14806 lines
699 KiB
Plaintext
14806 lines
699 KiB
Plaintext
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD> <20><><EFBFBD> <20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
<20><><EFBFBD>
|
|||
|
<20><><EFBFBD>
|
|||
|
<20><><EFBFBD> Online Software Programming Toolkit
|
|||
|
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>
|
|||
|
|
|||
|
Programmer's Manual
|
|||
|
|
|||
|
|
|||
|
Version 6.00
|
|||
|
|
|||
|
|
|||
|
DOS and Win32 Editions
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
NOTE: Since you will likely want to refer to this manual while
|
|||
|
working with OpenDoors, it is highly recommended that you take
|
|||
|
the time to print it out. Simply type COPY OPENDOOR.TXT PRN
|
|||
|
from your DOS prompt. With the exception of this title page,
|
|||
|
this document contains only 7-bit ASCII characters.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
(C) Copyright 1991 - 1996 by Brian Pirie. All Rights Reserved.
|
|||
|
|
|||
|
TABLE OF CONTENTS
|
|||
|
|
|||
|
|
|||
|
CHAPTER 1 - INTRODUCTION TO OPENDOORS.......................................5
|
|||
|
WELCOME! ...............................................................5
|
|||
|
FEATURES OF THE OPENDOORS TOOLKIT ......................................6
|
|||
|
|
|||
|
CHAPTER 2 - ABOUT THIS EVALUATION COPY AND ORDERING.........................9
|
|||
|
THE EVALUATION COPY & BENEFITS OF REGISTERING ..........................9
|
|||
|
HOW TO ORDER ...........................................................10
|
|||
|
HOW TO ORDER BY MAIL ...................................................11
|
|||
|
SENDING YOUR ORDER FEE IN THE MAIL .....................................12
|
|||
|
ORDERING BY CREDIT CARD ................................................14
|
|||
|
HOW YOU CAN RECEIVE YOUR ORDER .........................................15
|
|||
|
ORDERING THE SOURCE CODE ...............................................17
|
|||
|
OPENDOORS 6.00 ORDER FORM ..............................................18
|
|||
|
OPENDOORS 6.00 FEEDBACK FORM ...........................................19
|
|||
|
TERMS OF REGISTRATION AND SOURCE CODE USE ..............................20
|
|||
|
|
|||
|
CHAPTER 3 - OPENDOORS TUTORIAL..............................................21
|
|||
|
ABOUT THIS MANUAL ......................................................21
|
|||
|
COMPILING A PROGRAM WITH OPENDOORS .....................................22
|
|||
|
LINKING WITH OPENDOORS USING A DOS COMPILER ............................23
|
|||
|
LINKING WITH OPENDOORS USING A WINDOWS COMPILER ........................24
|
|||
|
RUNNING A DOOR PROGRAM WRITTEN WITH OPENDOORS ..........................26
|
|||
|
RUNNING DOS-BASED DOOR PROGRAMS ........................................26
|
|||
|
RUNNING WINDOWS 95/NT DOOR PROGRAMS ....................................26
|
|||
|
BASICS OF DOOR PROGRAMMING WITH OPENDOORS ..............................29
|
|||
|
TOUR OF A SAMPLE DOOR PROGRAM: "EX_VOTE" ...............................33
|
|||
|
OTHER EXAMPLE PROGRAMS INCLUDED WITH OPENDOORS .........................38
|
|||
|
|
|||
|
CHAPTER 4 - THE OPENDOORS API FUNCTIONS.....................................40
|
|||
|
OVERVIEW ...............................................................40
|
|||
|
TABLE OF MOST COMMONLY USED FUNCTIONS ..................................41
|
|||
|
TABLE OF ALL FUNCTIONS .................................................42
|
|||
|
OD_ADD_PERSONALITY() ...................................................47
|
|||
|
OD_AUTODETECT() ........................................................48
|
|||
|
OD_CHAT() ..............................................................50
|
|||
|
OD_CARRIER() ...........................................................51
|
|||
|
OD_CLEAR_KEYBUFFER() ...................................................53
|
|||
|
OD_CLR_LINE() ..........................................................55
|
|||
|
OD_CLR_SCR() ...........................................................57
|
|||
|
OD_COLOR_CONFIG() ......................................................59
|
|||
|
OD_DISP() ..............................................................60
|
|||
|
OD_DISP_EMU() ..........................................................62
|
|||
|
OD_DISP_STR() ..........................................................63
|
|||
|
OD_DRAW_BOX() ..........................................................65
|
|||
|
OD_EDIT_STR() ..........................................................68
|
|||
|
OD_EXIT() ..............................................................79
|
|||
|
OD_GET_ANSWER() ........................................................81
|
|||
|
OD_GET_INPUT() .........................................................82
|
|||
|
OD_GET_KEY() ...........................................................85
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 2
|
|||
|
|
|||
|
OD_GETTEXT() ...........................................................89
|
|||
|
OD_HOTKEY_MENU() .......................................................90
|
|||
|
OD_INIT() ..............................................................92
|
|||
|
OD_INPUT_STR() .........................................................95
|
|||
|
OD_KERNEL() ............................................................97
|
|||
|
OD_LIST_FILES() ........................................................98
|
|||
|
OD_LOG_WRITE() .........................................................100
|
|||
|
OD_MULTILINE_EDIT() ....................................................101
|
|||
|
OD_PAGE() ..............................................................104
|
|||
|
OD_PARSE_CMD_LINE() ....................................................105
|
|||
|
OD_POPUP_MENU() ........................................................107
|
|||
|
OD_PRINTF() ............................................................110
|
|||
|
OD_PUTCH() .............................................................115
|
|||
|
OD_PUTTEXT() ...........................................................116
|
|||
|
OD_REPEAT() ............................................................118
|
|||
|
OD_RESTORE_SCREEN() ....................................................120
|
|||
|
OD_SAVE_SCREEN() .......................................................121
|
|||
|
OD_SCROLL() ............................................................123
|
|||
|
OD_SEND_FILE() .........................................................124
|
|||
|
OD_SET_ATTRIB() ........................................................128
|
|||
|
OD_SET_COLOR() .........................................................131
|
|||
|
OD_SET_CURSOR() ........................................................134
|
|||
|
OD_SET_DTR() ...........................................................135
|
|||
|
OD_SET_PERSONALITY() ...................................................136
|
|||
|
OD_SET_STATUSLINE() ....................................................137
|
|||
|
OD_SLEEP() .............................................................139
|
|||
|
OD_SPAWN() .............................................................141
|
|||
|
OD_SPAWNVPE() ..........................................................143
|
|||
|
OD_WINDOW_CREATE() .....................................................145
|
|||
|
OD_WINDOW_REMOVE() .....................................................147
|
|||
|
|
|||
|
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE.................................148
|
|||
|
INTRODUCTION TO THE CONTROL STRUCTURE ..................................148
|
|||
|
CONTROL STRUCTURE - DOOR INFO FILE STATS ...............................150
|
|||
|
CONTROL STRUCTURE - SERIAL PORT SETTINGS ...............................153
|
|||
|
CONTROL STRUCTURE - BBS AND CALLER INFORMATION .........................158
|
|||
|
CONTROL STRUCTURE - DOOR SETTINGS ......................................182
|
|||
|
CONTROL STRUCTURE - DIAGNOSTICS ........................................185
|
|||
|
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ............................187
|
|||
|
CONTROL STRUCTURE - FUNCTION KEYS ......................................212
|
|||
|
CONTROL STRUCTURE - COLOR CUSTOMIZATION ................................216
|
|||
|
CONTROL STRUCTURE - TEXT CUSTOMIZATION .................................217
|
|||
|
|
|||
|
CHAPTER 6 - SPECIAL TOPICS..................................................220
|
|||
|
ADDITIONAL INFORMATION ON THE WIN32 VERSION ............................220
|
|||
|
CONFIGURATION FILE SYSTEM ..............................................225
|
|||
|
DEFINING CUSTOM DOOR INFORMATION FILE FORMATS ..........................230
|
|||
|
MULTIPLE PERSONALITY SYSTEM ............................................233
|
|||
|
LOG FILE SYSTEM ........................................................235
|
|||
|
MAKING DOORS MULTI-NODE-AWARE ..........................................237
|
|||
|
|
|||
|
CHAPTER 7 - TROUBLESHOOTING AND GETTING ASSISTANCE WITH OPENDOORS...........242
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 3
|
|||
|
|
|||
|
ABOUT THIS CHAPTER .....................................................242
|
|||
|
TROUBLESHOOTING PROBLEMS ...............................................242
|
|||
|
SOLUTIONS TO COMMON PROBLEMS ...........................................244
|
|||
|
OPENDOORS SUPPORT ......................................................245
|
|||
|
THE OPENDOORS SUPPORT BBS ..............................................245
|
|||
|
THE OPENDOORS WORD WIDE WEB SITE .......................................246
|
|||
|
THE OPENDOORS CONFERENCE ...............................................246
|
|||
|
GETTING IN TOUCH WITH ME ...............................................247
|
|||
|
|
|||
|
APPENDIX A - CONTENTS OF PACKAGE............................................249
|
|||
|
|
|||
|
APPENDIX B - CHANGES FOR THIS VERSION.......................................250
|
|||
|
|
|||
|
APPENDIX C - FUTURE VERSIONS................................................254
|
|||
|
|
|||
|
APPENDIX D - SPECIAL THANKS.................................................255
|
|||
|
|
|||
|
GLOSSARY....................................................................256
|
|||
|
|
|||
|
INDEX.......................................................................267
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 4
|
|||
|
|
|||
|
11
|
|||
|
111
|
|||
|
11
|
|||
|
11
|
|||
|
11
|
|||
|
11
|
|||
|
1111
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 1 - INTRODUCTION TO OPENDOORS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
WELCOME!
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
Welcome to OpenDoors! OpenDoors is a POWERFUL and EASY TO USE
|
|||
|
online software programming toolkit for C and C++. While
|
|||
|
OpenDoors is most often used to create add-on "door" programs
|
|||
|
that run under BBS systems, it can also be used for many other
|
|||
|
online software applications. By using OpenDoors, you are
|
|||
|
joining over 500 other programmers from around the world who
|
|||
|
have used it since it was first released to the public in 1991.
|
|||
|
Over the years, OpenDoors has grown from a simple BBS door
|
|||
|
programming library to what is perhaps the most sophisticated,
|
|||
|
widely used and supported package of its type.
|
|||
|
|
|||
|
What exactly is OpenDoors? OpenDoors provides a complete system
|
|||
|
that allows you to quickly and easily write spectacular,
|
|||
|
professional quality interactive online software. With
|
|||
|
OpenDoors, you can write software such as BBS door programs just
|
|||
|
as you would write any other program - without having to worry
|
|||
|
about the many of the internal details of door programming.
|
|||
|
OpenDoors looks after communicating through the modem, providing
|
|||
|
ANSI/AVATAR/RIP terminal support and interfacing with a wide
|
|||
|
variety of BBS packages through door information files (such as
|
|||
|
DOOR.SYS, DORINFO1.DEF, etc.). OpenDoors also looks after status
|
|||
|
lines and sysop function keys for DOS shells, chatting, hanging
|
|||
|
up, and so on. In addition, OpenDoors carries out all the work
|
|||
|
involved in keeping track of carrier detection, user timeouts
|
|||
|
and much, much more. OpenDoors is also highly flexible, allowing
|
|||
|
you to take as little or as much control of your program's
|
|||
|
behavior as you wish.
|
|||
|
|
|||
|
This package includes both DOS and Win32 versions of OpenDoors.
|
|||
|
This allows you to build a plain-DOS version of your program to
|
|||
|
run under a variety of platforms (DOS, DesqView, Windows 3.x,
|
|||
|
NT, 95 and OS/2), to build a Win32 version that takes special
|
|||
|
advantage of Windows 95 / NT, or build both versions of your
|
|||
|
program - the choice is yours. The DOS version of OpenDoors
|
|||
|
performs its serial I/O using either a FOSSIL driver, or built-
|
|||
|
in serial I/O capabilities, making the use of a FOSSIL driver
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 5
|
|||
|
|
|||
|
optional. The Win32 version takes special advantage of 32-bit
|
|||
|
programming, multithreading and the Windows GUI, and allows you
|
|||
|
to access many services that are provided by Windows, such as
|
|||
|
ODBC (for database access) and MAPI (for email and messaging).
|
|||
|
Both the DOS and Win32 versions of OpenDoors can be run under
|
|||
|
both DOS and Windows-based BBS packages. The DOS version of
|
|||
|
OpenDoors can also be run under OS/2-based BBS packages.
|
|||
|
|
|||
|
The following section provides more detailed information on the
|
|||
|
features and capabilities that OpenDoors provides.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
FEATURES OF THE OPENDOORS TOOLKIT
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
You will find that OpenDoors provides a solid platform to build
|
|||
|
BBS door programs and other online software on top of. You may
|
|||
|
want to write simple utility door programs, on-line games or
|
|||
|
sophisticated applications. Perhaps you are interested in
|
|||
|
getting into the market of selling online software, or perhaps
|
|||
|
you just wish to write some custom door programs for a
|
|||
|
particular BBS system. With OpenDoors, you can accomplish all of
|
|||
|
these things - and do it much more easily than ever before. Some
|
|||
|
of the features that OpenDoors provides to :
|
|||
|
|
|||
|
- OpenDoors handles all the "dirty" work involved in writing
|
|||
|
BBS door programs. Since OpenDoors looks after all the door-
|
|||
|
related operations for you, you need do next to nothing
|
|||
|
different when writing door programs than you would when
|
|||
|
writing any other program. You simply call OpenDoor's simple
|
|||
|
functions to input, output and control door operation. In
|
|||
|
fact, many people have converted non-door programs to door
|
|||
|
programs in only a matter of minutes using OpenDoors. One of
|
|||
|
the most common comments I receive about OpenDoors is how
|
|||
|
easy it is to use.
|
|||
|
|
|||
|
- OpenDoors allows you to write software that DIRECTLY support
|
|||
|
a wide variety of BBS systems, including RemoteAccess,
|
|||
|
QuickBBS, PC-Board, Maximus, Opus, Wildcat!, WWIV, Spitfire,
|
|||
|
SuperBBS, Telegard, TriBBS, GAP, and others.
|
|||
|
|
|||
|
- As you would expect, OpenDoors flawlessly monitors the
|
|||
|
modem's carrier detect signal, to automatically recover when
|
|||
|
a user hangs up - without your having to do anything extra in
|
|||
|
your program. OpenDoors also monitors how much time the user
|
|||
|
has left in the door, and provides a fully adjustable
|
|||
|
inactivity timeout monitor.
|
|||
|
|
|||
|
- OpenDoors takes care of all the work involved in reading and
|
|||
|
writing BBS door information files, such as DORINFO1.DEF,
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 6
|
|||
|
|
|||
|
EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, etc. If the particular
|
|||
|
information is available to OpenDoors, it will provide you
|
|||
|
with just about everything you could ever want to know about
|
|||
|
the user on-line, the system your door is running under, and
|
|||
|
so on. In addition to the many door information file formats
|
|||
|
supported by OpenDoors, you are also able to define your own
|
|||
|
custom formats.
|
|||
|
|
|||
|
- OpenDoors also does all the work involved in displaying and
|
|||
|
automatically updating the door's status line, with
|
|||
|
information available to the sysop such as user name,
|
|||
|
location, baud rate, time left, function keys,
|
|||
|
ANSI/AVATAR/RIP settings, and so on. Using OpenDoors, you can
|
|||
|
choose from a number of different "personalities". These
|
|||
|
personalities allows OpenDoors to mimic the status lines and
|
|||
|
sysop function keys used in various BBS packages. OpenDoors
|
|||
|
includes personalities that mimic RemoteAccess, PC-Board and
|
|||
|
Wildcat! OpenDoors also allows you to create your own
|
|||
|
personalities to mimic any other BBS system.
|
|||
|
|
|||
|
- OpenDoors automatically provides the sysop with all the
|
|||
|
standard function keys for adjusting user time, hanging up on
|
|||
|
or even locking out the user, and so on. OpenDoors also
|
|||
|
provides you with a chat mode, which is available to the
|
|||
|
sysop by pressing Alt-C. In addition, OpenDoors has full
|
|||
|
support for sysop shell to DOS, activated by the Alt-J key.
|
|||
|
|
|||
|
- What's more, OpenDoors is designed to be very easy to use.
|
|||
|
Even the most novice 'C' programmers are able to write
|
|||
|
professional-quality doors with OpenDoors. It takes care of
|
|||
|
just about every detail for you, yet still gives you the
|
|||
|
ability to completely control and customize every detail of
|
|||
|
your door's behavior. There are even people who begin door
|
|||
|
programming with OpenDoors, having never programmed in C in
|
|||
|
the past.
|
|||
|
|
|||
|
- OpenDoors supports both FOSSIL-based and built-in serial I/O
|
|||
|
capabilities. FOSSIL-based serial I/O can be used for maximum
|
|||
|
compatibility with various systems and serial ports,
|
|||
|
including multiple-port serial cards such as DigiBoard.
|
|||
|
OpenDoors can also operate without a FOSSIL driver, using
|
|||
|
it's own serial I/O capabilities. OpenDoor's built-in
|
|||
|
asynchronous communications supports baud rates of up to
|
|||
|
115,200 and non-standard serial port configurations.
|
|||
|
OpenDoors also has the ability to automatically detect which
|
|||
|
of the two serial I/O methods should be used on a particular
|
|||
|
system.
|
|||
|
|
|||
|
- OpenDoors also automatically detects when the BBS system is
|
|||
|
operating in local mode, and supports full local mode
|
|||
|
operations itself.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 7
|
|||
|
|
|||
|
- Other OpenDoors functions include a built in sysop-page
|
|||
|
function that will ask the user why they wish to chat, and
|
|||
|
then proceed to page the sysop, just as any BBS package
|
|||
|
would. OpenDoors also provides screen clearing functions
|
|||
|
(which will detect whether the user has screen clearing
|
|||
|
turned on), and various ANSI/AVATAR/RIP control functions
|
|||
|
(which again detect if the user has graphics mode turned on).
|
|||
|
|
|||
|
- In addition to the basic display features of OpenDoors there
|
|||
|
are also a number of advanced screen control functions. These
|
|||
|
include functions to save and restore the entire screen,
|
|||
|
along with functions to save, restore or scroll portions of
|
|||
|
the screen. Other functions allow you to provide overlapping
|
|||
|
windows and pop-up menus with highlighted selection bars.
|
|||
|
|
|||
|
- OpenDoors provides a multi-line text editor that you can use
|
|||
|
to allow the user to enter or edit text files, email
|
|||
|
messages, or any other text that spans multiple lines. You
|
|||
|
can customize many of the editor's settings to suit your
|
|||
|
needs.
|
|||
|
|
|||
|
- OpenDoors has a number of special sub-systems that you may
|
|||
|
elect to include in your doors. Among these, is a log-file
|
|||
|
system that allows you to add log file support to your doors
|
|||
|
with only a single line of programming.
|
|||
|
|
|||
|
- Another valuable OpenDoors sub-system is the configuration
|
|||
|
file system. Again using only a single line of code, you can
|
|||
|
add configuration file support to your doors. OpenDoors
|
|||
|
configuration files permit the sysop using the door to
|
|||
|
customize the door's behavior to their own preferences.
|
|||
|
|
|||
|
- OpenDoors can also be fully customized in order that you may
|
|||
|
write door programs that use languages other than English.
|
|||
|
|
|||
|
- Among the ANSI/AVATAR/RIP features found in OpenDoors is the
|
|||
|
ability to send ANSI/AVATAR/RIP files from disk. This allows
|
|||
|
you to easily design program screens, and incorporate them
|
|||
|
into your doors.
|
|||
|
|
|||
|
- OpenDoors also comes with the source code for a number of
|
|||
|
example doors, which you can modify, or simply extract bits
|
|||
|
and pieces for use in your own doors. Plus, this manual
|
|||
|
contains many examples of C source code, to help you in
|
|||
|
writing nearly any door program you might wish to build.
|
|||
|
|
|||
|
- You may also elect to purchase the source code for OpenDoors,
|
|||
|
which will permit you to make modifications to any portion of
|
|||
|
OpenDoors, use any portions of the OpenDoors source code in
|
|||
|
other programs you write, or merely learn how communications-
|
|||
|
type programs are written.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 8
|
|||
|
|
|||
|
2222
|
|||
|
22 22
|
|||
|
22
|
|||
|
22
|
|||
|
22
|
|||
|
22
|
|||
|
222222
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 2 - ABOUT THIS EVALUATION COPY AND ORDERING
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
THE EVALUATION COPY & BENEFITS OF REGISTERING
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
OpenDoors is distributed and sold using the conventional
|
|||
|
"shareware" approach. This complete package can be freely
|
|||
|
distributed, both online (through BBS systems and the Internet)
|
|||
|
and on CD-ROMs or other media. This gives you the chance to try
|
|||
|
OpenDoors before you buy it. Unlike traditional commercial
|
|||
|
software, you have the opportunity to see OpenDoors first-hand,
|
|||
|
and determine whether it meets your needs without first paying
|
|||
|
for it. However, before registering you are only permitted to
|
|||
|
use it under the following conditions:
|
|||
|
|
|||
|
1.)You may only use this package for a one month period, and
|
|||
|
for evaluation purposes only.
|
|||
|
|
|||
|
2.) Programs written with this package may not be distributed.
|
|||
|
|
|||
|
Also, before registering, any program written with OpenDoors
|
|||
|
will display a message to the user indicating that OpenDoors is
|
|||
|
not registered. Of course, this message is removed once you have
|
|||
|
registered.
|
|||
|
|
|||
|
If you decided to register OpenDoors, you will become the
|
|||
|
licensed owner of a powerful tool for creating BBS door programs
|
|||
|
and other online software. Registered (licensed) owners of
|
|||
|
OpenDoors are entitled to:
|
|||
|
|
|||
|
1.)Virtually unlimited use of OpenDoors. You may write as many
|
|||
|
programs as you wish using OpenDoors, and do what you please
|
|||
|
with these programs. They may be freely distributed, or even
|
|||
|
sold. What's more, there are no additional royalty fees.
|
|||
|
Your one time purchase of OpenDoors entitles you to use it
|
|||
|
as you please.
|
|||
|
|
|||
|
2.)Your registration entitles you to use both the DOS and Win32
|
|||
|
versions of OpenDoors.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 9
|
|||
|
|
|||
|
3.)You will also be entitled to free upgrades to newer versions
|
|||
|
of OpenDoors. In addition to the great many features and the
|
|||
|
quality that this version of OpenDoors has to offer, I am
|
|||
|
currently working on a great many additions and enhancements
|
|||
|
for the next version. (See the end of this document for an
|
|||
|
outline of features currently "in the works".) Any programs
|
|||
|
you write using this version will also automatically take on
|
|||
|
many of these new features when you upgrade to the new
|
|||
|
version.
|
|||
|
|
|||
|
|
|||
|
Perhaps the best news of all is the price of OpenDoors. Similar
|
|||
|
packages sell for $50, $75, or even more. However, this version
|
|||
|
of OpenDoors will only cost you $28 US Dollars, $34 Canadian
|
|||
|
Dollars, or the equivalent in your country's currency! (Note
|
|||
|
that this price will increase in future versions. By registering
|
|||
|
now, you will save by being able to upgrade to all future
|
|||
|
versions at no additional charge.)
|
|||
|
|
|||
|
Also, the source code for OpenDoors is now available to licensed
|
|||
|
users for an additional $28US / $34CDN / equivalent. Ordering a
|
|||
|
copy of the source code will allow you to customize OpenDoors
|
|||
|
for your own use, making any changes or additions that you wish.
|
|||
|
It also gives you the opportunity to see how OpenDoors works,
|
|||
|
and to use any portions of the OpenDoors code in any other
|
|||
|
programs you wish to write. If you think you might be interested
|
|||
|
in ordering the OpenDoors source code, please be sure to read
|
|||
|
the section entitled "Ordering The Source Code", located on page
|
|||
|
20.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
HOW TO ORDER
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
There are to ways of ordering and OpenDoors license
|
|||
|
(registration):
|
|||
|
|
|||
|
-The most common way to order is by mailing the OpenDoors order
|
|||
|
form along with a cheque, money order or cash to the address
|
|||
|
on this order form.
|
|||
|
|
|||
|
- You may order using a major credit card. OpenDoors credit card
|
|||
|
orders are handled by a third-party credit card order service,
|
|||
|
named PsL.
|
|||
|
|
|||
|
The following sections provide more information on how to order
|
|||
|
using each of these options.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 10
|
|||
|
|
|||
|
HOW TO ORDER BY MAIL
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
To order OpenDoors by mailing a cheque, money order or cash,
|
|||
|
simply follow these three steps:
|
|||
|
|
|||
|
1.) Fill out the registration form. Information on filling out
|
|||
|
the form is located on page 15.
|
|||
|
|
|||
|
2.) Send the appropriate payment, $28US/$34CDN/equivalent for
|
|||
|
the registration or $56US/$68CDN/equivalent for both the
|
|||
|
registration and source code. If you wish more detailed
|
|||
|
instructions on sending the registration fee, see the
|
|||
|
section that begins page on 12. Included in that section is
|
|||
|
a list of equivalent prices for a number of other
|
|||
|
countries.
|
|||
|
|
|||
|
3.) Send the above two items to me at:
|
|||
|
|
|||
|
Brian Pirie
|
|||
|
117 Cedarock Drive
|
|||
|
Kanata ON K2M 2H5
|
|||
|
Canada
|
|||
|
|
|||
|
|
|||
|
Many people who register OpenDoors also order the source code
|
|||
|
package. You may wish to consider the benefits of having the
|
|||
|
OpenDoors source code - it allows you to learn how OpenDoors and
|
|||
|
communications software is written, it allows you to modify and
|
|||
|
customize OpenDoors to suit your own preferences, and it also
|
|||
|
allows you to use portions of OpenDoors for other non-door
|
|||
|
programming projects. If you think you might also be interested
|
|||
|
in the OpenDoors source code, be sure to read the section on the
|
|||
|
source code, which begins on page 20.
|
|||
|
|
|||
|
Also, you may wish to send the OpenDoors feedback form (located
|
|||
|
on page 19), along with your registration. The feedback form
|
|||
|
gives you a chance to tell me what you think of OpenDoors, and
|
|||
|
what changes you would like to see in future versions. In fact,
|
|||
|
the majority of suggestions made on these forms in the past have
|
|||
|
already been implemented in the current version of OpenDoors.
|
|||
|
|
|||
|
If you have printed the OpenDoors manual, you can simply remove
|
|||
|
and mail the forms on pages 18 and 19. If you have not already
|
|||
|
printed a copy of the manual, and you have a printer, you can
|
|||
|
quickly print these forms by printing the ORDER.FRM file
|
|||
|
included in the OpenDoors distribution archive. (Type COPY
|
|||
|
ORDER.FRM PRN from your DOS prompt.)
|
|||
|
|
|||
|
NO PRINTER? Alternatively, if you do not have a printer, simply send a hand-
|
|||
|
written version of the order form.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 11
|
|||
|
|
|||
|
If you have any special instructions for me, or anything that
|
|||
|
you would like to say when you register, feel free to write this
|
|||
|
on the back of the registration form, or on a separate piece of
|
|||
|
paper.
|
|||
|
|
|||
|
When filling out the OpenDoors registration form, be sure to
|
|||
|
indicate how you would prefer to receive your OpenDoors
|
|||
|
registration key and/or source code. The following options are
|
|||
|
available:
|
|||
|
|
|||
|
- Having me send the registration and/or source code
|
|||
|
by conventional mail
|
|||
|
- Internet E-Mail (the fastest option)
|
|||
|
- By Fax
|
|||
|
- Having me call to your BBS
|
|||
|
- You calling the OpenDoors support BBS
|
|||
|
- FidoNet "CrashMail"
|
|||
|
|
|||
|
Once you have decided which means you would prefer to receive
|
|||
|
your order by, please read the detailed instructions on your
|
|||
|
order method, below. Also, if you are ordering the source code,
|
|||
|
please be sure to read the section on ordering the source code,
|
|||
|
which begins on page 20.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
SENDING YOUR ORDER FEE IN THE MAIL
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The price of OpenDoors is 34 Canadian Dollars, 28 U.S. Dollars,
|
|||
|
or equivalent for the registration. The source code costs an
|
|||
|
additional 34 Canadian Dollars, 28 U.S. Dollars, or equivalent.
|
|||
|
For your convenience, the equivalent value in a number of other
|
|||
|
country's currencies, at the time of this writing, is as
|
|||
|
follows:
|
|||
|
|
|||
|
-----------------------------------------------
|
|||
|
REGISTRATION
|
|||
|
REGISTRATION ONLY AND SOURCE CODE
|
|||
|
-----------------------------------------------
|
|||
|
34 Canadian Dollars 68 Canadian Dollars
|
|||
|
28 US Dollars 56 US Dollars
|
|||
|
18 British Pounds 36 British Pounds
|
|||
|
150 French Francs 300 French Francs
|
|||
|
44 German Marks 88 German Marks
|
|||
|
50 Netherland Gilders 100 Netherland Gilders
|
|||
|
39 Australian Dollars 78 Australian Dollars
|
|||
|
-----------------------------------------------
|
|||
|
|
|||
|
If you are ordering by mail, this order fee may be paid using
|
|||
|
any of the following methods:
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 12
|
|||
|
|
|||
|
|
|||
|
-Cheque or Money Order in Canadian currency, drawn upon a
|
|||
|
Canadian bank. In this case, your order fee will be either
|
|||
|
$34CDN for just the registration, or $68CDN for both the
|
|||
|
registration and source code.
|
|||
|
|
|||
|
-Cheque or Money Order in U.S. currency, drawn upon a U.S. bank.
|
|||
|
In this case, your order fee will be either $28US for just the
|
|||
|
registration, or $56US for both the registration and source
|
|||
|
code.
|
|||
|
|
|||
|
-An International Money Order or International Bank Draft
|
|||
|
(available from your bank, post office or companies such as
|
|||
|
American Express), in Canadian currency. Depending on the
|
|||
|
particular case, your order fee MAY be sent to me by the postal
|
|||
|
service, and you will mail your order form by itself. You
|
|||
|
should have the money order drawn in either $34CDN for just the
|
|||
|
registration, or $68CDN for both the registration and source
|
|||
|
code.
|
|||
|
|
|||
|
-A cheque drawn on any bank in the world, IN THAT COUNTRY'S
|
|||
|
CURRENCY, equivalent to 34 Canadian dollars. For instance, a
|
|||
|
cheque for the appropriate number of British Pounds, drawn on a
|
|||
|
British bank, is perfectly acceptable. However, I am unable to
|
|||
|
accept a cheque for $34 Canadian dollars, drawn on a British
|
|||
|
Bank. UNFORTUNATELY, THE BANKS IN CANADA ARE CURRENTLY
|
|||
|
UNWILLING TO ACCEPT EUROCHEQUES.
|
|||
|
|
|||
|
-Cash. Please note that it is not usually recommended that cash
|
|||
|
be sent in the mail, and that I cannot be responsible for any
|
|||
|
cash lost in the mail. Simply put, if you wish to order by
|
|||
|
cash, it is your responsibility to get the cash to me. However,
|
|||
|
if I do receive your order in the form of cash, it will be
|
|||
|
perfectly acceptable to me. I would like to mention that many
|
|||
|
people have already ordered OpenDoors by sending cash, and I
|
|||
|
have yet to run across any case of cash being lost in the mail.
|
|||
|
Nonetheless, if you wish to send cash, you may wish to consider
|
|||
|
doing so by registered mail, for your added security.
|
|||
|
|
|||
|
|
|||
|
If you are ordering OpenDoors from within Canada, you will most
|
|||
|
likely choose the first option (a Canadian cheque or money
|
|||
|
order). If you are ordering OpenDoors from within the United
|
|||
|
States, you will most likely choose the second option (an
|
|||
|
American cheque or money order). If you are ordering from
|
|||
|
outside Canada and the U.S., it would be ideal if you could send
|
|||
|
your fee by an international money order. However, it should be
|
|||
|
noted that any of the above order methods will be acceptable
|
|||
|
from any location. Also, it is quite possible that I may be able
|
|||
|
to accept other means of sending your order fee. If you are
|
|||
|
unsure about sending your order fee, please feel free to get in
|
|||
|
touch with me by any of the means listed on page 247.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 13
|
|||
|
|
|||
|
ORDERING BY CREDIT CARD
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This information applies to CREDIT CARD ORDERS ONLY. Please read
|
|||
|
this entire section before ordering OpenDoors by credit card.
|
|||
|
|
|||
|
In order to cover the additional costs of processing credit card
|
|||
|
orders, an $8 shipping and handling fee applies to all OpenDoors
|
|||
|
orders made through PsL. As such, the total prices you will pay
|
|||
|
are:
|
|||
|
|
|||
|
- Just registration ($28 + $8 Handling) = $36 U.S.
|
|||
|
- Registration and Source Code ($56 + $8 Handling) = $64 U.S.
|
|||
|
(All prices will be charged to your credit card in U.S.
|
|||
|
Dollars.)
|
|||
|
|
|||
|
You can order OpenDoors with MC, Visa, Amex, or Discover from
|
|||
|
Public (software) Library by calling 800-2424-PsL or 713-524-6394
|
|||
|
or by FAX to 713-524-6398 or by CIS Email to 71355,470. You can
|
|||
|
also order online through the World Wide Web. For more
|
|||
|
information on how to do this, visit the OpenDoors Web site.
|
|||
|
(Information on the OpenDoors web site is provided on page 246.)
|
|||
|
You can also mail credit card orders to PsL at P.O.Box 35705,
|
|||
|
Houston, TX 77235-5705. When ordering by phone, you must call
|
|||
|
between 6:00am and 6:00pm CST on Monday to Thursday, or between
|
|||
|
6:00am and 12:30pm on Fridays.
|
|||
|
|
|||
|
THE ABOVE NUMBERS ARE FOR CREDIT CARD ORDERS ONLY.
|
|||
|
THE AUTHOR OF THIS PROGRAM CANNOT BE REACHED AT THESE NUMBERS.
|
|||
|
|
|||
|
Any questions about the status of the shipment of the order,
|
|||
|
refunds, registration options, product details, technical
|
|||
|
support, volume discounts, dealer pricing, site licenses, non-
|
|||
|
credit card orders, etc., must be directed to:
|
|||
|
|
|||
|
Brian Pirie
|
|||
|
117 Cedarock Drive
|
|||
|
Kanata ON K2M 2H5
|
|||
|
Canada
|
|||
|
|
|||
|
To insure that you get the latest version, PsL will notify me the
|
|||
|
day of your order and I will ship OpenDoors directly to you. I
|
|||
|
will send OpenDoors by conventional mail unless I have previously
|
|||
|
heard from you, asking me to send your order by some other means.
|
|||
|
|
|||
|
When ordering by credit card through PsL, please be sure to
|
|||
|
indicate whether you wish to order just the OpenDoors
|
|||
|
registration, or both the registration and source code. Also,
|
|||
|
please be sure to include your credit card billing address.
|
|||
|
Without this information, PsL will be unable to process your
|
|||
|
order.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 14
|
|||
|
|
|||
|
HOW YOU CAN RECEIVE YOUR ORDER
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
For your convenience, I can send your OpenDoors registration key
|
|||
|
and/or source code by any of the following methods. If you are
|
|||
|
ordering OpenDoors by mail, simply check one of these options on
|
|||
|
your order form. If you are ordering through the third-party
|
|||
|
credit card service, I will automatically send your order by
|
|||
|
Internet email or conventional mail unless I receive a message
|
|||
|
from you before you order, asking me to send it by some other
|
|||
|
means.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING If you wish to receive your OpenDoors registration key by
|
|||
|
ORDER BY Internet E-Mail (including Internet E-Mail to a CompuServe
|
|||
|
INTERNET account), fill out the order form and mail it along with your
|
|||
|
E-MAIL payment as described below. Be sure to include your e-mail
|
|||
|
address on your order form. Note that the source code cannot be
|
|||
|
sent via Internet e-mail.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING In order to receive your OpenDoors registration key and/or
|
|||
|
ORDER source code by conventional mail, simply fill out the order
|
|||
|
BY MAIL form and mail it along with your payment as described below. I
|
|||
|
will cover the cost of postage. If your address contains non-
|
|||
|
Roman characters, also enclose a self-addressed envelope or
|
|||
|
mailing label.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING If you wish to receive your OpenDoors registration key by
|
|||
|
ORDER BY FAX, fill out the order form and mail it along with your payment
|
|||
|
FAX as described below. Be sure to include your fax number on your
|
|||
|
order form. Do to choose this method if you are ordering the
|
|||
|
source code.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING You may choose to receive your OpenDoors registration and/or
|
|||
|
ORDER BY source code by calling the OpenDoors BBS after your registration
|
|||
|
CALLING form and order fee have been received here. If you are unable to
|
|||
|
OPENDOORS receive your order by any other electronic means (such as a call
|
|||
|
BBS to your BBS, or by electronic mail), this may be the quickest
|
|||
|
way for you to receive your registration information and/or
|
|||
|
source code. The obvious disadvantage with to option is the fact
|
|||
|
that you will have to estimate when your order will arrive here
|
|||
|
in order to receive it as quickly as possible. You may end up
|
|||
|
calling the OpenDoors BBS more than once before your order has
|
|||
|
arrived. After your order form has arrived, your registration
|
|||
|
key and/or source code will be placed on hold for you, and you
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 15
|
|||
|
|
|||
|
will be able to receive it on your first call to the BBS. The
|
|||
|
phone number of the BBS is:
|
|||
|
|
|||
|
+1 (613) 599-5554
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING In order to receive your OpenDoors registration key and/or
|
|||
|
ORDER BY source code by a message and/or upload to your BBS, fill out
|
|||
|
CALL TO the order form and mail it along with your payment as described
|
|||
|
YOUR BBS below. Be sure to include the phone number, baud rate, and my
|
|||
|
login and password for the BBS to which you would like me to
|
|||
|
call. As always, I will cover any long distance costs. If, for
|
|||
|
some reason, I am unable to connect to your BBS (not because it
|
|||
|
is busy, but, for example, if your BBS is no longer online), I
|
|||
|
will send your order by conventional mail instead.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
RECEIVING In order to receive your OpenDoors registration key and/or
|
|||
|
ORDER BY source code by FidoNet CrashMail, simply fill out the order
|
|||
|
FIDONET form and mail it along with your payment as described below.
|
|||
|
CRASHMAIL Be sure to include the FidoNet node address to which you wish to
|
|||
|
have your registration key and/or source code sent to (via
|
|||
|
CrashMail). Again I will cover any long distance costs. If, for
|
|||
|
some reason, I am unable to connect to your FidoNet system, I
|
|||
|
will send your order by conventional mail instead.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 16
|
|||
|
|
|||
|
ORDERING THE SOURCE CODE
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
Many people also choose to order the source code along with
|
|||
|
their OpenDoors registration. Ordering the source code will
|
|||
|
allow you to customize OpenDoors for your own use, use parts of
|
|||
|
the OpenDoors source code in other programs, and learn more
|
|||
|
about how OpenDoors works. If you have any ideas for changes
|
|||
|
that you would like to see in OpenDoors, either large or small,
|
|||
|
ordering the source code will allow you to makes these changes
|
|||
|
yourself, creating your own customized version of OpenDoors. You
|
|||
|
will be able to remove copyright notices, change the way certain
|
|||
|
OpenDoors functions work, or add new capabilities to OpenDoors
|
|||
|
in surprisingly little time. You will also be able to use any of
|
|||
|
the OpenDoors source code, be it the DesqView-aware code,
|
|||
|
EMS/disk swapping routines, configuration file system,
|
|||
|
communications routines, or anything else, in any other programs
|
|||
|
that you write. Also, ordering the OpenDoors source code will
|
|||
|
allow you to learn more about how OpenDoors works, and how to
|
|||
|
program communications software and BBS door programs.
|
|||
|
|
|||
|
When you order the OpenDoors source code, you will receive the
|
|||
|
source code package. The source code package also includes a
|
|||
|
short "Source Code Manual", with a description of how the
|
|||
|
OpenDoors source code is organized, instructions on how to
|
|||
|
recompile the source code, and more. If you choose to receive
|
|||
|
the source code package electronically, you will receive it in
|
|||
|
the form of a single .ZIP file. If you choose to receive the
|
|||
|
source code package by mail, you will receive it on a 3-1/2"
|
|||
|
diskette.
|
|||
|
|
|||
|
REQUIREMENTS Due to the wide variety of compilers that are available, and the
|
|||
|
differences between them, I have been unable to test the
|
|||
|
OpenDoors source code with every compiler. This means that you
|
|||
|
may need to make some changes to the source code in order to
|
|||
|
compile it with certain compilers.
|
|||
|
|
|||
|
In order to compile the DOS version of OpenDoors, you must be
|
|||
|
using a compiler that supports inline assembly language
|
|||
|
keywords. This includes all Borland compilers released since
|
|||
|
1991, and many other compilers. The one notable exception is
|
|||
|
Watcom's compiler, which does not support inline assembly
|
|||
|
language at the time of this writing.
|
|||
|
|
|||
|
For your information, the DOS OpenDoors libraries included with
|
|||
|
this package were compiled using Turbo C++ 1.0 Professional. The
|
|||
|
Win32 libraries included with this package were compiled using
|
|||
|
Microsoft Visual C++ 2.0. This means that you can be reasonably
|
|||
|
certain that OpenDoors will compile with these compilers and any
|
|||
|
more recent compilers by these companies without any changes.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 17
|
|||
|
|
|||
|
--------------------------------------------------------------------------
|
|||
|
OPENDOORS 6.00 ORDER FORM
|
|||
|
--------------------------------------------------------------------------
|
|||
|
|
|||
|
REGISTRATION NAME : _______________________________ (AS SHOULD APPEAR IN
|
|||
|
REGISTRATION)
|
|||
|
YOUR NAME : _______________________________ (IF DIFFERENT)
|
|||
|
|
|||
|
POSTAL ADDRESS : ______________________________________________________
|
|||
|
|
|||
|
______________________________________________________
|
|||
|
|
|||
|
______________________________________________________
|
|||
|
|
|||
|
E-MAIL ADDRESSES : ____________________________________ (IF APPLICABLE)
|
|||
|
|
|||
|
ADDITIONAL INFO : ______________________________________________________
|
|||
|
(EG FAX/BBS PHONE NUMBER & BRIAN'S PASSWORD, IF NEEDED)
|
|||
|
|
|||
|
I WISH TO RECEIVE MY ORDER BY:
|
|||
|
___ ___
|
|||
|
| | - INTERNET E-MAIL (FASTEST) | | - I WILL CALL BRIAN'S BBS
|
|||
|
|___| |___|
|
|||
|
___ ___
|
|||
|
| | - CONVENTIONAL MAIL | | - CALL TO MY BBS
|
|||
|
|___| |___| (INCLUDE LOGIN INFO)
|
|||
|
___ ___
|
|||
|
| | - FAX (INCLUDE FAX #) | | - FIDONET "CRASHMAIL"
|
|||
|
|___| |___|
|
|||
|
|
|||
|
___
|
|||
|
I WOULD LIKE TO ORDER: | | - BOTH REGISTRATION KEY AND SOURCE CODE
|
|||
|
|___| ($56 US, $68 CANADIAN, OR EQUIVALENT FUNDS)
|
|||
|
___
|
|||
|
| | - JUST MY REGISTRATION KEY
|
|||
|
|___| ($28 US, $34 CANADIAN, OR EQUIVALENT FUNDS)
|
|||
|
___
|
|||
|
| | - UPGRADE TO SOURCE CODE (ONLY IF ALREADY
|
|||
|
|___| REGISTERED) ($28 US, $34 CANADIAN OR EQUIV.)
|
|||
|
|
|||
|
|
|||
|
I AGREE TO THE REGISTRATION TERMS, ____________________________
|
|||
|
SET FORTH ON PAGE 20 OF THE MANUAL (SIGNATURE)
|
|||
|
|
|||
|
MAKE CHEQUES PAYABLE TO: BRIAN PIRIE
|
|||
|
117 CEDAROCK DRIVE
|
|||
|
KANATA ON K2M 2H5
|
|||
|
CANADA
|
|||
|
+-- OFFICIAL USE ONLY ----------------------------------------------------+
|
|||
|
| |
|
|||
|
| S.N. : _____________ SENT : _________________________________________ |
|
|||
|
+-------------------------------------------------------------------------+
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 18
|
|||
|
|
|||
|
--------------------------------------------------------------------------
|
|||
|
OPENDOORS 6.00 FEEDBACK FORM
|
|||
|
--------------------------------------------------------------------------
|
|||
|
|
|||
|
YOUR NAME : _______________________________
|
|||
|
|
|||
|
|
|||
|
WHICH OPENDOORS LIBRARY(S) DO YOU EXPECT TO USE:
|
|||
|
___
|
|||
|
| | - DOS VERSION, MEMORY MODELS: _________________________
|
|||
|
|___|
|
|||
|
___
|
|||
|
| | - WINDOWS (WIN32) VERSION
|
|||
|
|___|
|
|||
|
|
|||
|
|
|||
|
HOW DID YOU FIRST LEARN OF OPENDOORS?
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
|
|||
|
WHICH COMPILER(S) AND VERSION(S) ARE YOU USING?
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
|
|||
|
WHAT DO YOU LIKE MOST ABOUT OPENDOORS?
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
|
|||
|
WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS?
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
|
|||
|
DO YOU HAVE ANY ADDITIONAL COMMENTS?
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
____________________________________________________________
|
|||
|
|
|||
|
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 19
|
|||
|
|
|||
|
TERMS OF REGISTRATION AND SOURCE CODE USE
|
|||
|
-----------------------------------------------------------------------------
|
|||
|
|
|||
|
When you purchase an OpenDoors registration and/or source code
|
|||
|
license, you are entitled to almost unlimited use of all
|
|||
|
versions of OpenDoors. However, in order to protect my
|
|||
|
investment of time and effort in developing OpenDoors, you must
|
|||
|
also agree to the terms outlined below when licensing OpenDoors
|
|||
|
and/or the source code. These terms are intended to be very
|
|||
|
reasonable, and are in no way intended to limit your use of
|
|||
|
OpenDoors. The primary intent of these terms is that you are not
|
|||
|
permitted to disclose your OpenDoors registration information,
|
|||
|
or the OpenDoors source code, to other individuals. The terms of
|
|||
|
registration and source code use are as follows:
|
|||
|
|
|||
|
For the purpose of these terms, "OpenDoors" is defined to be the
|
|||
|
library files, header files, example programs and programmer's
|
|||
|
manual of all versions, past and present, for all languages and
|
|||
|
platforms of the OpenDoors online software programming toolkit.
|
|||
|
In the case of a source code license, OpenDoors also refers to
|
|||
|
the source code that is used to build OpenDoors. Upon licensing
|
|||
|
OpenDoors, the individual or organization named on the order
|
|||
|
form (the licensee) is entitled to use of all versions of
|
|||
|
OpenDoors, within the terms set forth below. Violation of these
|
|||
|
terms will be considered copyright infringement, and grounds for
|
|||
|
the termination of the registration agreement. The licensee is
|
|||
|
entitled, at no additional cost, to use, distribute or sell the
|
|||
|
executable (.EXE or .COM) files that are built from OpenDoors.
|
|||
|
The licensee is also entitled to use, distribute or sell the
|
|||
|
example programs, example configuration files and portions of
|
|||
|
the manual. If licensing the source code, the licensee is also
|
|||
|
entitled to distribute or sell any executable files that result
|
|||
|
from using altered versions of the source code, or portions
|
|||
|
thereof, provided that it is not possible for other programmers
|
|||
|
to access the OpenDoors API functions through this executable
|
|||
|
file. The licensee is NOT entitled to distribute the
|
|||
|
registration key number that is provided by Brian Pirie, nor any
|
|||
|
portions of the OpenDoors source code. For the purposes of these
|
|||
|
terms, an organization is considered to be a company or non-
|
|||
|
profit organization. If the licensee is an organization, the
|
|||
|
registration key and source code may be shared among members of
|
|||
|
the organization, under the condition that these individuals are
|
|||
|
using the registration and/or source code only for official
|
|||
|
activities of that organization. These terms in no way suggest
|
|||
|
an agreement on the part of Brian Pirie to develop any future
|
|||
|
versions of OpenDoors, or fix any bugs in current versions of
|
|||
|
OpenDoors. OpenDoors is offered "as is", and no warrantees are
|
|||
|
expressed or implied. In no event shall Brian Pirie be liable
|
|||
|
for any loss of profit or any other damage, including but not
|
|||
|
limited to special, incidental, consequential or other damages.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 20
|
|||
|
|
|||
|
3333
|
|||
|
33 33
|
|||
|
33
|
|||
|
333
|
|||
|
33
|
|||
|
33 33
|
|||
|
3333
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 3 - OPENDOORS TUTORIAL
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
ABOUT THIS MANUAL
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors programmer's manual is intended to serve as a
|
|||
|
complete tutorial, guide and reference to writing programs with
|
|||
|
OpenDoors. Chapter 1 of this manual, beginning on page 5,
|
|||
|
provides an introduction and overview of the features of
|
|||
|
OpenDoors. If you are unsure of what OpenDoors will do for you,
|
|||
|
begin with Chapter 1. Chapter 2, beginning on page 9, provides
|
|||
|
important information related to this evaluation copy of
|
|||
|
OpenDoors, and how to register your copy. Chapter 3 serves as a
|
|||
|
tutorial on OpenDoors and BBS door programming in general.
|
|||
|
Chapter 4 provides a reference to the OpenDoors API functions
|
|||
|
which you can use in your programs. Chapter 5 provides a
|
|||
|
reference to the "OpenDoors control structure", which gives you
|
|||
|
access to a wide array of information, and allows you to
|
|||
|
customize OpenDoor's appearance and behavior. Chapter 6 provides
|
|||
|
information on special OpenDoors features and advanced door
|
|||
|
programming topics. Among the subjects discussed in chapter 6
|
|||
|
are the Win32 version of OpenDoors, configuration files, multi-
|
|||
|
node operation, RIP graphics, logfile support, defining custom
|
|||
|
door information file formats, and more.
|
|||
|
|
|||
|
Chapter 7 (which begins on page 242) gives instructions on
|
|||
|
troubleshooting programs written with OpenDoors, lists solutions
|
|||
|
to common difficulties, and has information about the many
|
|||
|
sources for OpenDoors support. If at any time you are having
|
|||
|
difficulty with OpenDoors, be sure to refer to this chapter for
|
|||
|
complete step-by-step instruction on tracing the source of your
|
|||
|
problem, and for solutions to common difficulties with
|
|||
|
OpenDoors. This chapter also directs you to some of the major
|
|||
|
sources of support, including information on the OpenDoors email
|
|||
|
conference, the OpenDoors support BBS, and how to get in touch
|
|||
|
with me.
|
|||
|
|
|||
|
You will also find many useful tools in this manual, which will
|
|||
|
no doubt come in useful while working with OpenDoors. Beginning
|
|||
|
on page 2 is a basic table of contents, showing you how the
|
|||
|
manual is organized, and helping you to locate general topics.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 21
|
|||
|
|
|||
|
At the end of the manual, beginning on page 267, is an index to
|
|||
|
help you locate more information on specific topics. The manual
|
|||
|
also includes a glossary, on page 256, which will help you in
|
|||
|
understanding new terms that you may come across while reading
|
|||
|
the manual. At the end of the manual, you will also find several
|
|||
|
useful sections, such as information on what is new in this
|
|||
|
version, information on how to contact me, and information about
|
|||
|
new OpenDoors features currently in the works.
|
|||
|
|
|||
|
You will likely want to print this manual, to make reading and
|
|||
|
reference while programming easier. To print this manual, simply
|
|||
|
type the following line from your DOS prompt. If you are worried
|
|||
|
about the size of this manual, you might consider using a
|
|||
|
utility that can print multiple pages of a text file on a single
|
|||
|
sheet of paper. Printing two manual pages per side of paper
|
|||
|
should certainly be legible, and even four-up would give you
|
|||
|
text about the size of average newspaper text. Printing on both
|
|||
|
sides, you should be able to fit the manual on about 34 sheets
|
|||
|
of paper (269/8 < 34).
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
COMPILING A PROGRAM WITH OPENDOORS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The process of compiling a program written with OpenDoors is
|
|||
|
very similar to that of compiling any other program. However,
|
|||
|
there are two additional steps which you must be sure to
|
|||
|
remember:
|
|||
|
|
|||
|
1.) You must include the OPENDOOR.H header file.
|
|||
|
|
|||
|
2.) You must link your program with the appropriate OpenDoors
|
|||
|
library file.
|
|||
|
|
|||
|
|
|||
|
All programs written with OpenDoors, must "include" the
|
|||
|
OPENDOOR.H header file. If you have placed the OPENDOOR.H header
|
|||
|
file in the same directory as your program's source code, place
|
|||
|
the following line at the beginning of your .C or .CPP file(s):
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
If you have placed the OPENDOOR.H header file in the same
|
|||
|
directory as other standard header files (such as stdio.h),
|
|||
|
place the following line at the beginning of your .C or .CPP
|
|||
|
file(s):
|
|||
|
|
|||
|
#include <opendoor.h>
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 22
|
|||
|
|
|||
|
In addition to including the OpenDoors header file in your
|
|||
|
source code modules, you must also "link" the appropriate
|
|||
|
OpenDoors library file with your program. The procedure for
|
|||
|
doing this depends upon which compiler you are using. The
|
|||
|
following sections describe how to link with the OpenDoors
|
|||
|
libraries using various compilers.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
LINKING WITH OPENDOORS USING A DOS COMPILER
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section describes how to link with the provided OpenDoors
|
|||
|
library files under a variety of DOS compilers. If you are using
|
|||
|
a compiler other than those described here, refer to your
|
|||
|
compiler's manual for information on how to link with third-
|
|||
|
party libraries.
|
|||
|
|
|||
|
If you are using Borland Turbo C 2.00 or earlier, you can cause
|
|||
|
your compiler to link your program with the OpenDoors library by
|
|||
|
creating a text file with a .PRJ extension. In this text file,
|
|||
|
you should list the names of your program's .C modules, along
|
|||
|
with the name of the appropriate OpenDoors library file, as
|
|||
|
listed in the table at the end of this section. You should then
|
|||
|
select this Project file from within the Turbo C IDE prior to
|
|||
|
compiling your program.
|
|||
|
|
|||
|
If you are using Turbo C++ or Borland C++, you can set your
|
|||
|
compiler to link your program with the OpenDoors library by
|
|||
|
creating a project file from within the IDE. To do this, choose
|
|||
|
the Open Project command from the Project menu, and enter the
|
|||
|
name for your new project file in the Load Project dialog box.
|
|||
|
Then add the names of your program's .C/.CPP modules, along with
|
|||
|
the name of the appropriate OpenDoors library file, by pressing
|
|||
|
[Insert] in the project window. When you return to Turbo C++ or
|
|||
|
Borland C++ again, you can work with the same project file by
|
|||
|
using the Open command from the Project menu.
|
|||
|
|
|||
|
If you are using any Microsoft C compiler, such as Quick C,
|
|||
|
Microsoft C or Visual C++, you can set your compiler to link
|
|||
|
your program with the OpenDoors library by creating a makefile.
|
|||
|
You can create a new project file from within Quick C by using
|
|||
|
the Set Program List option from the Make menu. You can do this
|
|||
|
from within Visual C++ by using the New command from the Project
|
|||
|
menu. You should add the names of your program's .C/.CPP source
|
|||
|
files, along with the name of the appropriate OpenDoors library
|
|||
|
file, to the newly create makefile.
|
|||
|
|
|||
|
There are several different DOS library files included with
|
|||
|
OpenDoors, each one for use with a different memory model. The
|
|||
|
following chart lists the library file names, along with their
|
|||
|
corresponding memory model. It is important that you use the
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 23
|
|||
|
|
|||
|
library file which corresponds to the memory model you are
|
|||
|
using. Whenever you change your compiler to use a different
|
|||
|
memory model, it is important to rebuild all of your source
|
|||
|
files (using the "Build All" or "Rebuild All" command) in
|
|||
|
addition to changing the library that your program is being
|
|||
|
linked with. If you are unfamiliar with the concept of memory
|
|||
|
models, you should refer to your compiler's manuals. If you are
|
|||
|
unsure as to what memory model your compiler is currently using,
|
|||
|
check this setting in the compile options dialog box or command
|
|||
|
line reference information.
|
|||
|
|
|||
|
+------------------------------------------------+
|
|||
|
| Library | Memory |
|
|||
|
| Filename | Model |
|
|||
|
|-------------|----------------------------------|
|
|||
|
| ODOORS.LIB | DOS small memory model library |
|
|||
|
| | |
|
|||
|
| ODOORM.LIB | DOS medium memory model library |
|
|||
|
| | (Available separately) |
|
|||
|
| | |
|
|||
|
| ODOORC.LIB | DOS compact memory model library |
|
|||
|
| | (Available separately) |
|
|||
|
| | |
|
|||
|
| ODOORL.LIB | DOS large memory model library |
|
|||
|
| | |
|
|||
|
| ODOORH.LIB | DOS huge memory model library |
|
|||
|
+------------------------------------------------+
|
|||
|
|
|||
|
To understand how to compile a program written with OpenDoors,
|
|||
|
it is a good idea to try compiling one of the example programs,
|
|||
|
such as ex_hello.c, that are included in the OpenDoors package.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
LINKING WITH OPENDOORS USING A WINDOWS COMPILER
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The Win32 version of OpenDoors resides in a DLL, ODOORS60.DLL.
|
|||
|
In order to use OpenDoors from a Win32 program, you will
|
|||
|
typically link to an import library (although it is also
|
|||
|
possible to use load-time dynamic linking through the use of
|
|||
|
LoadLibrary() and GetProcAddress()). The OpenDoors package
|
|||
|
includes a COFF-format import library for use Microsoft
|
|||
|
compilers, named ODOORW.LIB. If you are using a compiler that
|
|||
|
uses OMF-format object files, such as a Borland compiler, you
|
|||
|
will need to create your own version of the odoorw.lib import
|
|||
|
library, by using the implib utility provided with your
|
|||
|
compiler.
|
|||
|
|
|||
|
When compiling an OpenDoors program with a Windows compiler, be
|
|||
|
sure that either the WIN32 or __WIN32__ constant is defined.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 24
|
|||
|
|
|||
|
Microsoft and Borland compilers define one of these constants by
|
|||
|
default. However, if you are using a compiler from another
|
|||
|
company, you may need to explicitly configure your compiler to
|
|||
|
define one of these preprocessor constants.
|
|||
|
|
|||
|
If you are using Microsoft Visual C++ 2.0 or later, you can
|
|||
|
setup your compiler to link with the OpenDoors import library by
|
|||
|
creating a makefile (choose File|New|Project) and adding both
|
|||
|
your program's .C/.CPP source file(s) and the odoorw.lib import
|
|||
|
library to the project. When prompted for the Project type,
|
|||
|
choose "Application", not a "MFC AppWizard". If you are using
|
|||
|
Visual C++ 2.0, then you must manually edit the .mak file using
|
|||
|
a text editor. In this file, replace all occurrences of
|
|||
|
"/SUBSYSTEM:windows" with "/SUBSYSTEM:windows,4.0". This
|
|||
|
instructs the linker to create an executable file that is
|
|||
|
targeted for Windows 95. If you do not do this, some of the
|
|||
|
OpenDoors visual elements will not appear correctly. Later
|
|||
|
versions of Microsoft's compiler default to using
|
|||
|
"/SUBSYSTEM:windows,4.0", and so this step is no longer
|
|||
|
necessary with those compilers.
|
|||
|
|
|||
|
If you are using Borland C++ 4.50 or later, you must create an
|
|||
|
OpenDoors import library for ODOORS60.DLL before you can compile
|
|||
|
your first OpenDoors program. To do this, go to the directory
|
|||
|
where ODOORS60.DLL is located, move the original odoorw.lib to a
|
|||
|
backup location, and issue the command:
|
|||
|
|
|||
|
IMPLIB ODOORW.LIB ODOORS60.DLL
|
|||
|
|
|||
|
This will create a new import library (ODOORW.LIB) which you can
|
|||
|
then use with your compiler. To compile an OpenDoors program
|
|||
|
from the command line, issue the command:
|
|||
|
|
|||
|
BCC32 -tW your_program.c ODOORW.LIB
|
|||
|
|
|||
|
To compile an OpenDoors program from within the IDE, create a
|
|||
|
new project file, and add both your program's source file(s) and
|
|||
|
the OpenDoors import library to that project. If you are
|
|||
|
compiling from within the IDE, check the TargetExpert and be
|
|||
|
sure that you are using the multithreaded version of the the
|
|||
|
runtime libraries. By default, the Borland IDE compiles single-
|
|||
|
threaded, which will not work with OpenDoors.
|
|||
|
|
|||
|
Additional information on the Win32 version of OpenDoors is
|
|||
|
provided in chapter 6.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 25
|
|||
|
|
|||
|
RUNNING A DOOR PROGRAM WRITTEN WITH OPENDOORS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section provides information on how to run a BBS door
|
|||
|
program that has been written with OpenDoors. If you are using
|
|||
|
OpenDoors to write some other form of online software, the
|
|||
|
information provided here will apply to different degrees,
|
|||
|
depending on the nature of your program.
|
|||
|
|
|||
|
OpenDoors supports both local and remote modes. In the normal
|
|||
|
mode of operation, remote mode, your program's output will be
|
|||
|
displayed to both the local screen and the remote user's screen.
|
|||
|
To run your program in remote mode, you will usually set it up
|
|||
|
to run under some BBS package. However, for testing purposes, it
|
|||
|
is often convenient to run your program in local mode.
|
|||
|
|
|||
|
There are several ways to start your program in local mode. The
|
|||
|
first method is to place the example DORINFO1.DEF file in the
|
|||
|
same directory as your program. If your program uses the
|
|||
|
OpenDoors command line processing function, od_parse_cmd_line(),
|
|||
|
then you can start your program in local mode by simply
|
|||
|
specifying -local on your program's command line. For example,
|
|||
|
you can try the example program include with OpenDoors by
|
|||
|
issuing the command VOTEDOS -LOCAL (for the DOS version) or
|
|||
|
VOTEWIN -LOCAL (for the Windows 95/NT version). OpenDoors will
|
|||
|
also run in local mode if you set it up to run under a BBS
|
|||
|
package, and log into the BBS in local mode. When the BBS runs
|
|||
|
your door program, OpenDoors will automatically run in local
|
|||
|
mode.
|
|||
|
|
|||
|
To run your program in remote mode, you will probably want to
|
|||
|
run it under a BBS system. If you don't have a BBS package for
|
|||
|
testing purposes, you might want to obtain a popular BBS package
|
|||
|
such as Wildcat!, Maximus (which is free) or RemoteAccess.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
RUNNING DOS-BASED DOOR PROGRAMS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
DOS BBS packages typically run door programs using one of two
|
|||
|
methods. Either the BBS package directly loads and executes the
|
|||
|
program, or it exits to a DOS batch file, which in turn executes
|
|||
|
the door program. In either case, the BBS package produces a
|
|||
|
door information file, common called a "drop file", which
|
|||
|
provides information to the door program such as the name of the
|
|||
|
current user. OpenDoors automatically supports the common drop
|
|||
|
file formats, including DORINFOx.DEF and DOOR.SYS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
RUNNING WINDOWS 95/NT DOOR PROGRAMS
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 26
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section provides information specific to running door
|
|||
|
programs that are compiled with the Win32 version of OpenDoors.
|
|||
|
Please feel free to include this information in your program's
|
|||
|
manual.
|
|||
|
|
|||
|
Since the Win32 version of OpenDoors resides in a DLL,
|
|||
|
ODOORS60.DLL, this file must be present on any system where your
|
|||
|
program will be run. Although Windows 95/NT will find this file
|
|||
|
if it is located in the same directory as your program's
|
|||
|
executable file, it is a good idea to install this DLL into the
|
|||
|
Windows system directory. This way, all programs using the Win32
|
|||
|
version of OpenDoors can share the same copy of the DLL,
|
|||
|
reducing the amount of disk space that is used.
|
|||
|
|
|||
|
The required setup for a Windows 95/NT door will depend upon
|
|||
|
what BBS system it is being run under. If you the program is
|
|||
|
being run under a native Windows 95/NT BBS system, then ideally
|
|||
|
that BBS system will provide the ability to pass a live serial
|
|||
|
port handle to the door program, on the program's command line.
|
|||
|
Otherwise, you should run the door from a batch file, following
|
|||
|
the instructions provided below for running the program under a
|
|||
|
DOS-based BBS system. If the BBS system is able to pass a live
|
|||
|
Window communications handle on the door's command line, and you
|
|||
|
are using the OpenDoors standard command-line processing
|
|||
|
function (od_parse_cmd_line()), then you can just setup the BBS
|
|||
|
to run the program directly, using the command line:
|
|||
|
|
|||
|
YourProgramName.exe -handle xxxxxxxxxx
|
|||
|
|
|||
|
where xxxxxxxxx is the serial port handle, in decimal format.
|
|||
|
You do not need to use the start command, nor the DTRON utility,
|
|||
|
and you do not have to change the COM<n>AutoAssign setting in
|
|||
|
the system.ini file.
|
|||
|
|
|||
|
If you are running the Win32 door program under a DOS-based BBS
|
|||
|
system, or a Windows-based BBS system that is unable to pass a
|
|||
|
live serial port handle to the door program, then follow these
|
|||
|
steps:
|
|||
|
|
|||
|
1.Add a line of the form "COM<n>AutoAssign=<x>" to the [386Enh]
|
|||
|
section of your system.ini file. Here, <n> specifies the
|
|||
|
serial port number that the BBS's modem is connected to, and
|
|||
|
<x> will usually be 0. For example, if your modem is
|
|||
|
connected to COM1, you would add a line such as
|
|||
|
"COM1AutoAssign=0" (sans quotes). You will then have to re-
|
|||
|
start your computer for this change to take effect. If you do
|
|||
|
not do this, the Windows-based door program will not be able
|
|||
|
to access the modem.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 27
|
|||
|
|
|||
|
2.Setup the BBS software to run the Windows-based door program
|
|||
|
just as you would any other door program. You will probably
|
|||
|
want to do this from a batch file. The command line that runs
|
|||
|
the Windows program should be of the form:
|
|||
|
|
|||
|
start /w /m YourProgramName.exe [any command line
|
|||
|
parameters]
|
|||
|
|
|||
|
This will cause the Windows-based door program to start in
|
|||
|
minimized mode, and cause the calling MS-DOS session to wait
|
|||
|
until the Windows program exits before continuing. If you do
|
|||
|
not wish the program to be started in minimized mode, remove
|
|||
|
the /m from the command line. If you attempt to start the
|
|||
|
door program by calling it directly, rather than using the
|
|||
|
"start /w" command, the BBS software will immediately start
|
|||
|
again, cause it to attempt to run simultaneously with the
|
|||
|
door program.
|
|||
|
|
|||
|
3.After running the start command, use DTRON.EXE or a similar
|
|||
|
utility to re-enable DTR detection by the modem. Normally,
|
|||
|
this command line will be of the form:
|
|||
|
|
|||
|
dtron /port x /bps y
|
|||
|
|
|||
|
Where x is the serial port number (0 for COM1, 1 for COM2,
|
|||
|
etc.) and y is the locked bps rate. For example, if your
|
|||
|
serial port is locked at 38400 bps and is connected to COM2,
|
|||
|
you would use:
|
|||
|
|
|||
|
dtron /port 1 /bps 38400
|
|||
|
|
|||
|
For full information on the DTRON utility, simply type the
|
|||
|
command line:
|
|||
|
|
|||
|
dtron /help
|
|||
|
|
|||
|
You may freely redistribute the DTRON utility that is
|
|||
|
included in this package with your program.
|
|||
|
|
|||
|
Additional information on the Win32 version of OpenDoors, and
|
|||
|
further explanation of some of these steps, is provided in
|
|||
|
chapter 6.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 28
|
|||
|
|
|||
|
BASICS OF DOOR PROGRAMMING WITH OPENDOORS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section provides a complete tutorial to the basics of
|
|||
|
writing BBS door programs using OpenDoors. If you are using
|
|||
|
OpenDoors to write other online software, much of this
|
|||
|
information will still be relevant.
|
|||
|
|
|||
|
In addition to reading this section, I would encourage you to
|
|||
|
look at the example programs included int the OpenDoors
|
|||
|
packages. These programs, which are described beginning on page
|
|||
|
38, will give you a much better idea of what an OpenDoors
|
|||
|
program will look like. These programs can also serve as a great
|
|||
|
starting point for writing your own programs using OpenDoors.
|
|||
|
|
|||
|
Probably the best means of introduction to door programming with
|
|||
|
OpenDoors is by doing it yourself. As such, I strongly encourage
|
|||
|
you to try compiling and running the simple introduction program
|
|||
|
below. For instructions on compiling programs written with
|
|||
|
OpenDoors, see page 22.
|
|||
|
|
|||
|
DOS version:
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
main()
|
|||
|
{
|
|||
|
od_printf("Welcome to my first door program!\n\r");
|
|||
|
od_printf("Press a key to return to BBS!\n\r");
|
|||
|
od_get_key(TRUE);
|
|||
|
od_exit(0, FALSE);
|
|||
|
}
|
|||
|
|
|||
|
Win32 version:
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
int WINAPI WinMain(HINSTANCE hInstance,
|
|||
|
HINSTANCE hPrevInstance,LPSTR lpszCmdLine,int nCmdShow)
|
|||
|
{
|
|||
|
od_printf("Welcome to my first door program!\n\r");
|
|||
|
od_printf("Press a key to return to BBS!\n\r");
|
|||
|
od_get_key(TRUE);
|
|||
|
od_exit(0, FALSE);
|
|||
|
}
|
|||
|
|
|||
|
Keep in mind that even this simple program will automatically
|
|||
|
have all of the door capabilities we have already mentioned.
|
|||
|
Notice the line that reads #include "opendoor.h". All programs
|
|||
|
written with OpenDoors must include the OPENDOOR.H header file
|
|||
|
in order to compile correctly. The first two lines in the
|
|||
|
main/WinMain function simply call the OpenDoors od_printf()
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 29
|
|||
|
|
|||
|
function. od_printf() is similar to the printf() function that C
|
|||
|
programmers will already be familiar with. However, unlike
|
|||
|
printf(), the od_printf() function sends the output to both the
|
|||
|
modem and the local screen. Notice that the lines of text
|
|||
|
displayed by the od_printf() function end with a "\n\r"
|
|||
|
sequence, instead of the normal "\n". This is because the
|
|||
|
terminal emulation software that is running on the remote user's
|
|||
|
system usually requires both a carriage return and a line feed
|
|||
|
to correctly begin a new line. The next line in our example
|
|||
|
program is the OpenDoors single-key input function,
|
|||
|
od_get_key(). The TRUE value causes OpenDoors to wait for a key
|
|||
|
to be pressed (again, either from remote or local keyboard)
|
|||
|
before returning. The last line of the main/WinMain function is
|
|||
|
a call to od_exit(). Any program using OpenDoors should call
|
|||
|
this function. For the time being, you can always use the (0,
|
|||
|
FALSE) parameters.
|
|||
|
|
|||
|
Once again, you are encouraged to try compiling and running this
|
|||
|
program, as described above. Congratulations, you have written
|
|||
|
your first door program! Feel free to make any changes to this
|
|||
|
program, and see what effects your changes have.
|
|||
|
|
|||
|
To simplify this example, separate versions of this program are
|
|||
|
shown for the DOS and Win32 versions of OpenDoors. However, you
|
|||
|
would typically write your program so that it could be compiled
|
|||
|
using either the DOS or Win32 versions of OpenDoors, by
|
|||
|
beginning the mainline function as follows:
|
|||
|
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE
|
|||
|
hPrevInstance,
|
|||
|
LPSTR lpszCmdLine, int nCmdShow)
|
|||
|
#else
|
|||
|
int main(int argc, char *argv[])
|
|||
|
#endif
|
|||
|
|
|||
|
In case you are not entirely familiar with the operation of door
|
|||
|
programs, we will now provide an introduction to the internals
|
|||
|
of a door's operation. Keep in mind that OpenDoors automatically
|
|||
|
carries out most of these tasks for you. When any door program
|
|||
|
starts up, one of the first things it must do is to read the
|
|||
|
door information file(s) (sometimes called a "drop file") passed
|
|||
|
to it by the BBS. When a user is on-line, and wishes to run a
|
|||
|
door, they will most likely select a command from a menu. At
|
|||
|
this point, the BBS system (such as RemoteAccess, Maximus, PC-
|
|||
|
Board or whatever), will create a file of information about the
|
|||
|
system, who is currently on-line, and so on. Various BBS
|
|||
|
packages produce various styles of door information files.
|
|||
|
OpenDoors automatically recognizes and reads a wide variety of
|
|||
|
door information file formats. As a result, your doors will be
|
|||
|
able to run on a almost any BBS system.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 30
|
|||
|
|
|||
|
Fortunately, OpenDoors takes care of all the work involved in
|
|||
|
detecting and reading the door information file, and then
|
|||
|
initializing and communicating with the serial port for you. In
|
|||
|
order to carry out these tasks, along with setting up the status
|
|||
|
line, and so on, OpenDoors provides a function called od_init().
|
|||
|
If you do not explicitly call this function, the first call to
|
|||
|
any other OpenDoors function (such as the first time your door
|
|||
|
program outputs anything) will automatically cause the od_init()
|
|||
|
function to be called. As a result, upon the first call to an
|
|||
|
OpenDoors function, all of the initialization tasks for the door
|
|||
|
will automatically be carried out. However, there may be times
|
|||
|
when you will want your program to have access information about
|
|||
|
the user who is on-line, or carry out other actions which
|
|||
|
require od_init() to have been executed - prior to the point
|
|||
|
where you call any other OpenDoors functions. In this case, you
|
|||
|
will have to call od_init() yourself before you do any of these
|
|||
|
things.
|
|||
|
|
|||
|
OpenDoors provides you with a C/C++ structure, by the name of
|
|||
|
od_control, which allows you to access all the available
|
|||
|
information about the user who is on-line, the system your door
|
|||
|
is running on, and also allows you to adjust various OpenDoors
|
|||
|
parameters. Depending on what BBS system your door is running
|
|||
|
under, the actual information available from the od_control
|
|||
|
structure will vary. For more information on the od_control
|
|||
|
structure, see the section on the control structure, beginning
|
|||
|
on page 148.
|
|||
|
|
|||
|
Once the door has initialized itself, it will then begin
|
|||
|
communications with the user who is online. OpenDoors takes care
|
|||
|
of all communications, through its various input and display
|
|||
|
functions. When the door has finished, it will then write any
|
|||
|
information that has changed back to the door information file
|
|||
|
(if applicable), finish communicating with the modem, and return
|
|||
|
to the BBS. In OpenDoors, these shut-down operations are
|
|||
|
automatically performed you call the od_exit() function. This
|
|||
|
function will terminate the door's activity, OPTIONALLY hang up
|
|||
|
on the user (allowing you to provide either return to BBS or
|
|||
|
logoff options for exiting), and then exit with the specified
|
|||
|
errorlevel.
|
|||
|
|
|||
|
One other important OpenDoors function that you should be aware
|
|||
|
of is the od_kernel() function. od_kernel() is the central
|
|||
|
OpenDoors control function, and is responsible for much of
|
|||
|
OpenDoor's updating of the status line, monitoring the carrier
|
|||
|
detect and user timeout status, responding to sysop function
|
|||
|
keys, and so on. The od_kernel() function is called
|
|||
|
automatically by OpenDoors, within the other OpenDoors
|
|||
|
functions. As a result, since most door programs will call some
|
|||
|
OpenDoors function on a regular basis, you will most often have
|
|||
|
no need to call the od_kernel() function yourself. However, if
|
|||
|
your door is going to perform some action, such as updating data
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 31
|
|||
|
|
|||
|
files, during which it will not call any OpenDoors function for
|
|||
|
more than a few seconds, you should then call the od_kernel()
|
|||
|
function yourself. For more information on the od_kernel()
|
|||
|
function, see page 97.
|
|||
|
|
|||
|
For more information on the functions available from OpenDoors,
|
|||
|
or the control structure, see the corresponding sections in this
|
|||
|
manual.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 32
|
|||
|
|
|||
|
TOUR OF A SAMPLE DOOR PROGRAM: "EX_VOTE"
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
One of the best ways to see how OpenDoors works, and the
|
|||
|
potential that it has, is to look at the example programs
|
|||
|
included in the OpenDoors package. A brief description of each
|
|||
|
of these programs can be found on page 38. This section takes a
|
|||
|
closer look at one of the example programs, EX_VOTE.C. Unlike
|
|||
|
our simple example in the previous section, EX_VOTE.C is a much
|
|||
|
more complicated program, taking advantage of many of the
|
|||
|
advanced features of OpenDoors. Even if you do not understand
|
|||
|
everything that EX_VOTE.C does, you should be able to make use
|
|||
|
of various elements demonstrated here, in your own programs.
|
|||
|
|
|||
|
The OpenDoors package includes a two compiled versions of
|
|||
|
EX_VOTE. VOTEDOS.EXE is a plain-DOS program which can run under
|
|||
|
DOS, Windows or OS/2. VOTEWIN.EXE was compiled using the Win32
|
|||
|
version of OpenDoors, and so it runs only on Windows 95/NT. The
|
|||
|
OpenDoors package also contains a sample door information file,
|
|||
|
DORINFO1.DEF. You can use this file to test any doors in local
|
|||
|
mode. If you wish to manually create your own DORINFO1.DEF file,
|
|||
|
you can do so very easily. The DORINFO1.DEF door information
|
|||
|
file is a simple text file which lists a different piece of
|
|||
|
information on each line, in the following format:
|
|||
|
|
|||
|
+----------------------------------------------------------+
|
|||
|
| LINE NUMBER | DESCRIPTION | EXAMPLE |
|
|||
|
+-------------+------------------------+-------------------|
|
|||
|
| 1 | Name of the BBS | MY OWN BBS |
|
|||
|
| 2 | Sysop's first name | BRIAN |
|
|||
|
| 3 | Sysop's last name | PIRIE |
|
|||
|
| 4 | Com Port modem is on | COM0 |
|
|||
|
| 5 | Baud rate, etc. | 0 BAUD,N,8,1 |
|
|||
|
| 6 | Unused | 0 |
|
|||
|
| 7 | User's first name | JOHN |
|
|||
|
| 8 | User's last name | PUBLIC |
|
|||
|
| 9 | Caller's location | OTTAWA, ON |
|
|||
|
| 10 | ANSI mode (0=off, 1=on)| 1 |
|
|||
|
| 11 | User's security level | 32000 |
|
|||
|
| 12 | User's time left | 60 |
|
|||
|
+----------------------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
Feel free to make any changes you wish to EX_VOTE.C, and
|
|||
|
recompile it. One of the most effective and enjoyable ways to
|
|||
|
learn OpenDoors is by experimenting. If you are a registered
|
|||
|
owner of OpenDoors, you may even distribute your own versions of
|
|||
|
this door. Also, you may find that EX_VOTE.C serves as a good
|
|||
|
framework for building your own door programs.
|
|||
|
|
|||
|
The EX_VOTE.C door behaves similarly to most other door
|
|||
|
programs, and will have a fair bit in common with any other door
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 33
|
|||
|
|
|||
|
you write in OpenDoors. What you see in the output window is
|
|||
|
identical to what a remote user will be seeing. If the user has
|
|||
|
ANSI, AVATAR or RIP mode turned on, you will see the same colors
|
|||
|
as they do, and if they have screen clearing turned on, your
|
|||
|
screen will be cleared when theirs is. The status line at the
|
|||
|
bottom of the window will list the name of the user currently
|
|||
|
on-line (if you are using the sample DORINFO1.DEF file, the
|
|||
|
user's name will be "The Sysop"), the user's location, and the
|
|||
|
user's baud rate (0 if the door is operating in local mode). The
|
|||
|
local display also shows how much time the user has left,
|
|||
|
whether the user has paged the system operator for a chat, and
|
|||
|
other information.
|
|||
|
|
|||
|
There are a number of special commands that are only available
|
|||
|
to the system operator on the local keyboard. These commands
|
|||
|
allow the system operator to hang up on the user, adjust the
|
|||
|
amount of time the user may remain online, enter chat mode with
|
|||
|
the user, enter a DOS shell (in the DOS version), and so on. In
|
|||
|
the DOS version, help on these commands is available on the
|
|||
|
status line by pressing the [F9] key. In the Windows version,
|
|||
|
these commands are listed on the menu that appears at the top of
|
|||
|
the window.
|
|||
|
|
|||
|
Now, let us take a closer look at the actual source code for the
|
|||
|
EX_VOTE.C door. If you have not already printed out a copy of
|
|||
|
this manual, and possibly the EX_VOTE.C file as well, it would
|
|||
|
probably be a good idea to do so now.
|
|||
|
|
|||
|
Notice that near the top of the program, along with all the
|
|||
|
standard header files, the OPENDOOR.H file is included. This
|
|||
|
file must be included in all programs written under OpenDoors.
|
|||
|
If you are placing the OPENDOOR.H file in the same directory as
|
|||
|
the door you are compiling, simply include the line:
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
in your program.
|
|||
|
|
|||
|
The main()/WinMain() function of the EX_VOTE.C program has a
|
|||
|
for(;;) loop that repeatedly displays the main menu, obtains a
|
|||
|
choice from the user and responds to the command, until the user
|
|||
|
chooses to exit the program. Before the main menu is displayed,
|
|||
|
the screen is cleared by calling od_clr_scr(). The od_clr_scr()
|
|||
|
function will clear both the local and remote screens, but only
|
|||
|
if the user has screen clearing enabled. Refer to page 57 for
|
|||
|
information on how to force the screen to be cleared, regardless
|
|||
|
of the user's screen clearing setting. The main menu is
|
|||
|
displayed using the od_printf() function, one of the most common
|
|||
|
OpenDoors functions you will use. Next, od_get_answer() is used
|
|||
|
to obtain a menu choice from the user from the specified set of
|
|||
|
keys. Next, a switch() statement is used to respond to the
|
|||
|
user's command appropriately. If the user presses the P key to
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 34
|
|||
|
|
|||
|
page the system operator, od_page() is called. If the user
|
|||
|
chooses to return to the BBS, od_exit() is called to terminate
|
|||
|
OpenDoor's activities and return control to the BBS. The FALSE
|
|||
|
parameter passed to od_exit() indicates that OpenDoors should
|
|||
|
not disconnect (hangup) before exiting. If the user chooses to
|
|||
|
log off, EX_VOTE.C first confirms this action with the user, and
|
|||
|
then calls od_exit() with the TRUE parameter. The numerical
|
|||
|
parameter passed to od_exit() sets the errorlevel that OpenDoors
|
|||
|
will exit with.
|
|||
|
|
|||
|
In its ChooseQuestion() function, EX_VOTE.C uses the OpenDoors
|
|||
|
function od_get_key(). This function is similar to the
|
|||
|
od_get_answer() function that we have already seen. However,
|
|||
|
unlike od_get_answer() which will wait until the user presses
|
|||
|
some key from the list of possibilities you provide,
|
|||
|
od_get_key() will allow the user to press any key. od_get_key()
|
|||
|
accepts a single parameter. If this parameter is TRUE,
|
|||
|
od_get_key() will wait for the user to press a key before
|
|||
|
returning. If this parameter is FALSE, od_get_key() will return
|
|||
|
immediately with a value of 0 if there are no keys waiting in
|
|||
|
the inbound buffer, and returning the next key if there are
|
|||
|
characters waiting.
|
|||
|
|
|||
|
In a number of places, EX_VOTE.C also uses the od_input_str()
|
|||
|
function. Unlike od_get_key() and od_get_answer() which return a
|
|||
|
single character, od_input_str() allows the user to input and
|
|||
|
edit a string of many characters. You will only receive the
|
|||
|
string entered by the user after they press the enter key.
|
|||
|
od_input_str() accepts four parameters: the string where the
|
|||
|
user's input should be stored, the maximum number of characters
|
|||
|
to input, the minimum character value to accept and the maximum
|
|||
|
character value to accept.
|
|||
|
|
|||
|
Another new feature of OpenDoors that is used by EX_VOTE.C is
|
|||
|
the OpenDoors control structure, od_control. This global
|
|||
|
structure is documented in chapter 5 of this manual. The
|
|||
|
OpenDoors control structure allows you to access a wide variety
|
|||
|
of information about the user who is currently online, the BBS
|
|||
|
system your program is running on, and also allows you to
|
|||
|
control various OpenDoors settings. For example, EX_VOTE.C
|
|||
|
compares the current user name (od_control.od_user_name) with
|
|||
|
the name of the system operator (od_control.od_sysop_name) to
|
|||
|
determine whether it is the system operator who using the
|
|||
|
program.
|
|||
|
|
|||
|
EX_VOTE.C uses two data files, the first of which contains a
|
|||
|
record for every user, and the second of which contains a record
|
|||
|
for every question. EX_VOTE.C accesses these data files in a
|
|||
|
controlled manner in order to permit the program to be running
|
|||
|
simultaneously on multiple lines on a multi-node BBS system.
|
|||
|
When EX_VOTE.C needs to update a data file, it opens it for
|
|||
|
exclusive access, so that only one node can access the file at
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 35
|
|||
|
|
|||
|
any given time. Since the data file could have been changed by
|
|||
|
another node since the time that EX_VOTE.C last read the file,
|
|||
|
it always reads a record, makes changes to it and then re-writes
|
|||
|
the record while it has the file open for exclusive access. It
|
|||
|
then closes the file as soon as possible after opening the file,
|
|||
|
in order to permit other nodes to once again access the file.
|
|||
|
Because EX_VOTE.C keeps track of which questions each user has
|
|||
|
voted on, along with the questions and results of voting on each
|
|||
|
question, its data file format is more complex than many door
|
|||
|
programs (although not as complex as others).
|
|||
|
|
|||
|
EX_VOTE.C also uses color. One of the easiest ways to use
|
|||
|
different colors in an OpenDoors program is to use the
|
|||
|
OpenDoor's print color-setting extensions. You can change the
|
|||
|
color of text display at any point in an od_printf() format
|
|||
|
string using by enclosing the name of new display color in back
|
|||
|
quote characters (`, not '). For example:
|
|||
|
|
|||
|
od_printf("`red`This is in red `green`This is green\n\r");
|
|||
|
|
|||
|
Would cause the words "This is in red" to be displayed in red,
|
|||
|
and the words "This is in green" to be displayed in green.
|
|||
|
|
|||
|
EX_VOTE.C also takes advantage of a number of OpenDoors
|
|||
|
capabilities that you can optionally choose to include in your
|
|||
|
door programs. You will notice that there are a number of new
|
|||
|
lines at the beginning of the main() function, all of which
|
|||
|
change settings in the OpenDoors control structure. The line:
|
|||
|
|
|||
|
od_control.od_config_file = INCLUDE_CONFIG_FILE;
|
|||
|
|
|||
|
causes the OpenDoors configuration file system to be included in
|
|||
|
your program. Using this system, OpenDoors automatically reads a
|
|||
|
configuration file that can be used by the system operator to
|
|||
|
change various program settings. Refer to the included door.cfg
|
|||
|
file for an example OpenDoors configuration file. In addition to
|
|||
|
the configuration file settings automatically supported by the
|
|||
|
configuration file system, you can also add your own
|
|||
|
configuration file settings. To do this, you simply supply
|
|||
|
OpenDoors with a callback function that it will call whenever it
|
|||
|
encounters an unrecognized keyword in the configuration file.
|
|||
|
The line:
|
|||
|
|
|||
|
od_control.od_config_function = CustomConfigFunction;
|
|||
|
|
|||
|
Causes OpenDoors to call the function CustomConfigFunction() in
|
|||
|
EX_VOTE.C for this purpose. You will notice that the
|
|||
|
CustomConfigFunction() receives two parameters - the first is
|
|||
|
the unrecognized keyword, and the second is any parameters that
|
|||
|
follow the keyword in the configuration file. EX_VOTE.C checks
|
|||
|
for two special configuration file lines - one to set whether or
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 36
|
|||
|
|
|||
|
not users can add questions, and one to set whether or not users
|
|||
|
can view the results of a question before voting on it.
|
|||
|
|
|||
|
The next line in the main() function,
|
|||
|
|
|||
|
od_control.od_mps = INCLUDE_MPS;
|
|||
|
|
|||
|
causes the OpenDoors "Multiple Personality System" to be
|
|||
|
included in program. This allows the sysop to choose from a
|
|||
|
number of status line / sysop function key "personalities" that
|
|||
|
mimic a number of different BBS systems, using the Personality
|
|||
|
setting in the configuration file.
|
|||
|
|
|||
|
|
|||
|
The line:
|
|||
|
|
|||
|
od_control.od_logfile = INCLUDE_LOGFILE;
|
|||
|
|
|||
|
causes the OpenDoors log file system to be included in the
|
|||
|
program. The OpenDoors log file system automatically records the
|
|||
|
date and time of program startup, exit and other major actions
|
|||
|
in the specified file. EX_VOTE.C also writes its own log file
|
|||
|
entries by calling the od_log_write() function.
|
|||
|
|
|||
|
EX_VOTE.C also provides the ability for the sysop to provide
|
|||
|
their own ASCII/ANSI/AVATAR/RIP files to be displayed in place
|
|||
|
of the normal main menu. EX_VOTE.C uses the od_hotkey_menu()
|
|||
|
function to display a VOTE.ASC/.ANS/.AVT/.RIP file for the main
|
|||
|
menu, if such a file exists. If the file is not available, the
|
|||
|
normal EX_VOTE.C menu is used instead. The od_hotkey_menu()
|
|||
|
function will automatically select the appropriate file
|
|||
|
(.ASC/.ANS/.AVT/.RIP) for the current display mode, and the user
|
|||
|
is able to make a menu choice at any time. If a menu choice is
|
|||
|
made before the menu is entirely displayed, the function will
|
|||
|
stop displaying the menu and return immediately.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 37
|
|||
|
|
|||
|
OTHER EXAMPLE PROGRAMS INCLUDED WITH OPENDOORS
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
In addition to the EX_VOTE.C program, which is discussed in
|
|||
|
detail in the previous section, a number of other example
|
|||
|
programs are included with OpenDoors. These programs help to
|
|||
|
demonstrate what is possible with OpenDoors. They can also serve
|
|||
|
as excellent tools to help you learn OpenDoors. In addition, you
|
|||
|
are free to include any portions of any of these example
|
|||
|
programs in your own programs. Below is a summary of each of
|
|||
|
these example programs:
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EX_HELLO.C This an example of a very simple door program that displays a
|
|||
|
short message and prompts for the user to press a key. After the
|
|||
|
user presses a key, the door exits and control is returned to
|
|||
|
the main BBS software. Despite the fact that it only consists of
|
|||
|
a few lines of code, EX_HELLO remains a fully functional door
|
|||
|
program. For information on compiling an OpenDoors door program,
|
|||
|
see the section that begins on page 22.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EX_CHAT.C This program is an example of a multi-window full-screen chat
|
|||
|
door written with OpenDoors. EX_CHAT demonstrates the ease of
|
|||
|
using sophisticated ANSI / AVATAR / RIP terminal features within
|
|||
|
OpenDoors programs. For instructions on how to compile this
|
|||
|
program, see the section that begins on page 22.
|
|||
|
|
|||
|
This program create two windows on the screen, separated by a
|
|||
|
bar with user name / sysop name information. This program
|
|||
|
permits communication between the local sysop and remote user by
|
|||
|
displaying the text typed by the user in one window, and the
|
|||
|
text typed by the sysop in the other window. When either
|
|||
|
person's typing reaches the bottom of the window, the contents
|
|||
|
of the window is scrolled up to provide more room for typing.
|
|||
|
Words are also wrapped when either typist reaches the end of a
|
|||
|
line. The advantage of a split-screen chat program is that it
|
|||
|
permits both sysop and user to type at the same time without
|
|||
|
difficulty. The chat function automatically invokes OpenDoor's
|
|||
|
internal chat mode if ANSI, AVATAR or RIP modes are not
|
|||
|
available. The display colors, window sizes and locations, and
|
|||
|
distance to scroll a window's contents are configurable by
|
|||
|
setting the appropriate variables, below. When the Sysop invokes
|
|||
|
a DOS shell, a pop-up window is displayed to indicate to the
|
|||
|
user that the door program has been suspended.
|
|||
|
|
|||
|
The chat feature of this program can also be easily integrated
|
|||
|
into other doors you write, and may be used to replace the
|
|||
|
existing OpenDoors line-oriented chat system.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 38
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EX_MUSIC.C This example door demonstrates how to play "ANSI" music and
|
|||
|
sound effects in an OpenDoors door. Included in this program is
|
|||
|
a function to send "ANSI" music to the remote system, and a
|
|||
|
function to text the remote system's ability to play "ANSI"
|
|||
|
music. You may use both of these functions in your own doors, if
|
|||
|
you wish to add music or sound effect capabilities. This program
|
|||
|
can be compiled by following the instructions that begin on page
|
|||
|
22.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EX_SKI.C This is a simple but addictive online game that is written using
|
|||
|
OpenDoors. In this action game, the player must control a skier
|
|||
|
through a downhill slalom course. The user may turn the skier
|
|||
|
left or right, and the game ends as soon as the player skis
|
|||
|
outside the marked course. The game begins at an easy level, but
|
|||
|
quickly becomes more and more difficult as the course to be
|
|||
|
navigated becomes more and more narrow. The game maintains a
|
|||
|
list of players with high scores, and this list may be viewed
|
|||
|
from the main menu.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EX_VOTE.C The EX_VOTE.C file contain the source code for the Vote example
|
|||
|
door, as is described beginning on page 38. The Vote example
|
|||
|
door allows users to vote on up to 200 different "polls", view
|
|||
|
the results of voting on each question, and optionally add their
|
|||
|
own questions for other users to answer.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 39
|
|||
|
|
|||
|
444
|
|||
|
4444
|
|||
|
44 44
|
|||
|
44444444
|
|||
|
44
|
|||
|
44
|
|||
|
44
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 4 - THE OPENDOORS API FUNCTIONS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
OVERVIEW
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
OpenDoors provides a wide set of features that you can take
|
|||
|
advantage of in your program. You control these features and
|
|||
|
access OpenDoors from your program using two facilities - the
|
|||
|
OpenDoors API functions, and the OpenDoors control structure. In
|
|||
|
general, the API functions are used to actually accomplish a
|
|||
|
task, such as displaying something to the user, or retrieving
|
|||
|
input from the user. The OpenDoors control structure, on the
|
|||
|
other hand, is used to alter OpenDoors settings or retrieve
|
|||
|
specific information.
|
|||
|
|
|||
|
Any program written with OpenDoors makes use of the OpenDoors
|
|||
|
API functions for all of its door-related input and output. In
|
|||
|
addition to the common input and output tasks, the OpenDoors API
|
|||
|
functions provide access to many special capabilities, such as
|
|||
|
displaying ASCII/ANSI/AVATAR/RIP files, providing pop-up windows
|
|||
|
and menus, and much more. Much of the information about the user
|
|||
|
who is online, information about the system your door is running
|
|||
|
on, and settings which customize OpenDoor's behavior are
|
|||
|
controlled through the OpenDoors control structure. The control
|
|||
|
structure is described in the section beginning on page 148.
|
|||
|
|
|||
|
This chapter is divided into the following sections:
|
|||
|
|
|||
|
i.) TABLE OF MOST COMMONLY USED FUNCTIONS (Page 41)
|
|||
|
ii.) TABLE OF ALL OPENDOORS FUNCTIONS (Page 42)
|
|||
|
iii.) DETAILED INFORMATION ON EACH FUNCTION (Pages 47 - 147)
|
|||
|
|
|||
|
The two tables list the names of the OpenDoors functions, along
|
|||
|
with a brief description of the task performed by each function,
|
|||
|
and the page number on which the detailed description of that
|
|||
|
function can be found. The first table lists only the most
|
|||
|
commonly used OpenDoors functions, to allow you to quickly find
|
|||
|
the function you are most likely looking for. The second table
|
|||
|
lists all of the OpenDoors functions, grouped according to
|
|||
|
general categories of functionality.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 40
|
|||
|
|
|||
|
The section containing detailed information lists all of the
|
|||
|
functions in alphabetical order, with the information about each
|
|||
|
function beginning on a new page. This section includes a brief
|
|||
|
description of each function's purpose, a detailed description
|
|||
|
of how to use the function, the function call format, a list of
|
|||
|
related functions, and in many cases example source code showing
|
|||
|
you a typical use of the function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
TABLE OF MOST COMMONLY USED FUNCTIONS
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
od_printf() Displays text, with the ability to change
|
|||
|
display color. (page 110)
|
|||
|
|
|||
|
od_clr_scr() Clears the screen. (Page 57)
|
|||
|
|
|||
|
od_input_str() Inputs a string of one or more characters
|
|||
|
from the user. (Page 95)
|
|||
|
|
|||
|
od_get_answer() Inputs a single key from a list of possible
|
|||
|
choices ignoring upper/lower case. (Page 81)
|
|||
|
|
|||
|
od_get_key() Inputs any single key from the user.
|
|||
|
(Page 82)
|
|||
|
|
|||
|
od_set_cursor() Positions the cursor in ANSI/AVATAR/RIP
|
|||
|
modes. (Page 134)
|
|||
|
|
|||
|
od_hotkey_menu() Displays an ASCII/ANSI/AVATAR/RIP file, with
|
|||
|
the option of watching for a keypress from
|
|||
|
the user. (Page 90)
|
|||
|
|
|||
|
od_popup_menu() Displays a popup menu in ANSI/AVATAR/RIP
|
|||
|
modes. (Page 105)
|
|||
|
|
|||
|
od_window_create() Creates a popup window in ANSI/AVATAR/RIP
|
|||
|
modes. (Page 145)
|
|||
|
|
|||
|
od_window_remove() Removes a popup window in, restoring screen
|
|||
|
contents "underneath" window. (Page 147)
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 41
|
|||
|
|
|||
|
TABLE OF ALL FUNCTIONS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
OUTPUT TEXT DISPLAY FUNCTIONS
|
|||
|
FUNCTIONS ----------------------
|
|||
|
od_disp_str() Displays a normal, NULL-terminated
|
|||
|
string. (page 63)
|
|||
|
|
|||
|
od_disp() Sends the specified number of
|
|||
|
characters to the modem, with or
|
|||
|
without local echo. (page 60)
|
|||
|
|
|||
|
od_printf() Performs formatted output, as the
|
|||
|
printf() function does. Also allows
|
|||
|
imbedded codes to change display color.
|
|||
|
(page 110)
|
|||
|
|
|||
|
od_putch() Displays a single character. (page 115)
|
|||
|
|
|||
|
od_disp_emu() Displays a string, interpreting
|
|||
|
imbedded ANSI/AVATAR terminal emulation
|
|||
|
codes. (page 62)
|
|||
|
|
|||
|
od_repeat() Displays the same character any number
|
|||
|
of times, using AVATAR optimization, if
|
|||
|
possible. (page 118)
|
|||
|
|
|||
|
COLOR AND CURSOR CONTROL
|
|||
|
------------------------
|
|||
|
od_set_color() Sets current color to specified
|
|||
|
foreground and background settings.
|
|||
|
(page 131)
|
|||
|
|
|||
|
od_set_attrib() Sets current color to specified IBM-PC
|
|||
|
display attribute. (page 128)
|
|||
|
|
|||
|
od_set_cursor() Sets the position of the cursor, if
|
|||
|
ANSI/AVATAR/RIP mode is enabled. (page
|
|||
|
134)
|
|||
|
|
|||
|
SCREEN MANIPULATION
|
|||
|
-------------------
|
|||
|
od_clr_scr() Clears the screen, if user has screen
|
|||
|
clearing enabled. (page 57)
|
|||
|
|
|||
|
od_save_screen() Stores the current contents of the
|
|||
|
screen, to be later redisplayed using
|
|||
|
od_restore_screen(). Works in all
|
|||
|
display modes. (page 121)
|
|||
|
|
|||
|
od_restore_screen() Restores the contents of the screen, as
|
|||
|
previously stored using
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 42
|
|||
|
|
|||
|
od_save_screen(). Works in all display
|
|||
|
modes. (page 120)
|
|||
|
|
|||
|
BLOCK MANIPULATION
|
|||
|
------------------
|
|||
|
od_clr_line() Clears the remainder of current line.
|
|||
|
(page 55)
|
|||
|
|
|||
|
od_gettext() Stores any area of the screen, to later
|
|||
|
be displayed by od_puttext(). Requires
|
|||
|
ANSI/AVATAR/RIP graphics mode. (page
|
|||
|
89)
|
|||
|
|
|||
|
od_puttext() Displays text with color information,
|
|||
|
as previously stored using
|
|||
|
od_gettext(). Requires ANSI/AVATAR/RIP
|
|||
|
graphics mode. (page 116)
|
|||
|
|
|||
|
od_scroll() Scrolls a portion of the screen in
|
|||
|
ANSI/AVATAR/RIP graphics modes. (page
|
|||
|
123)
|
|||
|
|
|||
|
POPUP WINDOWS AND MENUS
|
|||
|
-----------------------
|
|||
|
od_draw_box() Draws a box on the screen in
|
|||
|
ANSI/AVATAR/RIP graphics mode. (page
|
|||
|
65)
|
|||
|
|
|||
|
od_window_create() Displays a popup window, storing the
|
|||
|
screen contents "under" the window.
|
|||
|
Requires ANSI/AVATAR/RIP graphics mode.
|
|||
|
(page 145)
|
|||
|
|
|||
|
od_window_remove() Removes a popup window displayed with
|
|||
|
od_window_create(), restoring the
|
|||
|
original screen contents "under" the
|
|||
|
window. Requires ANSI/AVATAR/RIP
|
|||
|
graphics mode. (page 147)
|
|||
|
|
|||
|
od_popup_menu() Displays a menu in a popup window,
|
|||
|
allowing the user to choose menu items
|
|||
|
either by pressing a "hot" key, or
|
|||
|
moving a highlighted selection bar.
|
|||
|
After menu selection, the menu may be
|
|||
|
removed, restoring the original screen
|
|||
|
contents "under" the window. Requires
|
|||
|
ANSI/AVATAR/RIP graphics mode. (page
|
|||
|
105)
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 43
|
|||
|
|
|||
|
FILE DISPLAY FUNCTIONS
|
|||
|
----------------------
|
|||
|
od_send_file() Displays an ASCII/ANSI/AVATAR/RIP file
|
|||
|
(for instance, an .ANS file created by
|
|||
|
a program such as "TheDraw" (page 124)
|
|||
|
|
|||
|
od_hotkey_menu() Displays an ASCII/ANSI/AVATAR/RIP menu
|
|||
|
file, with hotkeys active. (page 90)
|
|||
|
|
|||
|
od_list_files() Lists the files available for download
|
|||
|
in an area, using a FILES.BBS file.
|
|||
|
(page 98)
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
INPUT od_get_answer() Inputs a single key from the keyboard,
|
|||
|
FUNCTIONS allowing only particular responses.
|
|||
|
(page 81)
|
|||
|
|
|||
|
od_get_input() A more flexible version of
|
|||
|
od_get_key(), that also supports
|
|||
|
extended keys such as arrow keys,
|
|||
|
insert, etc. (page 82)
|
|||
|
|
|||
|
od_get_key() Inputs a single key from the keyboard,
|
|||
|
optionally waiting if a key is not
|
|||
|
available. (page 82)
|
|||
|
|
|||
|
od_input_str() Inputs a string of specified length,
|
|||
|
from the keyboard. (page 95)
|
|||
|
|
|||
|
od_edit_str() Formatted string editing function,
|
|||
|
requiring ANSI/AVATAR/RIP graphics.
|
|||
|
(page 68)
|
|||
|
|
|||
|
od_multiline_edit() Provides a text editor that allows the
|
|||
|
user to enter or edit text that spans
|
|||
|
multiple lines, such as email messages
|
|||
|
or text files. (page 101)
|
|||
|
|
|||
|
od_clear_keybuffer() Removes any waiting keys from the
|
|||
|
keyboard input queue. (page 53)
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
COMMON od_page() Allows the user to page the sysop.
|
|||
|
DOOR (page 101)
|
|||
|
ACTIVITY
|
|||
|
FUNCTIONS od_spawn() OpenDoors "quick" spawn function.
|
|||
|
Executes an external program (eg. file
|
|||
|
compressor, external protocol, etc.) on
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 44
|
|||
|
|
|||
|
a separate screen, restoring the
|
|||
|
OpenDoors screen afterwards. (page 139)
|
|||
|
|
|||
|
od_spawnvpe() OpenDoors full-featured spawn function.
|
|||
|
Executes an external program on a
|
|||
|
separate screen, searching the path for
|
|||
|
the program, allowing you to specify an
|
|||
|
environment to pass to the child
|
|||
|
process, and returning the errorlevel
|
|||
|
returned by the child process. (page
|
|||
|
143)
|
|||
|
|
|||
|
od_log_write() Adds an entry to the end of the log
|
|||
|
file. (page 100)
|
|||
|
|
|||
|
od_parse_cmd_line() Handle standard command line options.
|
|||
|
(page 105)
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
SPECIAL od_init() Begins door operation by setting up
|
|||
|
CONTROL the OpenDoors control structure,
|
|||
|
FUNCTIONS setting up the local screen,
|
|||
|
initializing the serial port (if
|
|||
|
applicable), and reading the door
|
|||
|
information file. (page 92)
|
|||
|
|
|||
|
od_color_config() Transfers a color configuration line to
|
|||
|
a color attribute value. (page 59)
|
|||
|
|
|||
|
od_add_personality() Adds a custom status line/control key
|
|||
|
personality to OpenDoors. (page 47)
|
|||
|
|
|||
|
od_set_statusline() Temporarily alters the setting of the
|
|||
|
current OpenDoors status line. (page
|
|||
|
137)
|
|||
|
|
|||
|
od_autodetect() Automatically determines the remote
|
|||
|
terminal software's graphical
|
|||
|
capabilities. (page 48)
|
|||
|
|
|||
|
od_kernel() The central OpenDoors control function,
|
|||
|
which should be executed every few
|
|||
|
seconds. (page 97)
|
|||
|
|
|||
|
od_exit() Ends door operations, closing the
|
|||
|
serial port driver, re-writing the door
|
|||
|
information file, and optionally
|
|||
|
returning control to the BBS. (page 79)
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 45
|
|||
|
|
|||
|
od_carrier() Allows detection of carrier signal in
|
|||
|
programs that have disabled OpenDoors
|
|||
|
internal checking. (page 51)
|
|||
|
|
|||
|
od_set_dtr() Controls the DTR signal to the modem.
|
|||
|
Can be used to manually disconnect a
|
|||
|
remote user, in order to perform
|
|||
|
activities such as call back
|
|||
|
verification. (page 135)
|
|||
|
|
|||
|
od_chat() Forces OpenDoors to enter chat mode,
|
|||
|
even if sysop did not press the "chat"
|
|||
|
key. (page 50)
|
|||
|
|
|||
|
od_sleep() Suspends program execution, yielding
|
|||
|
control to other tasks in a
|
|||
|
multitasking environment. (page 139)
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 46
|
|||
|
|
|||
|
OD_ADD_PERSONALITY()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Installs a custom status line / sysop function key personality
|
|||
|
into OpenDoors.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_add_personality(char *pszName, BYTE btOutputTop,
|
|||
|
BYTE btOutputBottom, OD_PERSONALITY_PROC *pfPerFunc);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION If used, this function should be called before any other
|
|||
|
OpenDoors API functions. This function installs a new
|
|||
|
personality into OpenDoors. The first parameter specifies the
|
|||
|
string that will be used to identify the personality. This is
|
|||
|
the string that the user will be able to supply in the
|
|||
|
configuration file to select this personality, and is also the
|
|||
|
string that can be passed to od_set_personality() to manually
|
|||
|
switch to this personality. The second and third parameters
|
|||
|
specify the 1-based to and bottom line numbers of the output
|
|||
|
window to be used with this personality. For instance, a top
|
|||
|
value of 1 and bottom value of 23 would cause all door output to
|
|||
|
be displayed on the first 23 lines of the screen, leaving the
|
|||
|
bottom two lines for use by the personality's status line. The
|
|||
|
last parameter is a pointer to the personality function, which
|
|||
|
OpenDoors will call to perform various operations with that
|
|||
|
involve the personality. For more information on personalities
|
|||
|
and the OpenDoors Multiple Personality System, see the section
|
|||
|
which begins on page 233.
|
|||
|
|
|||
|
This function only has an effect under the DOS version of
|
|||
|
OpenDoors.
|
|||
|
|
|||
|
SEE ALSO od_set_personality(), od_set_statusline()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 47
|
|||
|
|
|||
|
OD_AUTODETECT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Attempts to automatically determine the terminal capabilities of
|
|||
|
the remote system.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_autodetect(int nFlags);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function can be used to determine whether or not the remote
|
|||
|
terminal supports ANSI and/or RIP (Remote Imaging Protocol)
|
|||
|
graphics modes. This information is usually supplied to the door
|
|||
|
by the BBS software, through the door information file. For this
|
|||
|
reason, most door programs do not need to make used of this
|
|||
|
function. However, if your door will be running under any BBS
|
|||
|
software that does not report the ANSI or RIP capabilities of
|
|||
|
the remote system, you may wish to use this function.
|
|||
|
od_autodetect() will set either of the following OpenDoors
|
|||
|
control structure variables to TRUE if the corresponding
|
|||
|
graphics mode is detected:
|
|||
|
|
|||
|
od_control.user_ansi - TRUE if ANSI mode is available
|
|||
|
od_control.user_rip - TRUE if RIP mode is available
|
|||
|
|
|||
|
However, if either of these variables have previously been set
|
|||
|
to TRUE (either explicitly by your program, or due to the
|
|||
|
corresponding modes being enabled in the door information file),
|
|||
|
and od_autodetect() does not detect the corresponding graphics
|
|||
|
mode, they will not be set to FALSE. Not all terminal software
|
|||
|
that supports ANSI or RIP graphics mode will necessarily have
|
|||
|
the ability to report their graphics mode capabilities to the
|
|||
|
door. For this reason, failure to detect either of these modes
|
|||
|
does not necessarily indicate that they are not available.
|
|||
|
However, if these modes are detected by od_autodetect(), it is
|
|||
|
safe to assume that the remote system does support the detected
|
|||
|
mode.
|
|||
|
|
|||
|
The nFlags parameter is reserved for future use, and should
|
|||
|
always be set to DETECT_NORMAL.
|
|||
|
|
|||
|
This function cannot auto-detect AVATAR mode, because there is
|
|||
|
no standard means of determining whether a remote system
|
|||
|
supports AVATAR mode.
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below is an example of using od_autodetect() in determining the
|
|||
|
remote terminal's graphics capabilities. Since not all terminal
|
|||
|
software supports auto-detection, this example will also prompt
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 48
|
|||
|
|
|||
|
the user to determine their software's capabilities if
|
|||
|
od_autodetect() fails to detect ANSI mode. This code assumes
|
|||
|
that if the terminal software supports the autodetection of ANSI
|
|||
|
mode, that it will also support the autodetection of RIP mode.
|
|||
|
OpenDoors assumes that ANSI mode is always available in
|
|||
|
conjunction with RIP mode.
|
|||
|
|
|||
|
/* Call the automatic terminal detection function */
|
|||
|
od_autodetect();
|
|||
|
|
|||
|
/* If ANSI mode was not detected, ask the user about
|
|||
|
if(!od_control.user_ansi)
|
|||
|
{
|
|||
|
/* Prompt the user for ANSI capabilities */
|
|||
|
od_clr_scr();
|
|||
|
od_printf("Does your system support ANSI graphics?");
|
|||
|
od_printf(" (Y/N)");
|
|||
|
|
|||
|
/* If the user chooses [Y]es */
|
|||
|
if(od_get_answer("YN") == 'Y')
|
|||
|
{
|
|||
|
/* Turn on ANSI mode */
|
|||
|
od_control.user_ansi = TRUE;
|
|||
|
|
|||
|
/* Since ANSI mode is present, RIP mode may also */
|
|||
|
/* be available. Prompt the user for RIP. */
|
|||
|
od_printf("\r\n\n");
|
|||
|
od_printf("Does your system support RIP graphics?");
|
|||
|
od_printf(" (Y/N)");
|
|||
|
|
|||
|
/* If the user chooses [Y]es */
|
|||
|
if(od_get_answer("YN") == 'Y')
|
|||
|
/* Turn on RIP mode */
|
|||
|
od_control.user_rip = TRUE;
|
|||
|
|
|||
|
/* Since ANSI mode is present, AVATAR mode may */
|
|||
|
/* also be available. Prompt the user for AVATAR. */
|
|||
|
od_printf("\r\n\n");
|
|||
|
od_printf("Does your system support AVATAR ");
|
|||
|
od_printf("graphics? (Y/N)");
|
|||
|
|
|||
|
/* If the user chooses [Y]es */
|
|||
|
if(od_get_answer("YN") == 'Y')
|
|||
|
/* Turn on AVATAR mode */
|
|||
|
od_control.user_avatar = TRUE;
|
|||
|
}
|
|||
|
|
|||
|
od_printf("\r\n\n");
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 49
|
|||
|
|
|||
|
OD_CHAT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Manually invokes sysop chat mode.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_chat(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION Normally, the OpenDoors sysop chat mode will only be invoked
|
|||
|
when the sysop explicitly requests it using the sysop chat key.
|
|||
|
However, there may be some cases where you wish to manually
|
|||
|
invoke the sysop chat mode. One example is when you are
|
|||
|
replacing the OpenDoors built-in chat mode with your own, but
|
|||
|
still wish to use the OpenDoors chat mode under some
|
|||
|
circumstances. For instance, you may wish to use your own split-
|
|||
|
screen chat routine if ANSI, AVATAR or RIP graphics mode is
|
|||
|
available, and use the OpenDoors line-oriented chat mode if only
|
|||
|
ASCII mode is available.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_page()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of using the od_chat() function, see the
|
|||
|
ex_chat.c example door, which is described on page 38.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 50
|
|||
|
|
|||
|
OD_CARRIER()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE To determine the status of the carrier detect signal, in
|
|||
|
programs where OpenDoors' internal carrier detection has been
|
|||
|
disabled.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_carrier(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE if a carrier is present, or
|
|||
|
FALSE if no carrier is present, or in local mode.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION Usually, you will not have any use for the od_carrier()
|
|||
|
function, as OpenDoors automatically monitor's the carrier
|
|||
|
detect signal, and will correctly recover if the carrier detect
|
|||
|
signal is lost while the door is operating in remote mode.
|
|||
|
However, in some programs, you may wish to disable OpenDoors'
|
|||
|
internal carrier detection routines, using the
|
|||
|
od_control.od_disable variable. Two such cases in which you
|
|||
|
might want to do this, are a call-back verification door, which
|
|||
|
disconnects the user and attempts to call them back, or in a
|
|||
|
terminal program, which is in fact not a door at all (and as
|
|||
|
such you would not want to have OpenDoors exit when the carrier
|
|||
|
detect signal is lost). In cases like these, you will then be
|
|||
|
able to use the od_carrier() function in order to determine the
|
|||
|
state of the carrier detect signal.
|
|||
|
|
|||
|
This function will return a Boolean value (for more information
|
|||
|
on Boolean values, see the Glossary which begins on page 256),
|
|||
|
of either TRUE or FALSE. If a carrier detect signal is present
|
|||
|
when the function is called, it will return TRUE, and if no
|
|||
|
carrier detect signal is detected, it will return FALSE. Since
|
|||
|
there is no remote connection, and thus no carrier when
|
|||
|
OpenDoors is operating in local mode, this function will always
|
|||
|
return a value of FALSE in local mode.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_set_dtr()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE As an example of the use of this function, let us consider a
|
|||
|
call back verification door, which hangs up on the user, and
|
|||
|
then calls the user back at their entered phone number, in order
|
|||
|
to verify the correctness of that number. This program would
|
|||
|
probably contain a function that is responsible for
|
|||
|
disconnecting the user, waiting for the connection to be broken,
|
|||
|
and then phoning the user. At some point in this function,
|
|||
|
likely just prior to the point where the function hangs up on
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 51
|
|||
|
|
|||
|
the user, you would disable OpenDoors' internal carrier
|
|||
|
detection, using the line:
|
|||
|
|
|||
|
od_control.od_disable |= DIS_CARRIERDETECT;
|
|||
|
|
|||
|
You would then want to have a piece of code which would simply
|
|||
|
wait up to a given amount of time for the carrier signal to
|
|||
|
drop. If this occurs, you would continue to place the call, and
|
|||
|
if it does not occur, you would probably try your hangup
|
|||
|
procedure one or two more times. In this example, the function
|
|||
|
will return with a value of FALSE if the carrier signal does not
|
|||
|
drop, and will return a value of TRUE if it does.
|
|||
|
|
|||
|
char hangup(void)
|
|||
|
{
|
|||
|
clock_t timer;
|
|||
|
char to_return = FALSE;
|
|||
|
|
|||
|
od_set_dtr(FALSE); /* Hangup modem */
|
|||
|
|
|||
|
/* Wait up to 30secs */
|
|||
|
timer = clock() + CLOCKS_PER_SEC * 30;
|
|||
|
while(timer >= clock())
|
|||
|
{ /* If carrier has been lost, return with success */
|
|||
|
if(!od_carrier())
|
|||
|
{
|
|||
|
to_return = TRUE;
|
|||
|
break;
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
od_set_dtr(TRUE); /* Re-enable DTR signal */
|
|||
|
return(to_return);
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 52
|
|||
|
|
|||
|
OD_CLEAR_KEYBUFFER()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to clear the input keyboard buffer
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_clear_keybuffer(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION OpenDoors maintains its own keyboard input buffer, in order to
|
|||
|
permit the user to "type ahead" - to send input to the door
|
|||
|
prior to the time when it is ready to process those key presses.
|
|||
|
For example, the user could begin to type a command while a menu
|
|||
|
is still being displayed, and when your door reaches the point
|
|||
|
of inputting the menu command, the characters already typed by
|
|||
|
the user will already be waiting for the OpenDoors input
|
|||
|
functions. Note that the keyboard input buffer will include both
|
|||
|
the keys hit by the user on-line, and the non-function keys (ie,
|
|||
|
Alt-C will not appear in the OpenDoors keyboard buffer), hit by
|
|||
|
the sysop. This allows both the user on-line and the sysop to
|
|||
|
control the door at any time. If the sysop wishes to temporarily
|
|||
|
prevent the user from having any control over the door, the
|
|||
|
sysop may use the Alt-K (user-keyboard off) key. The key strokes
|
|||
|
placed in the OpenDoors type-ahead buffer will be retrieved by
|
|||
|
the od_get_key() and od_input_str() functions. The keyboard
|
|||
|
buffer can contain a maximum of 64 user keystrokes in this
|
|||
|
version of OpenDoors, after which any additional keystrokes will
|
|||
|
simply be discarded by OpenDoors.
|
|||
|
|
|||
|
There are times, however, when you will want to erase any keys
|
|||
|
that have been hit by the user, to prevent them from typing
|
|||
|
ahead. For example, if your door has been busy doing some
|
|||
|
processing for a few moments, they user may have been pressing
|
|||
|
keys on their keyboard - perhaps in the hope that doing so will
|
|||
|
speed things up. These keys will be waiting in the type-ahead
|
|||
|
buffer, and if one of the keys the user entered was a valid
|
|||
|
response to the next prompt in your door, the user may find that
|
|||
|
they have accidentally made a choice they did not wish to. A
|
|||
|
well designed door will simply erase the contents of the type-
|
|||
|
ahead buffer after any long period of internal processing, etc.
|
|||
|
Keep in mind that too much use of the od_clear_keybuffer()
|
|||
|
function can be just as undesirable as not using it all, as
|
|||
|
there are times when the presence of the keyboard buffer can
|
|||
|
prove to be very useful for the user of a door.
|
|||
|
|
|||
|
To erase the contents of the type-ahead buffer, you simply call
|
|||
|
the od_clear_keybuffer() function. This function takes no
|
|||
|
parameters, and does not return any value.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 53
|
|||
|
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_get_key(), od_input_str(), od_edit_str()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For one example of the use of the od_clear_keybuffer() function,
|
|||
|
see the example program EX_VOTE.C, which is described beginning
|
|||
|
on page 38. Below is another example of using this function. In
|
|||
|
this case, we present a simple function, wait_for_return(),
|
|||
|
which simply pauses for the user to press their [Enter]/[Return]
|
|||
|
key. The function begins by displaying a prompt asking for the
|
|||
|
[Enter] or [Return] key to be pressed. The function then clears
|
|||
|
the keyboard input buffer, and waits until the user presses the
|
|||
|
carriage return key, using the od_get_key() function. Note also
|
|||
|
that this function will only continue if the user has pressed
|
|||
|
the correct key. This is a good idea in all door programs, as it
|
|||
|
allows your door to distinguish between a character pressed by
|
|||
|
the user, and a "line noise" character.
|
|||
|
|
|||
|
void wait_for_return(void)
|
|||
|
{ /* Display prompt */
|
|||
|
od_disp_str("Please Press [Enter] to continue...\n\r");
|
|||
|
od_clear_keybuffer(); /* Clear keyboard buffer */
|
|||
|
while(od_get_key(TRUE) != 13); /* Wait for Enter key */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 54
|
|||
|
|
|||
|
OD_CLR_LINE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Clears the rest of the current display line
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_clr_line(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function clears the line that the cursor is on, from the
|
|||
|
cursor position to the end of the line. After the rest of the
|
|||
|
line is cleared, the cursor is automatically returned to the
|
|||
|
position it was at prior to issuing the command. Hence, if the
|
|||
|
display line the cursor was located on looked as follows, with
|
|||
|
the underscore (_) character representing the cursor position:
|
|||
|
|
|||
|
This is a_line of text!
|
|||
|
|
|||
|
With the cursor between the words "a" and "line", after the
|
|||
|
od_clr_line command is issued, the line would appear as follows:
|
|||
|
|
|||
|
This is a_
|
|||
|
|
|||
|
With the cursor directly following the word "a". Note that this
|
|||
|
function places a space character at the cursor location, and
|
|||
|
every location up to the end of the line.
|
|||
|
|
|||
|
When the door is running in plain ASCII mode, this command will
|
|||
|
simply clear the rest of the line by manually sending a series
|
|||
|
of space and backspace characters. When ANSI, AVATAR or RIP
|
|||
|
modes are active, the corresponding ANSI/AVATAR control sequence
|
|||
|
will be sent in order to accomplish the line clear. Since the
|
|||
|
graphics mode sequences are much shorter than the sequence that
|
|||
|
would be required to clear the line manually, the use of this
|
|||
|
function will cause your door's graphics to display much more
|
|||
|
quickly when ANSI, AVATAR or RIP modes are active. Also note
|
|||
|
that in ANSI, AVATAR or RIP graphics modes, the line will be
|
|||
|
cleared with the currently selected color attribute. Thus, if
|
|||
|
you wanted to place a blue background on a particular line, you
|
|||
|
would use the od_set_color() (or od_set_attrib()) function, then
|
|||
|
use the od_set_cursor() function to locate the cursor at the
|
|||
|
beginning of the desired line, followed by the od_clr_line()
|
|||
|
function. Just such a procedure is demonstrated in the example,
|
|||
|
below.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_clr_scr(), od_set_cursor()
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 55
|
|||
|
|
|||
|
EXAMPLE Below, is an example of a function that clears an entire line
|
|||
|
with a specified color. Since this function performs operations
|
|||
|
that require ANSI, AVATAR or RIP graphics mode, it should only
|
|||
|
be used in a case where these modes are known to be available.
|
|||
|
For example, this function would be useful in a full-screen
|
|||
|
editor or viewer, or when performing ANSI animations. The
|
|||
|
function accepts three parameters: the line to be cleared (where
|
|||
|
1 is the first line, 2 the second, and so on), the foreground
|
|||
|
color of this line, and the background color of this line.
|
|||
|
|
|||
|
This function differs from the od_clr_line() function itself in
|
|||
|
several important manners. First of all, this function clears
|
|||
|
the entire line, whereas the od_clr_line() function can be used
|
|||
|
to clear only the remaining characters of the line, after any
|
|||
|
particular location. Also, as mentioned before, this function
|
|||
|
selects a color to clear the line to, and moves the cursor to
|
|||
|
the line which is to be cleared - neither of which is done by
|
|||
|
the od_clr_line() function.
|
|||
|
|
|||
|
|
|||
|
void clear_line(char line_number,char foreground,char
|
|||
|
background)
|
|||
|
{
|
|||
|
od_set_cursor(line_number,1); /* move to correct line */
|
|||
|
od_set_color(foreground,background); /* set color */
|
|||
|
od_clr_line(); /* clear entire line */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 56
|
|||
|
|
|||
|
OD_CLR_SCR()
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE The OpenDoors clear screen function
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_clr_scr(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION The od_clr_scr() function can be used to clear the output
|
|||
|
screen. (ie, the user's screen and local screen with the
|
|||
|
exception of the status line are cleared.) This function will
|
|||
|
only clear the screen if screen clearing is enabled. If your
|
|||
|
program will be running under BBS systems that do not pass the
|
|||
|
user's screen clearing setting to the door, you may wish to
|
|||
|
determine yourself whether or not the user's system supports
|
|||
|
screen clearing codes, during the first time the user uses the
|
|||
|
door. You will then be able to store this setting in a data
|
|||
|
file. The example below demonstrates how to detect whether or
|
|||
|
not the user's system supports screen clearing.
|
|||
|
|
|||
|
You should note that the ability for the user's terminal to
|
|||
|
support screen clearing codes is independent of the user's ANSI
|
|||
|
/ AVATAR / RIP graphics mode settings.
|
|||
|
|
|||
|
For more information on the user's screen clearing setting,
|
|||
|
please refer to the user_attrib variable in the OpenDoors
|
|||
|
Control Structure chapter of this manual. If you wish to force a
|
|||
|
screen clear, regardless of the user's screen clearing setting,
|
|||
|
simply use the function call:
|
|||
|
|
|||
|
od_disp_emu("\xc", TRUE);
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_clr_line()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below is an example of a function which determines whether or
|
|||
|
not the user's system supports screen clearing. This function
|
|||
|
will return a value of TRUE if screen clearing is supported, and
|
|||
|
will return a value of FALSE if screen clearing is not
|
|||
|
supported:
|
|||
|
|
|||
|
int user_supports_screen_clearing(void)
|
|||
|
{
|
|||
|
char answer;
|
|||
|
/* display instructions to user */
|
|||
|
od_disp_str("In order for this door to function\n\r");
|
|||
|
od_disp_str("correctly, we must know whether or not\n\r");
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 57
|
|||
|
|
|||
|
od_disp_str("your system supports screen clearing.\n\r");
|
|||
|
od_disp_str("In a moment, we will attempt to clear\n\r");
|
|||
|
od_disp_str(
|
|||
|
"your screen in order to test your system's\n\r");
|
|||
|
od_disp_str("capabilities.\n\r\n\r");
|
|||
|
|
|||
|
od_disp_str("Please press [Enter]/[Return] when you\n\r");
|
|||
|
od_disp_str("are ready to perform this test.\n\r");
|
|||
|
while(od_get_key(TRUE)!=13); /* wait for [Return] key */
|
|||
|
|
|||
|
od_clr_scr(); /* attempt to clear screen */
|
|||
|
/* ask user if their screen cleared */
|
|||
|
od_disp_str("Did your screen just clear? (Y/N)\n\r");
|
|||
|
for(;;) /* loop until user chooses [Y]es or [N]o */
|
|||
|
{
|
|||
|
answer=od_get_key(TRUE); /* Get user's answer */
|
|||
|
if(answer=='y' || answer=='Y') return(TRUE);
|
|||
|
if(answer=='n' || answer=='N') return(FALSE);
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 58
|
|||
|
|
|||
|
OD_COLOR_CONFIG()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Parses a color configuration line from the configuration file,
|
|||
|
generating a color attribute value.
|
|||
|
|
|||
|
|
|||
|
FORMAT BYTE od_color_config(char *pszColorDesc);
|
|||
|
|
|||
|
|
|||
|
RETURNS Color attribute value
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function will be of use if you are using the configuration
|
|||
|
file system of OpenDoors, and wish to allow the sysop to specify
|
|||
|
text colors to be used in your door. While OpenDoors
|
|||
|
automatically recognizes color configuration settings for things
|
|||
|
such as sysop chat mode and FILES.BBS listings, you may wish to
|
|||
|
add additional color configuration options. In this case, you
|
|||
|
could call the od_color_config() function from your custom line
|
|||
|
function. For more information on the custom line function, see
|
|||
|
the section on the OpenDoors configuration file system, which
|
|||
|
begins on page 224.
|
|||
|
|
|||
|
To use this function, simply pass the configuration file line
|
|||
|
you wish to have parsed to the function in it's single
|
|||
|
parameter. The function will then return a color attribute value
|
|||
|
in the same format that is used but the od_set_attrib()
|
|||
|
function. Colors are specified using a string of the format:
|
|||
|
|
|||
|
{Flashing} {Bright} [foreground] on [background]
|
|||
|
|
|||
|
Where "Flashing" is an optional keyword indicating that the text
|
|||
|
should be flashing. "Bright" is an optional keyword indicating
|
|||
|
that the foreground color should be bright. Foreground is the
|
|||
|
name of a foreground color, and background is the name of a
|
|||
|
background color. Case (upper or lower) is not significant.
|
|||
|
|
|||
|
The color keywords are language configurable, using the array
|
|||
|
od_control.od_color_names.
|
|||
|
|
|||
|
|
|||
|
EXAMPLE See the example accompanying in the section on the OpenDoors
|
|||
|
configuration file system, which begins on page 224.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 59
|
|||
|
|
|||
|
OD_DISP()
|
|||
|
------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Sends a buffer of text with optional local echo
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_disp(char *pachBuffer, INT nSize, BOOL bLocalEcho);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function allows you to send a buffer of text of any
|
|||
|
specified length, with the option of enabling or disabling local
|
|||
|
echo. You will probably have little use for this function -
|
|||
|
instead you will most likely display strings using either the
|
|||
|
od_disp_str() or od_printf() functions, depending on whether or
|
|||
|
not you wish to use printf()'s formatting options. For a
|
|||
|
breakdown of the uses of the various OpenDoors display
|
|||
|
functions, see the description of the od_disp_str() function, on
|
|||
|
page 63.
|
|||
|
|
|||
|
There are two cases when this function will come in useful:
|
|||
|
|
|||
|
1.)If you wish to display a buffer of characters of known
|
|||
|
length, which may contain null (ASCII 0) characters.
|
|||
|
Since this character is used by the C language to
|
|||
|
indicate the end of a string, the other two string
|
|||
|
display functions (od_disp_str() and od_printf()) will
|
|||
|
not send this character to the remote system.
|
|||
|
|
|||
|
2.)If you wish to send text to the remote system without
|
|||
|
having it displayed on the local screen, or if you wish
|
|||
|
to send strings to the modem when it is in command
|
|||
|
mode, without having these characters displayed on the
|
|||
|
local screen.
|
|||
|
|
|||
|
The od_disp() function is called with three parameters. The
|
|||
|
first parameter, pachBuffer, is a pointer to a buffer of
|
|||
|
characters you wish to have displayed. The second parameter,
|
|||
|
nSize, is simply the number of characters in the buffer to be
|
|||
|
displayed. If the third parameter, bLocalEcho, is set to TRUE,
|
|||
|
then all characters sent to the modem will also be displayed on
|
|||
|
the local screen. If the third parameter is set to FALSE, then
|
|||
|
the buffer will be sent to the modem without being echoed to the
|
|||
|
sysop's screen.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_disp_str(), od_printf(), od_putch(), od_repeat(),
|
|||
|
od_disp_emu()
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 60
|
|||
|
|
|||
|
EXAMPLES The following are a few examples of the use of the od_disp()
|
|||
|
function:
|
|||
|
|
|||
|
In order to display a single character, contained in the
|
|||
|
variable "character", without echo to the local screen:
|
|||
|
|
|||
|
od_disp(&character,1,FALSE);
|
|||
|
|
|||
|
|
|||
|
In order to send a command to the modem (only if you know that
|
|||
|
the modem is in command mode), with the command contained in the
|
|||
|
null-terminated string "string":
|
|||
|
|
|||
|
od_disp(string,strlen(string),FALSE);
|
|||
|
|
|||
|
|
|||
|
In order to send exactly 5 characters from the buffer "buffer",
|
|||
|
WITH echo to the local screen:
|
|||
|
|
|||
|
od_disp(buffer,5,TRUE);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 61
|
|||
|
|
|||
|
OD_DISP_EMU()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Displays a string with ANSI/AVATAR terminal emulation
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_disp_emu(char *pszToDisplay, BOOL bRemoteEcho);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION The od_disp_emu() function allows you to display your own ANSI /
|
|||
|
AVATAR graphics sequences. This function passes the characters
|
|||
|
you wish to display to the OpenDoors terminal emulator, which is
|
|||
|
fully documented in the description of the od_send_file()
|
|||
|
function, on page 124. This function can be used to send these
|
|||
|
control sequences to the user's terminal, and also have them
|
|||
|
displayed on the local screen as they will appear to the user.
|
|||
|
|
|||
|
The string passed to od_disp_emu() contains any stream of text
|
|||
|
to display, and may include both normal text and terminal
|
|||
|
emulation control sequences. If the bRemoteEcho parameter is set
|
|||
|
to TRUE, the string passed to od_disp_emu() will be sent to the
|
|||
|
remote terminal in addition to being displayed locally. If this
|
|||
|
parameter is set to FALSE, the string will only be displayed
|
|||
|
locally.
|
|||
|
|
|||
|
Note that if you wish to display an entire file containing
|
|||
|
ANSI/AVATAR/RIP graphics sequences (perhaps as your program's
|
|||
|
menu or title screen), you can use the od_send_file() function.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_send_file(), od_disp(), od_disp_str() od_printf().
|
|||
|
|
|||
|
For a breakdown of the uses of the various OpenDoors display
|
|||
|
functions, see the od_disp_str() function, on page 63.
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_disp_emu() function, see the
|
|||
|
SpaceRight() and MoveLeft() functions included in the example
|
|||
|
program ex_ski.c.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 62
|
|||
|
|
|||
|
OD_DISP_STR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Displays a string to the screen (remote and local)
|
|||
|
|
|||
|
|
|||
|
FORMAT od_disp_str(char *pszToDisplay);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION The two functions most often used for displaying strings within
|
|||
|
a door are the od_disp_str() and od_printf() functions. The
|
|||
|
od_printf() function allows for formatted output, whereas the
|
|||
|
od_disp_str function simply displays the actual contents of the
|
|||
|
string passed to it. If you wish to display a single character,
|
|||
|
use the od_putch() function. If you wish to send a string or
|
|||
|
buffer to the modem without local echo, use the od_disp()
|
|||
|
function. If you wish to send a sequence of the same character
|
|||
|
to the modem, the od_repeat() function will use graphics control
|
|||
|
codes, if available to display the sequence much faster than
|
|||
|
simply sending the same character in repetition. Also, if you
|
|||
|
wish to send ANSI, AVATAR or RIP graphics control codes, and
|
|||
|
have them emulated on the local screen, use the od_disp_emu()
|
|||
|
function.
|
|||
|
|
|||
|
The od_disp_str() function displays the contents of the null-
|
|||
|
terminated string pointed to by *string. Display is sent to both
|
|||
|
the local screen and modem (presuming the door is not running in
|
|||
|
local mode).
|
|||
|
|
|||
|
An important thing to keep in mind when using the od_disp_str()
|
|||
|
function, is that you should use "/n/r" instead of simply "/n"
|
|||
|
for a new line. This is due to the fact that terminal programs
|
|||
|
usually require a carriage-return line-feed sequence (/n/r),
|
|||
|
instead of just a line-feed (/n). For example, instead of using:
|
|||
|
|
|||
|
od_disp_str("Hello world!\n");
|
|||
|
|
|||
|
You should use:
|
|||
|
|
|||
|
od_disp_str("Hello world!\n\r");
|
|||
|
|
|||
|
To change the cursor color or location of output with the
|
|||
|
od_disp_str() function, refer to the od_set_cursor() and the
|
|||
|
od_set_attrib() functions.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_disp(), od_printf(), od_putch(), od_repeat(), od_disp_emu()
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 63
|
|||
|
|
|||
|
EXAMPLES Below are a few examples of various uses of the od_disp_str()
|
|||
|
function:
|
|||
|
|
|||
|
Displaying three string constants on separate lines:
|
|||
|
|
|||
|
od_disp_str("This is an example\n\r");
|
|||
|
od_disp_str("of the OpenDoors\n\r");
|
|||
|
od_disp_str("od_disp_str() function\n\r");
|
|||
|
|
|||
|
|
|||
|
Displaying three string constants on the same line:
|
|||
|
|
|||
|
od_disp_str("Another ");
|
|||
|
od_disp_str("od_disp_str() ");
|
|||
|
od_disp_str("example\n\r");
|
|||
|
|
|||
|
|
|||
|
Displaying a string variable:
|
|||
|
|
|||
|
char string[80];
|
|||
|
|
|||
|
strcpy(string,"This is a string!\n\r");
|
|||
|
od_disp_str(string);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 64
|
|||
|
|
|||
|
OD_DRAW_BOX()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Draws a box on the screen in ANSI, AVATAR or RIP graphics modes.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_draw_box(BYTE btLeft, BYTE btTop, BYTE btRight, BYTE
|
|||
|
btBottom);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success, FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function is for use in ANSI, AVATAR or RIP graphics modes.
|
|||
|
This function will draw a box in the current display attribute,
|
|||
|
at the specified location on the screen. The boarder of the box
|
|||
|
is made up of the characters specified in the od_control.
|
|||
|
od_box_chars[] array. If AVATAR graphics mode is available, this
|
|||
|
function uses AVATAR control codes to display the box in less
|
|||
|
than 1/10 the length of time required to display the box in ANSI
|
|||
|
mode.
|
|||
|
|
|||
|
The first two parameters of this function, btLeft and btTop,
|
|||
|
specify the coordinates of the top, left-hand corner of the box
|
|||
|
to be draw. The third and fourth parameters, btRight and
|
|||
|
btBottom, specify the coordinates of the bottom, left-hand
|
|||
|
corner of the box. Like the values passed to the od_set_cursor()
|
|||
|
function, these coordinates are relative to the upper left-hand
|
|||
|
corner of the screen, with the position (1,1) being this corner.
|
|||
|
|
|||
|
As mentioned above, this function will display the window in the
|
|||
|
current text color. Thus, before calling this function, you
|
|||
|
should use either the od_set_color() or the od_set_attrib()
|
|||
|
function to specify the color in which you would like to have
|
|||
|
the window displayed.
|
|||
|
|
|||
|
Normally, the boarder of the window will be displayed using the
|
|||
|
IBM extended ASCII characters which produce a single line
|
|||
|
boarder. However, you may wish to have the boarder displayed
|
|||
|
using different characters. In this case, the characters used to
|
|||
|
display the boarder can be specified by the od_control.
|
|||
|
od_box_chars variable, described in the OpenDoors control
|
|||
|
structure section of this manual.
|
|||
|
|
|||
|
SEE ALSO od_set_color(), od_set_attrib(), od_clr_scr(), od_edit_str(),
|
|||
|
od_set_cursor()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE As an example of the use of the od_draw_box() function in
|
|||
|
conjunction with the od_edit_str() function, we show a portion
|
|||
|
of a program which displays a window, and allows the user to
|
|||
|
input the name of a file they would like to upload, a
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 65
|
|||
|
|
|||
|
description of the file, and whether they want it to be a
|
|||
|
private upload. The user is able to move among fields using the
|
|||
|
tab key, and select a "continue" button when they are finished.
|
|||
|
The function returns TRUE if the user selects continue, and
|
|||
|
FALSE if the user presses [ESCape].
|
|||
|
|
|||
|
// Main "dialog box" function
|
|||
|
int get_information(char *filename, char *description,
|
|||
|
char *private)
|
|||
|
{
|
|||
|
char current_field=1; // Currently selected field
|
|||
|
int choice; // User's choice
|
|||
|
|
|||
|
od_set_color(L_WHITE,D_BLUE); // Display window
|
|||
|
od_draw_box(10,5,70,13);
|
|||
|
|
|||
|
od_set_cursor(5,25); // Display window title
|
|||
|
od_set_color(L_GREEN,D_BLUE);
|
|||
|
od_disp_str(" ENTER FILENAME INFORMATION ");
|
|||
|
|
|||
|
od_set_color(L_CYAN,D_BLUE); // Display fields and titles
|
|||
|
od_set_cursor(6,15);
|
|||
|
od_disp_str("FILENAME : ");
|
|||
|
od_repeat(176,13);
|
|||
|
od_set_cursor(7,12);
|
|||
|
od_disp_str("DESCRIPTION : ");
|
|||
|
od_repeat(176,43);
|
|||
|
od_set_cursor(8,16);
|
|||
|
od_disp_str("PRIVATE : ");
|
|||
|
od_repeat(176,2);
|
|||
|
draw_button();
|
|||
|
|
|||
|
filename[0]='\0'; // Blank out contents of input variables
|
|||
|
description[0]='\0';
|
|||
|
private[0]='\0';
|
|||
|
|
|||
|
for(;;) // Main dialog box loop
|
|||
|
{
|
|||
|
if(current_field==4) // If field is the button
|
|||
|
{
|
|||
|
od_set_color(L_GREEN,D_BLUE); // Highlight button
|
|||
|
draw_button();
|
|||
|
|
|||
|
do // Loop until user presses [TAB], [ENTER], or [ESC]
|
|||
|
{
|
|||
|
choice=od_get_key(TRUE);
|
|||
|
} while(choice!=9 && choice!=13 && choice!=27);
|
|||
|
|
|||
|
od_set_color(L_CYAN,D_BLUE); // Un-highlight button
|
|||
|
draw_button();
|
|||
|
|
|||
|
if(choice==13) return(TRUE); // If [ENTER] was pressed
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 66
|
|||
|
|
|||
|
if(choice==27) return(FALSE); // If [ESC] was pressed
|
|||
|
current_field=1; // Otherwise, [TAB] was pressed
|
|||
|
}
|
|||
|
|
|||
|
switch(current_field) // According to selected field
|
|||
|
{ // Input from the appropriate line
|
|||
|
case 1:
|
|||
|
choice=od_edit_str(filename,"FFFFFFFFFFFF",6,26,
|
|||
|
0x1b,0x1a,176,
|
|||
|
EDIT_FLAG_EDIT_STRING|
|
|||
|
EDIT_FLAG_ALLOW_CANCEL|
|
|||
|
EDIT_FLAG_FIELD_MODE|
|
|||
|
EDIT_FLAG_KEEP_BLANK);
|
|||
|
break;
|
|||
|
case 2:
|
|||
|
choice=od_edit_str(description,
|
|||
|
"*******************",
|
|||
|
7,26,0x1b,0x1a,176,
|
|||
|
EDIT_FLAG_EDIT_STRING|
|
|||
|
EDIT_FLAG_ALLOW_CANCEL|
|
|||
|
EDIT_FLAG_FIELD_MODE|
|
|||
|
EDIT_FLAG_KEEP_BLANK);
|
|||
|
|
|||
|
break;
|
|||
|
case 3:
|
|||
|
choice=od_edit_str(private,"Y",8,26,
|
|||
|
0x1b,0x1a,176,
|
|||
|
EDIT_FLAG_EDIT_STRING|
|
|||
|
EDIT_FLAG_ALLOW_CANCEL|
|
|||
|
EDIT_FLAG_FIELD_MODE);
|
|||
|
}
|
|||
|
// If user pressed [ESCape]
|
|||
|
if(choice==EDIT_RETURN_CANCEL) return(FALSE);
|
|||
|
// If user choice to go to previous field
|
|||
|
if(choice==EDIT_RETURN_PREVIOUS)
|
|||
|
{
|
|||
|
if(current_field==1) // If at first field
|
|||
|
current_field=4; // Go to last field
|
|||
|
else // If not at first field
|
|||
|
--current_field; // Go to previous field
|
|||
|
}
|
|||
|
else // If user chose next field
|
|||
|
++current_field; // Go to next field
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
void draw_button(void) // Function to display the button
|
|||
|
{
|
|||
|
od_draw_box(12,10,23,12); // Draw box for button
|
|||
|
od_set_cursor(11,14);
|
|||
|
od_disp_str("Continue"); // Display text in button
|
|||
|
}
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 67
|
|||
|
|
|||
|
OD_EDIT_STR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Allows you to perform formatted input with full line editing
|
|||
|
features, etc., in ANSI/AVATAR/RIP graphics mode.
|
|||
|
|
|||
|
|
|||
|
FORMAT WORD od_edit_str(char *pszInput, char *pszFormat, INT nRow,
|
|||
|
INT nColumn, BYTE btNormalColor, BYTE btHighlightColor,
|
|||
|
char chBlank, WORD nFlags);
|
|||
|
|
|||
|
|
|||
|
RETURNS This function will return one of the following values:
|
|||
|
|
|||
|
EDIT_RETURN_ERROR Indicates that an error has occurred,
|
|||
|
and the edit function was unable to
|
|||
|
run. This will occur if there is an
|
|||
|
error in one of the parameters, or if
|
|||
|
ANSI/AVATAR/RIP graphics is not
|
|||
|
available
|
|||
|
|
|||
|
EDIT_RETURN_CANCEL Indicates that the user pressed the
|
|||
|
cancel key [ESC], and that the string
|
|||
|
was left unaltered.
|
|||
|
|
|||
|
EDIT_RETURN_ACCEPT Indicates that the user pressed the
|
|||
|
accept key [Enter], or that the auto-
|
|||
|
enter feature was activated.
|
|||
|
|
|||
|
EDIT_RETURN_PREVIOUS Indicates that the user wishes to move
|
|||
|
to the previous field, by pressing [UP
|
|||
|
ARROW], [SHIFT]-[TAB], etc.
|
|||
|
|
|||
|
EDIT_RETURN_NEXT Indicates that the user wishes to move
|
|||
|
to the next field, by pressing [DOWN
|
|||
|
ARROW], [TAB], etc.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION To perform string input within OpenDoors, one of two functions
|
|||
|
can be used, od_input_str() and od_edit_str(). The first
|
|||
|
function, od_input_str(), allows simple line input and editing,
|
|||
|
and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
|
|||
|
function, od_edit_str(), allows many formatted input options,
|
|||
|
advanced line editing, and other features, but requires the use
|
|||
|
of ANSI, AVATAR or RIP terminal modes.
|
|||
|
|
|||
|
As mentioned above, the od_edit_str() function allows for
|
|||
|
advanced line editing, such as inputting and deleting text from
|
|||
|
the middle of the string (whereas the od_input_str() function
|
|||
|
only allows editing from the end of the string, such as
|
|||
|
backspacing to erase a mistake). The edit functions available
|
|||
|
from the od_edit_str() are listed below. Note that some of these
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 68
|
|||
|
|
|||
|
functions may or may not be available, depending upon the
|
|||
|
capabilities of the user's terminal program. While there is no
|
|||
|
single standard used for the transmission of special edit keys
|
|||
|
such as the arrow keys, the od_edit_str() function makes as much
|
|||
|
effort as possible to make all of the edit features available to
|
|||
|
most terminal programs. Many of the edit functions can be
|
|||
|
accesses using either [CONTROL]-key combinations or special keys
|
|||
|
such as the arrow keys, delete key, and so on. OpenDoors will
|
|||
|
recognize most of these special control keys when sent as either
|
|||
|
an ANSI control sequence (which is sent by most terminal
|
|||
|
programs), or as a DoorWay style scan code / ASCII code sequence
|
|||
|
(which is also available from many terminal programs, but is not
|
|||
|
usually required). The od_edit_str() edit functions are as
|
|||
|
follows. Note that all edit functions are always available from
|
|||
|
the local keyboard.
|
|||
|
|
|||
|
HOME - Moves the cursor to the beginning of the line being
|
|||
|
edited. Press the [HOME] key, either in DoorWay mode
|
|||
|
or from the local keyboard.
|
|||
|
|
|||
|
END - Moves the cursor to the end of the line being edited.
|
|||
|
Press the [END] key, either in DoorWay mode or from
|
|||
|
the local keyboard.
|
|||
|
|
|||
|
DELETE CHARACTER - Deletes the character under the cursor. Press
|
|||
|
[DELete] on the local keyboard, in DoorWay mode, and
|
|||
|
under many terminal programs without DoorWay mode.
|
|||
|
Alternatively, press [CONTROL]-[G].
|
|||
|
|
|||
|
BACKSPACE - Deletes the character left of the cursor. Press
|
|||
|
[BACKSPACE] or [CONTROL]-[H].
|
|||
|
|
|||
|
TOGGLE INSERT MODE - Switches the od_edit_str() function between
|
|||
|
insert mode and overwrite mode. Press [INSert], either
|
|||
|
in DoorWay mode, or from the local keyboard.
|
|||
|
Alternatively, press [CONTROL]-[V].
|
|||
|
|
|||
|
CURSOR LEFT - Moves the cursor left one character. Press [LEFT
|
|||
|
ARROW] on the local keyboard, in DoorWay mode, and
|
|||
|
under many terminal programs without DoorWay mode.
|
|||
|
Alternatively, press [CONTROL]-[S].
|
|||
|
|
|||
|
CURSOR RIGHT - Moves the cursor right one character. Press
|
|||
|
[RIGHT ARROW] on the local keyboard, in DoorWay mode,
|
|||
|
and under many terminal programs without DoorWay mode.
|
|||
|
Alternatively, press [CONTROL]-[D].
|
|||
|
|
|||
|
ERASE ENTIRE LINE - Press [CONTROL]-[Y].
|
|||
|
|
|||
|
ACCEPT INPUT - Press the [ENTER] / [RETURN] line to accept the
|
|||
|
input. Alternatively, press [CONTROL]-[Z]. Note that
|
|||
|
this key will only work when the current input is
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 69
|
|||
|
|
|||
|
"valid" (ie, it conforms to the format string, which
|
|||
|
is described below)
|
|||
|
|
|||
|
CANCEL INPUT - Only available if specifically enabled on the
|
|||
|
od_edit_str() command line. Press [ESCape].
|
|||
|
|
|||
|
NEXT FIELD - If enabled, allows the user to move to the next
|
|||
|
field in a dialog box / form. Press [DOWN ARROW] in
|
|||
|
DoorWay mode and under many terminal programs without
|
|||
|
DoorWay mode. Alternatively, press [TAB]. Note that
|
|||
|
the [DOWN ARROW] key is NOT usually available from the
|
|||
|
local keyboard, as it is usually used to adjust the
|
|||
|
user's remaining time.
|
|||
|
|
|||
|
PREVIOUS FIELD - If enabled, allows the user to move to the
|
|||
|
previous field in a dialog box / form. Press [UP
|
|||
|
ARROW] in DoorWay mode and under many terminal
|
|||
|
programs without DoorWay mode. Alternatively, press
|
|||
|
[SHIFT]-[TAB] on the local keyboard or in DoorWay
|
|||
|
mode. Again, note that the [UP ARROW] key is NOT
|
|||
|
usually available from the local keyboard, as it is
|
|||
|
usually used to adjust the user's remaining time.
|
|||
|
|
|||
|
|
|||
|
Let us now look at the parameters which the od_edit_str()
|
|||
|
function accepts. The first parameter, pszInput, is a pointer to
|
|||
|
the string where the user's input should be stored. It is
|
|||
|
important that this string be long enough to accommodate the
|
|||
|
longest input your format string will permit, including the '\0'
|
|||
|
C string terminator (ie, the string should be one character
|
|||
|
greater than the length of the format string, not including the
|
|||
|
format string's ' and " characters).
|
|||
|
|
|||
|
The second parameter, pszFormat, is a pointer to a string which
|
|||
|
specifies the format and maximum length of the input the
|
|||
|
od_edit_str() function should accept. Using the format string,
|
|||
|
not only do you specify the length of the input field, but you
|
|||
|
can also force the user's input into certain formats. For
|
|||
|
example, if you wished to input a North American style phone
|
|||
|
number, you could use a format string of "###-###-####". Then
|
|||
|
regardless of whether the user typed any dash character or not,
|
|||
|
their input would be converted, as they type, to the format of
|
|||
|
the phone number 613-599-5554. You could also specify a format
|
|||
|
string such of "MMMMMMMMMMMMMMMMMMMMMMMMMMMMMM", which would
|
|||
|
permit the user to enter a name of up to 30 characters. Note
|
|||
|
that since the cursor can be moved to the position immediately
|
|||
|
following the last character, a the input field for a 30
|
|||
|
character string will occupy 31 columns on the screen. The
|
|||
|
od_edit_str() function would then automatically capitalize the
|
|||
|
name, so that the first character of each word is capitalized,
|
|||
|
and the remain characters of the word is in lower case. Even if
|
|||
|
the user were to move the cursor to the middle of the string
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 70
|
|||
|
|
|||
|
they had entered, and add or delete a space (and thus either
|
|||
|
make one work two or two words one), od_edit_str() would re-
|
|||
|
format the string to reflect the change. The valid characters
|
|||
|
for the format sting, along with their meanings, are listed
|
|||
|
below. Note that the format string is NOT case sensitive (except
|
|||
|
for literal strings delimited by the '' or "" characters), and
|
|||
|
space characters can be added at any point to increase
|
|||
|
legibility.
|
|||
|
|
|||
|
# Indicates that numeric characters from '0' to '9' are valid
|
|||
|
for this position
|
|||
|
|
|||
|
% Indicates that numeric characters from '0' to '9', and the
|
|||
|
space character (' ') are valid for this position.
|
|||
|
|
|||
|
9 Indicates that numeric characters from '0' to '9', along
|
|||
|
with '.', '-' and '+' are valid for this position. This
|
|||
|
format style is intended for floating-point numeric input.
|
|||
|
|
|||
|
? Indicates that any character is valid for this position.
|
|||
|
|
|||
|
* Indicates that any printable character, from ASCII 32 to
|
|||
|
ASCII 127, is valid for this position.
|
|||
|
|
|||
|
A Indicates that alphabetical characters 'A' to 'Z', 'a' to
|
|||
|
'z' and space (' ') are valid for this position.
|
|||
|
|
|||
|
C Indicates that city name characters are valid for this
|
|||
|
position. As with the 'M' format character, words are
|
|||
|
automatically capitalized so that the first letter is in
|
|||
|
upper case, and all subsequent letters are in lower case.
|
|||
|
In addition to permitting alphabetical characters and the
|
|||
|
space (' ') character, the ',' and '.' characters are also
|
|||
|
accepted in this position.
|
|||
|
|
|||
|
D Indicates that date characters '0' to '9', '-' and '/' are
|
|||
|
valid for this position.
|
|||
|
|
|||
|
F Indicates that MS-DOS filename characters are valid for
|
|||
|
this position.
|
|||
|
|
|||
|
H Indicates that hexidecimal character '0' to '9', 'A' to 'F'
|
|||
|
and 'a' to 'f' are valid for this position.
|
|||
|
|
|||
|
L Indicates that only lower case alphabetical characters 'a'
|
|||
|
to 'z', and the space (' ') character is valid for this
|
|||
|
position. However, if the user attempts to enter an upper
|
|||
|
case alphabetical character in this position, it will
|
|||
|
automatically be converted to the lower case equivalent.
|
|||
|
|
|||
|
M Indicates that name characters are valid for this position.
|
|||
|
These characters are the alphabetical characters 'A' to
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 71
|
|||
|
|
|||
|
'Z', 'a' to 'z', and the space character (' '). A
|
|||
|
character's case is converted such that the first character
|
|||
|
of a word is in upper case, and all other letters are in
|
|||
|
lower case.
|
|||
|
|
|||
|
T Indicates that telephone number character '0' to '9', '(',
|
|||
|
')', '-' and ' ' are valid for this position.
|
|||
|
|
|||
|
U Indicates that only upper case alphabetical characters 'A'
|
|||
|
to 'Z', and the space (' ') character is valid for this
|
|||
|
position. However, if the user attempts to enter a lower
|
|||
|
case alphabetical character in this position, it will
|
|||
|
automatically be converted to the upper case equivalent.
|
|||
|
|
|||
|
W Indicates that MS-DOS filename characters are permitted in
|
|||
|
this position, including the '*' and '?' wildcard
|
|||
|
characters.
|
|||
|
|
|||
|
X Indicates that alphanumeric characters 'A' to 'Z', 'a' to
|
|||
|
'z', '0' to '9' and ' ' are valid for this position.
|
|||
|
|
|||
|
Y Indicates that yes/no characters 'Y', 'N', 'y', 'n' are
|
|||
|
valid for this position. The characters are automatically
|
|||
|
converted to upper case.
|
|||
|
|
|||
|
'/" Single or double quotes can be used to specify sequences of
|
|||
|
characters that should appear at the same location in the
|
|||
|
input string (referred to elsewhere as "literal strings").
|
|||
|
When the user is entering the string, these characters are
|
|||
|
automatically supplied, and the user is not required to
|
|||
|
type them. Literal strings must begin and end with the same
|
|||
|
quote character. Remember that the double quote (")
|
|||
|
character must be imbedded in C strings by preceding the
|
|||
|
quote character with a \ (backslash) character.
|
|||
|
|
|||
|
The third and fourth parameters, nRow and nColumn specify the
|
|||
|
location on the screen where the first (left most) character of
|
|||
|
the input field should be located. These parameters are
|
|||
|
identical to the nRow and nColumn parameters passed to the
|
|||
|
od_set_cursor() function. In other words, nRow specifies the
|
|||
|
line number on the screen, where 1 is the first line, and
|
|||
|
nColumn specifies the column across the screen, where 1 is the
|
|||
|
first column.
|
|||
|
|
|||
|
The fifth and sixth parameters, btNormalColor and
|
|||
|
btHighlightColor, allow you to specify the color of the input
|
|||
|
field. The fifth parameter, btNormalColor, specifies the color
|
|||
|
of the input field when input is not taking place and the sixth
|
|||
|
parameter, btHighlightColor, specifies the color of the field
|
|||
|
while input is taking place. Thus, if you had several input
|
|||
|
fields on the screen at one time, you would be able to make is
|
|||
|
easier for the user to identify the currently active field by
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 72
|
|||
|
|
|||
|
having the field currently accepting input highlighted in a
|
|||
|
color distinct from the other fields. When the od_edit_str()
|
|||
|
function begins, it will change the current color of the field
|
|||
|
from the normal color to the highlighted color. Then, when the
|
|||
|
od_edit_str() function exits, it will change the current color
|
|||
|
of the field back to its normal color. If you do not wish to
|
|||
|
have the field highlighted, you can set both of these parameters
|
|||
|
to the same value, and disable field re-drawing by using the
|
|||
|
eighth parameter, flags.
|
|||
|
|
|||
|
The seventh parameter accepted by the od_edit_str() function,
|
|||
|
chBlank, will serve one of two purposes. Normally, this
|
|||
|
parameter will specify a background character to display in the
|
|||
|
unfilled portion at the end of the input field. This can be set
|
|||
|
to a character, such as the ASCII 177 grey block character, to
|
|||
|
produce a visual background to the field. Doing this will show
|
|||
|
the user visually how long the field is, and how many character
|
|||
|
they will be permitted to type into the field. Normally, this
|
|||
|
field will be displayed during input, and removed when the
|
|||
|
od_edit_str() function exits. However, you may cause the
|
|||
|
background to remain in place using the eighth parameter, flags.
|
|||
|
If you do not wish to have this "background" visual field
|
|||
|
effect, simply set the character parameter to a space (ASCII
|
|||
|
32). In password input mode, this parameter will instead specify
|
|||
|
the character to display in place of characters typed by the
|
|||
|
user. In this case, the background display character defaults to
|
|||
|
the space (ASCII 32) character.
|
|||
|
|
|||
|
The eighth, and last, parameter accepted by the od_edit_str()
|
|||
|
function is the nFlags parameter. This parameter is a bit-mapped
|
|||
|
flags variable which allows you to control special features of
|
|||
|
the od_edit_str() function. More than one of these settings may
|
|||
|
be specified by listing a chain of the values, separated by the
|
|||
|
bitwise-or (|) operator. If you do not wish to turn on any of
|
|||
|
these modes, simply pass the EDIT_FLAG_NORMAL value as the flags
|
|||
|
parameter.
|
|||
|
|
|||
|
EDIT_FLAG_NORMAL - Default setting, use this value of none of
|
|||
|
the other flags below are active.
|
|||
|
|
|||
|
EDIT_FLAG_NO_REDRAW - When set, prevents the od_edit_str()
|
|||
|
function from re-drawing the input string and field
|
|||
|
when it starts up and exits. If you set this flag, the
|
|||
|
normal color and highlight color should contain the
|
|||
|
same value. If background character (the character
|
|||
|
parameter) is not a space (ASCII 32) character, you
|
|||
|
must draw the field background prior to calling
|
|||
|
od_edit_str(). Also, if you are calling od_edit_str()
|
|||
|
with the EDIT_FLAG_EDIT_STRING flag set, you must
|
|||
|
display the existing string in the field prior to
|
|||
|
calling od_edit_str().
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 73
|
|||
|
|
|||
|
EDIT_FLAG_FIELD_MODE - Setting this flag specifies that
|
|||
|
od_edit_str() should operate in field input mode. In
|
|||
|
field input mode, the user may finish entering their
|
|||
|
input by pressing the previous field or next field
|
|||
|
button (arrow keys, tab keys, etc.), as described
|
|||
|
above. If the user chooses to finish and accept their
|
|||
|
input by pressing one of these keys, the od_edit_str()
|
|||
|
return value will reflect which choice they made. This
|
|||
|
will allow you to make it possible for the user to
|
|||
|
move between a number of input fields in a form /
|
|||
|
dialog box, as demonstrated in the example
|
|||
|
accompanying the od_draw_box() function.
|
|||
|
|
|||
|
EDIT_FLAG_EDIT_STRING - Setting this flag specifies that
|
|||
|
od_edit_str() should edit a pre-existing string,
|
|||
|
instead of starting with a blank string. In this case,
|
|||
|
the input_string parameter MUST point to an
|
|||
|
initialized string. This string may either contain
|
|||
|
some text, or be empty, but od_edit_str() will expect
|
|||
|
to find a string terminator ('\0') character, and will
|
|||
|
begin editing the contents of the string prior to that
|
|||
|
character. If you do not set the EDIT_FLAG_EDIT_STRING
|
|||
|
flag, the previous contents of the input_string
|
|||
|
parameter is not significant, as od_edit_str() will
|
|||
|
automatically start with a blank string.
|
|||
|
|
|||
|
EDIT_FLAG_STRICT_INPUT - Setting this flag causes the
|
|||
|
od_edit_str() function to operate in "strict" input
|
|||
|
mode, which may be desirable if your input format
|
|||
|
contains more than one type of input. Normally, if you
|
|||
|
were inputting such a string, the user would be able
|
|||
|
to move to the middle of the string, and insert any
|
|||
|
text. Doing so would cause the rest of the input line
|
|||
|
to shift right. However, in cases where your format
|
|||
|
string specifies different types of character to be
|
|||
|
permitted in different positions, this can cause the
|
|||
|
input to be changed so that it no longer conforms to
|
|||
|
the format string. In this case, the user's input will
|
|||
|
no longer be valid, and the user will not be able to
|
|||
|
exit the function by pressing [ENTER] (although
|
|||
|
[ESCAPE] will still be available, if you activated it)
|
|||
|
until they change their input. However, when strict
|
|||
|
input mode is turned on, od_edit_str() will restrict
|
|||
|
the ways in which the user is permitted to edit the
|
|||
|
string, to prevent just such a case from occurring.
|
|||
|
|
|||
|
EDIT_FLAG_PASSWORD_MODE - Setting this flag causes the
|
|||
|
od_edit_str() function to operate in "password" mode.
|
|||
|
In password mode, the characters typed by the user
|
|||
|
will be hidden, displayed instead as the blank
|
|||
|
character specified in the "character" parameter.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 74
|
|||
|
|
|||
|
EDIT_FLAG_ALLOW_CANCEL - When this flag is set, the user will be
|
|||
|
able to cancel their current input and abort the
|
|||
|
editing process by pressing their [ESCAPE] key. When
|
|||
|
they do so, any changes they have made to the input
|
|||
|
field will be canceled, and replaced by the original
|
|||
|
contents of the string. The od_edit_str() function
|
|||
|
will then exit, indicating that the user has canceled
|
|||
|
their input.
|
|||
|
|
|||
|
EDIT_FLAG_FILL_STRING - When set, this flag will force the user
|
|||
|
to enter a string that fills the entire length of the
|
|||
|
format string. Normally, the user will be able to
|
|||
|
enter a string of any length up to the maximum length
|
|||
|
specified by the format string. However in some cases,
|
|||
|
such as when inputting a date, you will want to have
|
|||
|
the input field filled. (Otherwise, the user would be
|
|||
|
able to enter only the first part of the date.)
|
|||
|
|
|||
|
EDIT_FLAG_AUTO_ENTER - When set, this flag will cause the
|
|||
|
od_edit_str() function to automatically simulate
|
|||
|
pressing of the [ENTER] key when the string is filled.
|
|||
|
This can be used to cause the od_edit_str() function
|
|||
|
to finish inputting as soon as a valid string is
|
|||
|
entered, instead of having to wait for the user to
|
|||
|
press [ENTER] / [RETURN].
|
|||
|
|
|||
|
EDIT_FLAG_AUTO_DELETE - When set, along with the
|
|||
|
EDIT_FLAG_EDIT_STRING flag, this flag will activate
|
|||
|
the auto-delete feature of the od_edit_str() function.
|
|||
|
When auto-delete is active, if the first key pressed
|
|||
|
by the user is not an edit control key, the existing
|
|||
|
text will automatically be deleted, and a totally new
|
|||
|
string accepted from the user. This could be useful
|
|||
|
when you are allowing the user to go back to edit a
|
|||
|
previous input. If the user wishes to only change part
|
|||
|
of the old string, they can move the cursor to the
|
|||
|
location where they wish to make the change, and
|
|||
|
perform their editing. However, if the user wishes to
|
|||
|
completely replace the old string with a new one, they
|
|||
|
can simply begin to type, and the old string will
|
|||
|
automatically be deleted, and the new string accepted.
|
|||
|
|
|||
|
EDIT_FLAG_KEEP_BLANK - Normally, OpenDoors will only display the
|
|||
|
input field background (as passed in the "character"
|
|||
|
parameter) while the user is editing the string, and
|
|||
|
will remove it when the od_edit_str() function exits.
|
|||
|
However, you may wish to continue having this field
|
|||
|
displayed after input has taken place, and the
|
|||
|
od_edit_str() function has exited. In this case,
|
|||
|
setting this flag will cause the background characters
|
|||
|
to remain visible after input has finished.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 75
|
|||
|
|
|||
|
EDIT_FLAG_PERMALITERAL - When the format string contains literal
|
|||
|
characters (such as forcing a ':' character to be
|
|||
|
added to a time input by using the format string
|
|||
|
"##':'##':'##"), the od_edit_str() function can
|
|||
|
operate in one of two modes. In the default mode, the
|
|||
|
literal characters will only be displayed when they
|
|||
|
have been automatically added to the string. For
|
|||
|
instance, if you were inputting the current time using
|
|||
|
the above format string, this mode would result in the
|
|||
|
input field initially being blank. When the user types
|
|||
|
the first digit of the time, that number would appear.
|
|||
|
When the user types the second digit of the time, that
|
|||
|
number will appear, and then the colon character will
|
|||
|
automatically be added by OpenDoors. However, you can
|
|||
|
also set the od_edit_str() function to operate in
|
|||
|
"PermaLiteral" mode, by setting this flag. When the
|
|||
|
EDIT_FLAG_PERMALITERAL flag is set, the input field
|
|||
|
will initially contain the literal characters (ie, the
|
|||
|
colons in our example), with the cursor still located
|
|||
|
at the leftmost position in the input field. In this
|
|||
|
mode, the literal character become a permanent part of
|
|||
|
the input field, and can not be moved or deleted by
|
|||
|
the user - instead the cursor simply skips over the
|
|||
|
literal character's position.
|
|||
|
|
|||
|
EDIT_FLAG_LEAVE_BLANK - This flag applies to the special case
|
|||
|
where the first character or characters of the format
|
|||
|
string are literals. By default, the od_edit_str()
|
|||
|
function will always return a string containing at
|
|||
|
least these first literal characters. However, you can
|
|||
|
alter this behaviors by setting this flag. When set,
|
|||
|
if no non-literal characters have been entered in the
|
|||
|
string, od_edit_str() will return an empty string.
|
|||
|
|
|||
|
EDIT_FLAG_SHOW_SIZE - Normally, od_edit() adds an extra blank to
|
|||
|
the end of the input field, to give the cursor a space
|
|||
|
to move into when the field is full. However, you may
|
|||
|
prefer to have the input field be shown as exactly the
|
|||
|
maximum size of input that is permitted. Setting
|
|||
|
EDIT_FLAG_SHOW_SIZE does just this. In this case, the
|
|||
|
cursor will be positioned immediately past the end of
|
|||
|
the input field when the maximum number of characters
|
|||
|
have been entered.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_input_str(), od_get_char(), od_clear_keybuffer()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below are several examples of typical uses of the od_edit_str()
|
|||
|
function. For the sake of simplicity, all of these examples
|
|||
|
perform their input beginning at the top, left hand corner of
|
|||
|
the screen, and store the user's input in the string variable
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 76
|
|||
|
|
|||
|
named "string". For an example of the user of the od_edit_str()
|
|||
|
function in a dialog-box / form entry application, see the
|
|||
|
example accompanying the od_draw_box() function.
|
|||
|
|
|||
|
To input a name with a maximum of 25 characters, having the
|
|||
|
first letter of each word automatically capitalized:
|
|||
|
|
|||
|
od_edit_str(string, "MMMMMMMMMMMMMMMMMMMMMMMMM", 1, 1,
|
|||
|
0x03, 0x21, 176, EDIT_FLAG_NORMAL);
|
|||
|
|
|||
|
To input a North American style phone number, requiring that all
|
|||
|
digits be filled, and running in "strict input" mode:
|
|||
|
|
|||
|
od_edit_str(string, "###'-'###'-'####",
|
|||
|
1, 1, 0x03, 0x21, 176,
|
|||
|
EDIT_FLAG_FILL_STRING|
|
|||
|
EDIT_FLAG_STRICT_INPUT);
|
|||
|
|
|||
|
To allow the user to edit a previously entered 20 character
|
|||
|
string, with auto-delete mode on. Any characters will be
|
|||
|
permitted in the string. Remember that when the
|
|||
|
EDIT_FLAG_EDIT_STRING flag is set, the string must be
|
|||
|
initialized prior to calling the od_edit_str() function.
|
|||
|
|
|||
|
od_edit_str(string, "????????????????????",
|
|||
|
1, 1, 0x03, 0x21, 176,
|
|||
|
EDIT_FLAG_EDIT_STRING|
|
|||
|
EDIT_FLAG_AUTO_DELETE);
|
|||
|
|
|||
|
|
|||
|
To input a password of up to 16 characters from the user. Here,
|
|||
|
the password will only be permitted to contain upper case
|
|||
|
characters, and the od_edit_str() password mode is used, with a
|
|||
|
small block displayed in place of any characters typed:
|
|||
|
|
|||
|
od_edit_str(string, "UUUUUUUUUUUUUUUU",
|
|||
|
1, 1, 0x03, 0x21, 254,
|
|||
|
EDIT_FLAG_PASSWORD_MODE);
|
|||
|
|
|||
|
To input a two-digit number from the user, requiring that both
|
|||
|
digits be filled, and automatically accepting the input after
|
|||
|
the two digits have been entered (not requiring the user to
|
|||
|
press [ENTER]):
|
|||
|
|
|||
|
od_edit_str(string, "##", 1, 1, 0x03, 0x21, 176,
|
|||
|
EDIT_FLAG_FILL_STRING|
|
|||
|
EDIT_FLAG_AUTO_ENTER);
|
|||
|
|
|||
|
To input a filename to download, as a field in a dialog box.
|
|||
|
Here, the filename will be permitted to contain valid filename
|
|||
|
characters, and the od_input_str() function will operate in
|
|||
|
field mode, with the cancel [ESCape] key enabled. Also, string
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 77
|
|||
|
|
|||
|
edit mode will be enabled, allowing the user to edit a
|
|||
|
previously entered line, and the EDIT_FLAG_KEEP_BLANK flag will
|
|||
|
be set, causing the field background to remain displayed after
|
|||
|
the user exits. This time, however, auto-delete mode will not be
|
|||
|
used. Note that this combination of parameters expects that the
|
|||
|
field and it's contents will have already been displayed, prior
|
|||
|
to calling the od_edit_str() function.
|
|||
|
|
|||
|
od_edit_str(string, "WWWWWWWWWWWW",
|
|||
|
1, 1, 0x03, 0x21, 176,
|
|||
|
EDIT_FLAG_EDIT_STRING|
|
|||
|
EDIT_FLAG_FIELD_MODE|
|
|||
|
EDIT_FLAG_ALLOW_CANCEL|
|
|||
|
EDIT_FLAG_KEEP_BLANK);
|
|||
|
|
|||
|
To input a string without the field background and line
|
|||
|
redrawing before and after input takes place:
|
|||
|
|
|||
|
od_edit_str(string, "******************************",
|
|||
|
1, 1, 0x07, 0x07, ' ',
|
|||
|
EDIT_FLAG_NO_REDRAW);
|
|||
|
|
|||
|
To input a date, using PermaLiteral mode. Here, the month is
|
|||
|
entered by a three digit short form ("JAN", "FEB", etc.), and
|
|||
|
the literal characters such as the '-' and the "19" are a
|
|||
|
permanent part of the input field:
|
|||
|
|
|||
|
od_edit_str(string,"UUU'-'##'-19'##",
|
|||
|
1, 1, 0x03, 0x21, 176,
|
|||
|
EDIT_FLAG_PERMALITERAL|
|
|||
|
EDIT_FLAG_FILL_STRING);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 78
|
|||
|
|
|||
|
OD_EXIT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE The OpenDoors program termination function
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_exit(INT nErrorLevel, BOOL bTermCall);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION You MUST USE THIS FUNCTION when you want your program to exit.
|
|||
|
This function will close the serial port, re-write changed
|
|||
|
information to the door information (drop), call your end-of-
|
|||
|
program function (if any), and then exit with the errorlevel
|
|||
|
specified in the first parameter.
|
|||
|
|
|||
|
Also, if the second parameter, bTermCall, is set to TRUE,
|
|||
|
od_exit() will also log the user off (for options such as
|
|||
|
logging off within the door - as shown in the example below).
|
|||
|
This is accomplished by lowering the DTR line to the modem,
|
|||
|
causing the modem to hangup. When control is returned to the
|
|||
|
BBS, it will then detect that the user is no longer online, and
|
|||
|
will carry out its own logoff processing.
|
|||
|
|
|||
|
If you wish for your program to always perform any activities
|
|||
|
prior to exiting, such as updating or closing data files, you
|
|||
|
should set a function to be executed from within the od_exit()
|
|||
|
function. This is accomplished by using the od_control.
|
|||
|
od_before_exit variable, as described in the section on the
|
|||
|
OpenDoors control structure in chapter 5. Use of this variable
|
|||
|
will allow your program to always carry out these activates,
|
|||
|
even if OpenDoors decides to call the od_exit() function itself,
|
|||
|
such as when a user hangs up on the door.
|
|||
|
|
|||
|
Note that in special cases, you may use the
|
|||
|
od_control.od_disable variable to prevent the od_exit() function
|
|||
|
from re-writing the door information file. Also, you may use the
|
|||
|
od_control.od_noexit variable to shutdown door operations
|
|||
|
without actually exiting your program. Both of these variables
|
|||
|
are described in chapter 5.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_init()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE The example below demonstrates a function which a door could
|
|||
|
execute when the user chooses to exit the door. This function
|
|||
|
will ask the user whether they wish to exit the door and return
|
|||
|
to the BBS, simply logoff of the BBS, or continue using the
|
|||
|
door. The example function will then call od_exit() if the user
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 79
|
|||
|
|
|||
|
wishes to exit the door, or return control to the function which
|
|||
|
called it, if the user does not wish to exit:
|
|||
|
|
|||
|
void goodbye(void)
|
|||
|
{
|
|||
|
char pressed;
|
|||
|
/* Display choices to user */
|
|||
|
od_disp_str("You have chosen to exit this door.\n\r");
|
|||
|
od_disp_str("Do you wish to:\n\r");
|
|||
|
od_disp_str(" [R]eturn to the BBS\n\r");
|
|||
|
od_disp_str(" [L]ogoff of the BBS\n\r");
|
|||
|
od_disp_str(" [C]ontinue using the door\n\r");
|
|||
|
|
|||
|
for(;;) /* loop until user makes valid choice */
|
|||
|
{
|
|||
|
pressed=od_get_key(TRUE); /* Get key from user */
|
|||
|
|
|||
|
/* If user selects R, exit without hanging up */
|
|||
|
if(pressed=='R' || pressed=='r') od_exit(40,FALSE);
|
|||
|
|
|||
|
/* If user selects L, hangup and then exit */
|
|||
|
if(pressed=='L' || pressed=='l') od_exit(41,TRUE);
|
|||
|
|
|||
|
/* If user selects C, return and allow door to continue */
|
|||
|
if(pressed=='C' || pressed=='c') return;
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 80
|
|||
|
|
|||
|
OD_GET_ANSWER()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to allow the user to respond to a prompt using only
|
|||
|
certain keys.
|
|||
|
|
|||
|
|
|||
|
FORMAT char od_get_answer(char *pszOptions);
|
|||
|
|
|||
|
|
|||
|
RETURNS Character that user entered
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function can be used to get a response from the user, when
|
|||
|
only particular responses should be accepted. The parameter to
|
|||
|
the od_get_answer() function is simply a string listing the
|
|||
|
valid responses. The function will wait until the user selects
|
|||
|
one of the valid responses, and then return that response. The
|
|||
|
function is case insensitive, and will return the character in
|
|||
|
the same case that was supplied to it in the string.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_get_key(), od_hotkey_menu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLES od_get_answer("YN");
|
|||
|
- If the user presses 'y', will return 'Y'.
|
|||
|
|
|||
|
od_get_answer("yn");
|
|||
|
- If the user presses 'y', will return 'y'.
|
|||
|
|
|||
|
od_get_answer("ABC 123\n\rZ");
|
|||
|
- Valid responses will be: [A], [B], [C], [SPACE],
|
|||
|
[1], [2], [3], [ENTER], [Z]
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 81
|
|||
|
|
|||
|
OD_GET_INPUT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE This function allows a single input event (e.g. keystroke) to be
|
|||
|
retrieved, optionally translating extended key sequences such as
|
|||
|
arrow keys and the insert key.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_get_input(tODInputEvent *pInputEvent,
|
|||
|
tODMilliSec TimeToWait, WORD wFlags);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success, FALSE if no input event was retrieved.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION Like od_get_key(), od_get_input() can be used to retrieve a
|
|||
|
single key of input from the user. However, od_get_input() has
|
|||
|
been designed to be easily extended in future versions of
|
|||
|
OpenDoors. The information retrieved by this new function is
|
|||
|
placed in a structure, which contains information on whether the
|
|||
|
input event was generated by the remote user or the local
|
|||
|
console, and what type of input event it was. This function also
|
|||
|
has built-in the ability to recognize and translate the multiple-
|
|||
|
character sequences that are generated when the user presses
|
|||
|
extended keys such as arrow keys, insert, delete, etc.
|
|||
|
|
|||
|
The first parameter points to a tODInputEvent structure, which is
|
|||
|
defined as follows:
|
|||
|
|
|||
|
typedef struct
|
|||
|
{
|
|||
|
tODInputEventType EventType;
|
|||
|
BOOL bFromRemote;
|
|||
|
char chKeyPress;
|
|||
|
} tODInputEvent;
|
|||
|
|
|||
|
When od_get_input() successfully retrieves an input event, this
|
|||
|
structure is filled with information about the input. The
|
|||
|
EventType member can be either EVENT_CHARACTER (indicating a
|
|||
|
single character keystroke) or EVENT_EXTENDED_KEY (indicating an
|
|||
|
extended key, such as an arrow key). In the case of
|
|||
|
EVENT_CHARACTER, chKeyPress is set to the character that was
|
|||
|
received. In the case of EVENT_EXTENDED_KEY, chKeyPress is set to
|
|||
|
one of the following values:
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 82
|
|||
|
|
|||
|
+------------------+---------------+-------------------------+
|
|||
|
| chKeyPress Value | Meaning | Control Key Alternative |
|
|||
|
+------------------+---------------+-------------------------+
|
|||
|
| OD_KEY_F1 | [F1] | None |
|
|||
|
| OD_KEY_F2 | [F2] | None |
|
|||
|
| OD_KEY_F3 | [F3] | None |
|
|||
|
| OD_KEY_F4 | [F4] | None |
|
|||
|
| OD_KEY_F5 | [F5] | None |
|
|||
|
| OD_KEY_F6 | [F6] | None |
|
|||
|
| OD_KEY_F7 | [F7] | None |
|
|||
|
| OD_KEY_F8 | [F8] | None |
|
|||
|
| OD_KEY_F9 | [F9] | None |
|
|||
|
| OD_KEY_F10 | [F10] | None |
|
|||
|
| OD_KEY_UP | [UP ARROW] | [CTRL]-[E] |
|
|||
|
| OD_KEY_DOWN | [DOWN ARROW] | [CTRL]-[X] |
|
|||
|
| OD_KEY_LEFT | [LEFT ARROW] | [CTRL]-[S] |
|
|||
|
| OD_KEY_RIGHT | [RIGHT ARROW] | [CTRL]-[D] |
|
|||
|
| OD_KEY_INSERT | [INSERT] | [CTRL]-[V] |
|
|||
|
| OD_KEY_DELETE | [DELETE] | [CTRL]-[G] |
|
|||
|
| OD_KEY_HOME | [HOME] | None |
|
|||
|
| OD_KEY_END | [END] | None |
|
|||
|
| OD_KEY_PGUP | [PAGE UP] | None |
|
|||
|
| OD_KEY_PGDN | [PAGE DOWN] | None |
|
|||
|
| OD_KEY_SHIFTTAB | [SHIFT]-[TAB] | None |
|
|||
|
+------------------+---------------+-------------------------+
|
|||
|
|
|||
|
The bFromRemote member of the tODInputEvent structure will be set
|
|||
|
to TRUE if the input event originated from the remote system, or
|
|||
|
FALSE if the event originated from the local system.
|
|||
|
|
|||
|
The second parameter, TimeToWait specifies how long the function
|
|||
|
should wait for input before returning, in milliseconds. A value
|
|||
|
of 0 causes the function to return immediately if no input is
|
|||
|
waiting in OpenDoor's internal input buffer. The is equivalent to
|
|||
|
a value of FALSE being passed to the od_get_key() function. A
|
|||
|
value of OD_NO_TIMEOUT causes this function to wait and only
|
|||
|
return after the next input event has been received. This is
|
|||
|
equivalent to a value of TRUE being passed to the od_get_key()
|
|||
|
function. An other value specifies the maximum number of
|
|||
|
milliseconds that od_get_input() should wait for input. If input
|
|||
|
is received before this time elapses, od_get_key() will return
|
|||
|
immediately with a value of TRUE, and the tODInputEvent structure
|
|||
|
will be fill accordingly. If no input is received before this
|
|||
|
time elapses, od_get_key() will return FALSE. The number of
|
|||
|
milliseconds to wait is rounded to the nearest 55 milliseconds in
|
|||
|
the DOS version of OpenDoors.
|
|||
|
|
|||
|
The third parameter allows you to specify flags to further
|
|||
|
control the behavior of od_get_input(). Normally, this parameter
|
|||
|
will be set to GETIN_NORMAL. However, you can disable all
|
|||
|
translation of extended keystrokes by setting this value to
|
|||
|
GETIN_RAW. In this mode, od_get_input() works just like
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 83
|
|||
|
|
|||
|
od_get_key(), returning every individual character received from
|
|||
|
the remote system.
|
|||
|
|
|||
|
Since extended keys are not directly supported by all terminal
|
|||
|
programs, od_get_input() provides alternatives for some of the
|
|||
|
extended keys, in the form of control-key combinations. The
|
|||
|
control key combinations recognized by od_get_input() are listed
|
|||
|
in the table above. However, these control key alternatives can
|
|||
|
be ignored by setting the GETIN_RAWCTRL flag.
|
|||
|
|
|||
|
The od_get_input() function is used internally by
|
|||
|
od_popup_menu(), od_edit_str() and od_multiline_edit().
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_get_key(), od_clear_keybuffer()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE The following example shows the structure of how od_get_input()
|
|||
|
might be used in your program:
|
|||
|
|
|||
|
tODInputEvent InputEvent;
|
|||
|
od_get_input(&InputEvent, OD_NO_TIMEOUT, GETIN_NORMAL);
|
|||
|
if(InputEvent.EventType == EVENT_EXTENDED_KEY)
|
|||
|
{
|
|||
|
switch(InputEvent.chKeyPress)
|
|||
|
{
|
|||
|
case OD_KEY_UP:
|
|||
|
/* The up arrow key has been pressed. */
|
|||
|
break;
|
|||
|
case OD_KEY_DOWN:
|
|||
|
/* The down arrow key has been pressed. */
|
|||
|
break;
|
|||
|
}
|
|||
|
}
|
|||
|
else if(InputEvent.EventType == EVENT_CHARACTER)
|
|||
|
{
|
|||
|
/* A single character key has been pressed, and is */
|
|||
|
/* stored in InputEvent.chKeyPress. */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 84
|
|||
|
|
|||
|
OD_GET_KEY()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to input a key from the user
|
|||
|
|
|||
|
|
|||
|
FORMAT char od_get_key(BOOL bWait);
|
|||
|
|
|||
|
|
|||
|
RETURNS The next key waiting from the keyboard, or 0 if none.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function retrieves the next key waiting in the OpenDoors
|
|||
|
keyboard buffer (see the description of the od_clear_keybuffer()
|
|||
|
function, on page 53, for more information on the OpenDoors
|
|||
|
keyboard buffer). The od_get_key() function allows your door to
|
|||
|
retrieve both those keystrokes pressed by the user, and the
|
|||
|
keystrokes pressed on the sysop keyboard (other than the sysop
|
|||
|
function keys), in the sequence they were pressed. Since input
|
|||
|
is accepted from both sources, it is possible for the sysop, as
|
|||
|
well as the remote user, to make selections and control the
|
|||
|
door.
|
|||
|
|
|||
|
Door input with OpenDoors can be accomplished with this
|
|||
|
function, with the od_input_str() function or with the
|
|||
|
od_edit_str() function. The od_input_str() and od_edit_str()
|
|||
|
functions is used to input an entire sequence of characters from
|
|||
|
the user (a string), and requires the user to press the [Enter]
|
|||
|
key when they are finished typing their input. On the other
|
|||
|
hand, the od_get_key() function is used to input a single
|
|||
|
keystroke (one character) from the user, and allows the user to
|
|||
|
make choices without having to press the enter key.
|
|||
|
|
|||
|
The od_get_key() function accepts a single parameter, which
|
|||
|
determines whether or not it should wait for the user to press a
|
|||
|
key, if they have not already done so. If you pass a FALSE value
|
|||
|
to od_get_key(), then the function will not wait for a key to be
|
|||
|
pressed at the keyboard, but instead return a 0 if there are no
|
|||
|
keys waiting in the buffer. If you pass a TRUE value to
|
|||
|
od_get_key(), then this function will instead wait for a key to
|
|||
|
be pressed. Also, while waiting for the user to press a key, the
|
|||
|
od_get_key() function will give up the processor to other
|
|||
|
waiting programs, if you door is running under DesqView.
|
|||
|
|
|||
|
If you are waiting for the user to make a choice from a menu or
|
|||
|
list of options, you will most likely pass a TRUE to the
|
|||
|
od_get_key() function, indicating that you wish for it to wait
|
|||
|
until a key is pressed. However, if you wish to continue other
|
|||
|
processing if no key is yet available from the keyboard, you
|
|||
|
should pass a FALSE to the od_get_key() function. For example,
|
|||
|
if you are displaying a screen of text, and wish to allow the
|
|||
|
user to pause or abort the display, you would simply call the
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 85
|
|||
|
|
|||
|
od_get_key() function every few moments, passing it a value of
|
|||
|
FALSE. You would then be able to check if any control keys have
|
|||
|
been pressed, and if not, continue displaying text.
|
|||
|
|
|||
|
The od_get_key() function returns the ASCII value representing
|
|||
|
the keystroke that was made. If you are waiting for the user to
|
|||
|
make a particular choice, perhaps from a menu, you will most
|
|||
|
likely store the value returned by od_get_key() in a variable of
|
|||
|
type char. For example:
|
|||
|
|
|||
|
char key;
|
|||
|
...
|
|||
|
key=od_get_key(TRUE);
|
|||
|
|
|||
|
You would then be able to determine which key the user pressed
|
|||
|
by testing the value of key, either by comparing it's numerical
|
|||
|
ASCII value, or by comparing it to a character constant. If you
|
|||
|
are testing for a non-character key, such as [ESCape], [Tab] or
|
|||
|
[Return], you may wish to use the ASCII value of that key. For
|
|||
|
example, if you wished to take some action in the case that the
|
|||
|
user presses the [Enter]/[Return] key, who's ASCII value is 13,
|
|||
|
you could do:
|
|||
|
|
|||
|
key=od_get_key(TRUE); /* Get keypress from user */
|
|||
|
if(key==13) /* If key was [Enter]/[Return] */
|
|||
|
{
|
|||
|
... /* Whatever you want to do */
|
|||
|
}
|
|||
|
|
|||
|
If you wish, instead, to respond to the user pressing a
|
|||
|
character key (perhaps as a choice from a menu), you can do so
|
|||
|
by using character constants, such as 'c', '6', or 'F'. Also,
|
|||
|
when testing for an alphabetical character, you will probably
|
|||
|
want to check for the user pressing either the upper or lower-
|
|||
|
case version of the letter. For example, if you wished to have
|
|||
|
the user press the [Y] key to continue, you could test for
|
|||
|
either an upper or lower-case Y as follows:
|
|||
|
|
|||
|
key=od_get_key(TRUE); /* Get keypress from user */
|
|||
|
if(key=='y' || key=='Y') /* If key was [y]/[Y] */
|
|||
|
{
|
|||
|
... /* Whatever you want to do */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
The charts on the following page lists the decimal value and corresponding
|
|||
|
keystroke(s) of each of the ASCII values from 0 to 127.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 86
|
|||
|
|
|||
|
ASCII KEYSTROKE | ASCII KEYSTROKE
|
|||
|
----- ------------------------------ | ----- ----------------------
|
|||
|
0 [Control]-[@] | 15 [Control]-[O]
|
|||
|
1 [Control]-[A] | 16 [Control]-[P]
|
|||
|
2 [Control]-[B] | 17 [Control]-[Q]
|
|||
|
3 [Control]-[C] | 18 [Control]-[R]
|
|||
|
4 [Control]-[D] | 19 [Control]-[S]
|
|||
|
5 [Control]-[E] | 20 [Control]-[T]
|
|||
|
6 [Control]-[F] | 21 [Control]-[U]
|
|||
|
7 [Control]-[G] | 22 [Control]-[V]
|
|||
|
8 [Control]-[H]/[Backspace] | 23 [Control]-[W]
|
|||
|
9 [Control]-[I]/[Tab] | 24 [Control]-[X]
|
|||
|
10 [Control]-[J] | 25 [Control]-[Y]
|
|||
|
11 [Control]-[K] | 26 [Control]-[Z]
|
|||
|
12 [Control]-[L] | 27 [ESCape]
|
|||
|
13 [Control]-[M]/[Enter]/[Return] | 32 [SpaceBar]
|
|||
|
14 [Control]-[N] |
|
|||
|
|
|||
|
|
|||
|
|
|||
|
ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE
|
|||
|
----- --------- | ----- --------- | ----- --------- | ----- ---------
|
|||
|
33 '!' | 57 '9' | 80 'P' | 104 'h'
|
|||
|
34 '"' | 58 ':' | 81 'Q' | 105 'i'
|
|||
|
35 '#' | 59 ';' | 82 'R' | 106 'j'
|
|||
|
36 '$' | 60 '<' | 83 'S' | 107 'k'
|
|||
|
37 '%' | 61 '=' | 84 'T' | 108 'l'
|
|||
|
38 '&' | 62 '>' | 85 'U' | 109 'm'
|
|||
|
39 '\'' (') | 63 '?' | 86 'V' | 110 'n'
|
|||
|
40 '(' | 64 '@' | 87 'W' | 111 'o'
|
|||
|
41 ')' | 65 'A' | 88 'X' | 112 'p'
|
|||
|
42 '*' | 66 'B' | 89 'Y' | 113 'q'
|
|||
|
43 '+' | 67 'C' | 90 'Z' | 114 'r'
|
|||
|
44 ',' | 68 'D' | 91 '[' | 115 's'
|
|||
|
45 '-' | 69 'E' | 92 '\\' (\) | 116 't'
|
|||
|
46 '.' | 70 'F' | 93 ']' | 117 'u'
|
|||
|
47 '/' | 71 'G' | 94 '^' | 118 'v'
|
|||
|
48 '0' | 72 'H' | 95 '_' | 119 'w'
|
|||
|
49 '1' | 73 'I' | 96 '`' | 120 'x'
|
|||
|
50 '2' | 74 'J' | 98 'b' | 121 'y'
|
|||
|
51 '3' | 75 'K' | 99 'c' | 122 'z'
|
|||
|
52 '4' | 76 'L' | 100 'd' | 123 '{'
|
|||
|
53 '5' | 77 'M' | 101 'e' | 124 '|'
|
|||
|
54 '6' | 78 'N' | 102 'f' | 125 '}'
|
|||
|
55 '7' | 79 'O' | 103 'g' | 126 '~'
|
|||
|
56 '8' | | | 127 [DELete]
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 87
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_get_input(), od_input_str(), od_edit_str(),
|
|||
|
od_clear_keybuffer()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For examples of the use of the od_get_key() function, see the
|
|||
|
examples in the description portion, above, and the examples for
|
|||
|
the od_exit() and od_clear_keybuffer() functions. For further
|
|||
|
examples of this function, see the example program EX_VOTE.C,
|
|||
|
described in the section beginning on page 38.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 88
|
|||
|
|
|||
|
OD_GETTEXT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Stores a rectangular region of the screen in an array, to later
|
|||
|
be redrawn using od_puttext(). Requires ANSI, AVATAR or RIP
|
|||
|
modes.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_gettext(INT nLeft, INT nTop, INT nRight, INT nBottom,
|
|||
|
void *pBlock);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function stores the contents (both text and color
|
|||
|
information) of the rectangular portion of the screen denoted by
|
|||
|
the variables nLeft, nTop, nRight and nBottom into the buffer
|
|||
|
pointed to by pBlock. The saved portion of the screen may then
|
|||
|
be restored using od_puttext(). The buffer must be large enough
|
|||
|
to store two bytes for every character in the specified
|
|||
|
rectangle. In other words, the required size of the buffer, in
|
|||
|
bytes, is:
|
|||
|
|
|||
|
length * width * 2
|
|||
|
|
|||
|
The parameters nLeft and nRight are column numbers from 1 to 80,
|
|||
|
and the parameters nTop and nBottom are row numbers between 1
|
|||
|
and 23.
|
|||
|
|
|||
|
This function has no effect on the current text color or cursor
|
|||
|
position. ANSI, AVATAR or RIP mode is required for this
|
|||
|
function. If you wish to save and restore the entire screen, you
|
|||
|
may use the od_save_screen() and od_restore_screen() functions,
|
|||
|
which can be used in all display modes.
|
|||
|
|
|||
|
If this function fails for any reason, a value of FALSE is
|
|||
|
returned, and the od_control.od_error variable is set to
|
|||
|
indicate the reason for the failure. For more information on the
|
|||
|
od_control.od_error variable, see page 185.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_puttext(), od_save_screen(), od_restore_screen(),
|
|||
|
od_scroll(), od_window_create(), od_window_remove()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 89
|
|||
|
|
|||
|
OD_HOTKEY_MENU()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to display a menu file with hotkeys
|
|||
|
|
|||
|
|
|||
|
FORMAT char od_hotkey_menu(char *pszFileName, char *pszHotKeys, BOOL
|
|||
|
bWait);
|
|||
|
|
|||
|
|
|||
|
RETURNS Key pressed in response to menu, or '\0' if none.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function can be used to display a menu from an ASCII, ANSI,
|
|||
|
AVATAR or RIP file, allowing the user to select an option at any
|
|||
|
time while the menu is being displayed. The od_hotkey_menu()
|
|||
|
function is quite similar to the od_send_file() function, and
|
|||
|
you should probably familiarize yourself with that function if
|
|||
|
you are going to use od_hotkey_menu(). Like od_send_file(),
|
|||
|
od_hotkey_menu() will display the file specified by pszFileName,
|
|||
|
using the appropriate terminal emulation. If no extension is
|
|||
|
provided for the filename, OpenDoors will automatically search
|
|||
|
for matching files ending in .ASC, .ANS and .AVT extensions.
|
|||
|
OpenDoors will the select the appropriate file to display, based
|
|||
|
on the available files and available terminal emulation.
|
|||
|
|
|||
|
The second parameter, pszHotKeys, is a string specifying the
|
|||
|
valid responses to the menu, in the same format as the string
|
|||
|
passed to the od_get_answer() function. If any of the characters
|
|||
|
listed in this string are pressed, either uppercase or lowercase
|
|||
|
versions, OpenDoors will immediately stop displaying the menu,
|
|||
|
and return with the value of the key pressed. The case (upper or
|
|||
|
lower) returned will always be identical to the case used in the
|
|||
|
hotkeys string. You can include the [ENTER] key as a valid hot
|
|||
|
key by including the \n character in the hotkey string.
|
|||
|
|
|||
|
The third parameter passed to od_hotkey_menu(), bWait, specifies
|
|||
|
whether OpenDoors should wait after displaying the menu for the
|
|||
|
user to make a valid selection from the menu (TRUE), or if it
|
|||
|
should exit immediately (FALSE). Normally, you will want to use
|
|||
|
the TRUE value when calling this function. This will allow you
|
|||
|
to use a single function call that will display the menu and
|
|||
|
always return the user's selection. If you wish to gain control
|
|||
|
as soon as OpenDoors has displayed the menu, you may specify
|
|||
|
FALSE for this parameter. In this case, if the user does not
|
|||
|
press any of the valid hot keys while the menu is being sent,
|
|||
|
the function will return the character '\0'.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_send_file(), od_get_answer()
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 90
|
|||
|
|
|||
|
EXAMPLE As an example of the use of the od_hotkey_menu() function,
|
|||
|
consider the following code fragment:
|
|||
|
|
|||
|
|
|||
|
for(;;) /* Main program loop */
|
|||
|
{ /* Display menu and get user's choice */
|
|||
|
char choice=od_hotkey_menu("MAINMENU","123Q",TRUE");
|
|||
|
|
|||
|
switch(choice) /* Perform the appropriate action */
|
|||
|
{
|
|||
|
case '1':
|
|||
|
od_printf("You selected one.\n\r");
|
|||
|
break;
|
|||
|
|
|||
|
case '2':
|
|||
|
od_printf("You selected two.\n\r");
|
|||
|
break;
|
|||
|
|
|||
|
case '3':
|
|||
|
od_printf("You selected three.\n\r");
|
|||
|
break;
|
|||
|
|
|||
|
case 'Q':
|
|||
|
od_exit(FALSE,10);
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
This is an example of the main menu loop of a simple door that
|
|||
|
uses the od_hotkey_menu() function. The program will continue
|
|||
|
executing the for(;;) loop until the user chooses to exit the
|
|||
|
door. On each iteration of the loop, the od_hotkey_menu()
|
|||
|
function is called, to display the door's menu from the file
|
|||
|
MAINMENU.A??. The appropriate .ASC/.ANS/.AVT file will be chosen
|
|||
|
and displayed as the menu. The possible choices that may be made
|
|||
|
from the menu are specified by the string "123Q". Thus, whenever
|
|||
|
the user presses one of the keys [1], [2], [3] or [Q], the
|
|||
|
od_hotkey_menu() function will return immediately with the value
|
|||
|
of the key pressed. If the menu is still being displayed at the
|
|||
|
time when the key was pressed, menu display will cease at that
|
|||
|
moment. The program then executes a case statement, to respond
|
|||
|
to the user's key appropriately. If the user presses [1], [2] or
|
|||
|
[3] this door will output a simple message to the screen. If the
|
|||
|
user presses the [Q] key, the door will pass control back to the
|
|||
|
BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 91
|
|||
|
|
|||
|
OD_INIT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE To initialize OpenDoors activities
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_init(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function initializes OpenDoors. This function must be
|
|||
|
called manually if you wish to access data about the user, etc.,
|
|||
|
before you call any other OpenDoors functions. However, if you
|
|||
|
do not explicitly call the od_init() function, it will be called
|
|||
|
automatically on the first call to most other OpenDoors
|
|||
|
functions. The only functions that should be called before
|
|||
|
od_init() are od_add_personality() and od_parse_cmd_line(). The
|
|||
|
od_init() function reads information from the door information
|
|||
|
file, initializes communications with the modem, displays the
|
|||
|
status line, and sets up OpenDoors' internal data structures.
|
|||
|
For more information on what data is and is not available before
|
|||
|
od_init() has been called, please refer to the chapter on the
|
|||
|
OpenDoors control structure, which begins on page 148.
|
|||
|
|
|||
|
The od_init() function will read the door information file which
|
|||
|
is located in the directory specified by the variable
|
|||
|
od_control.info_path. If this variable has not been set prior to
|
|||
|
calling the od_init() function, OpenDoors will expect to find
|
|||
|
the door information file in the current directory. Thus, if you
|
|||
|
wish your door to be able to be run in a directory other than
|
|||
|
the BBS system directory, it would be a good idea to allow the
|
|||
|
sysop using your door to specify the location of the door
|
|||
|
information file. For an example of setting the
|
|||
|
od_control.info_path variable, please see the example program
|
|||
|
located on page 150.
|
|||
|
|
|||
|
Also note that you can prevent the od_init() function from
|
|||
|
carrying out some of it's normal activities, such as attempting
|
|||
|
to read a door information file, by the use of the
|
|||
|
od_control.od_disable variable, as described in the section on
|
|||
|
the OpenDoors control structure, which begins on page 148.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_exit()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE At times, you may wish to write a door program which will
|
|||
|
require a maintenance utility to be run on a regular basis. For
|
|||
|
example, a game door may have to have its system files updated
|
|||
|
on a daily basis, by having a utility program run in a system
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 92
|
|||
|
|
|||
|
event each day at midnight. One way of accomplishing this would
|
|||
|
be to have your door package include two .EXE files, one being
|
|||
|
the actual door program, and the other being a utility program.
|
|||
|
However, another option would be to have both the door and
|
|||
|
maintenance functions to be accessible from a single .EXE file,
|
|||
|
in order to simplify use of the door for the sysop. In this
|
|||
|
case, you would want to test the command line to determine
|
|||
|
whether your program should run in door mode or maintenance
|
|||
|
mode. You would then only execute the od_init() function, along
|
|||
|
with the rest of your door code, if you program were running in
|
|||
|
"door mode".
|
|||
|
|
|||
|
The program below demonstrates one method of doing just this. In
|
|||
|
this case, the program would include two functions, door(),
|
|||
|
which would carry out all of the door-related activities, and
|
|||
|
maint(), which would carry out all of the maintenance-related
|
|||
|
activities. In this simple example, if the command line includes
|
|||
|
a "-M" or "/M", the program will run in maintenance mode,
|
|||
|
otherwise it will run in door mode. Also, if it is running in
|
|||
|
door mode, the program will take the first command-line
|
|||
|
parameter, if any, as a path to the location of the door
|
|||
|
information file.
|
|||
|
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
void door(void);
|
|||
|
void maint(void);
|
|||
|
|
|||
|
|
|||
|
int main(int argc, char *argv[])
|
|||
|
{
|
|||
|
int counter;
|
|||
|
|
|||
|
/* Check any command line parameters for /M or -M */
|
|||
|
for(counter=1;counter<argc;++counter)
|
|||
|
{
|
|||
|
if((argv[counter])[1]=='m' || (argv[counter])[1]=='M')
|
|||
|
{
|
|||
|
maint(); /* Then carry out maintenance */
|
|||
|
exit(20); /* And exit */
|
|||
|
}
|
|||
|
}
|
|||
|
/* If there was no -M or /M, then run in door mode */
|
|||
|
|
|||
|
/* If there are any command-line parameters take the first */
|
|||
|
/* as the path to the door information file */
|
|||
|
if(argc>1) strncpy(od_control.info_path,argv[1],59);
|
|||
|
|
|||
|
od_init(); /* call the od_init() function */
|
|||
|
door(); /* Run the door portion of the program */
|
|||
|
od_exit(30,FALSE); /* Shutdown the door */
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 93
|
|||
|
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
void maint(void)
|
|||
|
{
|
|||
|
... /* Carry out maintenance activities here */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
void door(void)
|
|||
|
{
|
|||
|
... /* Carry out door activities here */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 94
|
|||
|
|
|||
|
OD_INPUT_STR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Inputs a string from the user
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_input_str(char *pszInput, INT nMaxLength,
|
|||
|
unsigned char chMin, unsigned char chMax);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION To perform string input within OpenDoors, one of two functions
|
|||
|
can be used, od_input_str() and od_edit_str(). The first
|
|||
|
function, od_input_str(), allows simple line input and editing,
|
|||
|
and can be used in ASCII, ANSI, AVATAR and RIP modes. The second
|
|||
|
function, od_edit_str(), allows many formatted input options,
|
|||
|
advanced line editing, and other features, but requires the use
|
|||
|
of ANSI, AVATAR or RIP graphics modes.
|
|||
|
|
|||
|
The od_input_str() function allows you to input a string from
|
|||
|
the user. The string will be permitted to have up to the number
|
|||
|
of characters specified by the max_len parameter, and all
|
|||
|
characters must be between the values of the min_char and
|
|||
|
max_char parameters. This function will wait until the user
|
|||
|
presses the [Enter] key to finish inputting the string.
|
|||
|
|
|||
|
The first parameter passed to this function should be a pointer
|
|||
|
to the string where the user's input should be stored. So, if
|
|||
|
you wanted to store a string of up to 30 characters inputted by
|
|||
|
the user, you might define this string as follows:
|
|||
|
|
|||
|
char input_string[31];
|
|||
|
|
|||
|
Notice here than the string must be long enough to hold the
|
|||
|
thirty characters which can be entered by the user, along with
|
|||
|
the additional "null" character which is used to indicate the
|
|||
|
end of a string in C. Hence, the length of the string should
|
|||
|
always be at least one greater than the total number of
|
|||
|
characters the user is permitted to enter, passed in the
|
|||
|
nMaxLength parameter.
|
|||
|
|
|||
|
The second parameter passed to the od_input_str() function
|
|||
|
should be an integer value indicating the maximum number of
|
|||
|
characters which can be input by the user. For example, if this
|
|||
|
parameter had a value of 10, the user would be able to enter a
|
|||
|
string containing any number of characters up to and including
|
|||
|
10 characters. If this parameter had a value of 1, the user
|
|||
|
would only be able to enter a single character. However, the
|
|||
|
user would be able to backspace, change the character, and press
|
|||
|
[Enter] when they were satisfied with their entry. Note that
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 95
|
|||
|
|
|||
|
even if you only ask the od_input_str() function to input a
|
|||
|
single character, it will still expect a STRING to be passed to
|
|||
|
it, and will return a string with either zero or one character,
|
|||
|
followed by a null (string terminator) character.
|
|||
|
|
|||
|
The third and fourth parameters passed to this function allow
|
|||
|
you to control what characters the user will be permitted to
|
|||
|
enter as part of the string. For example, you could set the
|
|||
|
minimum character to the '0' character and the maximum character
|
|||
|
to the '9' character, permitting the user to only enter numeric
|
|||
|
characters. On the other hand, you could permit the user to
|
|||
|
enter all ASCII characters in the range from 32 to 127. The
|
|||
|
od_input_str() function will permit characters in the range
|
|||
|
beginning with the character passed as minchar, up to and
|
|||
|
including the character passed as maxchar.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_edit_str(), od_get_key(), od_clear_keybuffer()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below are a number of examples of the use of the od_input_str()
|
|||
|
function in various applications:
|
|||
|
|
|||
|
- To input a two character number (only digits from 0-9):
|
|||
|
|
|||
|
od_input_str(string, 2, '0', '9');
|
|||
|
|
|||
|
- To input a 35 character name (characters from Space to
|
|||
|
ASCII 127):
|
|||
|
|
|||
|
od_input_str(string, 35, 32, 127);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 96
|
|||
|
|
|||
|
OD_KERNEL()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE The OpenDoors Central Control function.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_kernel(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION In the DOS version of OpenDoors, the od_kernel() function is
|
|||
|
responsible for many vital OpenDoors tasks, such as monitoring
|
|||
|
the carrier detect signal, monitoring the amount of time that
|
|||
|
the user has remaining, updating the status line, responding to
|
|||
|
sysop hotkeys, and reading characters which are received from
|
|||
|
the modem. The od_kernel() function is automatically called on a
|
|||
|
frequent basis by the other OpenDoors functions, so most often
|
|||
|
you will not need to be concerned with this function. However,
|
|||
|
in order that OpenDoors can carry out the activities mentioned
|
|||
|
above with a quick response, it is important that od_kernel(),
|
|||
|
or some other OpenDoors function be called at least once every
|
|||
|
second. Thus, if your program will be carrying out some
|
|||
|
processing, in which it will not be calling any OpenDoors
|
|||
|
functions for more than a second or so, you should call the
|
|||
|
od_kernel() function yourself. The example below demonstrates
|
|||
|
one method of doing just this.
|
|||
|
|
|||
|
Note that if for some reason or other, it is not possible for
|
|||
|
your program to call the od_kernel() function, or any other
|
|||
|
OpenDoors functions for a period of several seconds, this will
|
|||
|
not cause your door to crash or fail in any way. The only
|
|||
|
problem will be that OpenDoors will not be able to respond to
|
|||
|
any action, such as the sysop pressing a function key, or the
|
|||
|
user dropping carrier, until such time as you next call
|
|||
|
od_kernel(), or some OpenDoors function. Hence, use of the
|
|||
|
od_kernel() function will improve the quality and response time
|
|||
|
of your program, but calling it or some OpenDoors function on a
|
|||
|
regular basis is not absolutely vital.
|
|||
|
|
|||
|
This function has no effect in the Win32 version of OpenDoors.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_sleep()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 97
|
|||
|
|
|||
|
OD_LIST_FILES()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Lists files in a particular file area (using FILES.BBS)
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_list_files(char *pszFileSpec);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE if successful, FALSE if unsuccessful
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function allows you to display a list of files available
|
|||
|
for download from a particular file area, as any BBS system
|
|||
|
would. The file names and descriptions are taken from the
|
|||
|
FILES.BBS located in the directory pointed to by pszFileSpec.
|
|||
|
Thus, to list the files available for download in
|
|||
|
C:\BBS\FILES\UPLOADS, simply:
|
|||
|
|
|||
|
od_list_files("C:\\BBS\\FILES\\UPLOADS");
|
|||
|
|
|||
|
OpenDoors uses a third-generation FILES.BBS format, that is
|
|||
|
compatible with other FILES.BBS formats, but adds some
|
|||
|
additional features. Each line in the FILES.BBS file lists a
|
|||
|
filename, along with it's description. Thus, a typical FILES.BBS
|
|||
|
file might look as follows:
|
|||
|
|
|||
|
PKZ110.EXE PKZip file compressor, version 1.10
|
|||
|
ODOORS60.ZIP The newest version of OpenDoors
|
|||
|
REC*.ZIP A Record file
|
|||
|
C:\BBS\*.* All BBS files.
|
|||
|
|
|||
|
When displayed, OpenDoors will list the size of each file found
|
|||
|
in the FILES.BBS file beside it's name, if the file is found. If
|
|||
|
the file does not exist, then a "[OFFLINE]" string is displayed
|
|||
|
in the file size column. Title lines may also be added to the
|
|||
|
FILES.BBS, by indenting them one or more columns. Thus, you
|
|||
|
could have something like:
|
|||
|
|
|||
|
NEWEST UPLOADS
|
|||
|
~~~~~~~~~~~~~~
|
|||
|
PKZ110.EXE PKZip file compressor, version 1.10
|
|||
|
ODOORS60.ZIP The newest version of OpenDoors
|
|||
|
REC*.ZIP A Record file
|
|||
|
C:\BBS\*.* All BBS files.
|
|||
|
|
|||
|
In addition to this standard FILES.BBS format, OpenDoors will
|
|||
|
also permit wildcards to be used in FILES.BBS filenames (ie
|
|||
|
FNEWS???.*), or full directory paths to allow files from several
|
|||
|
different directories to be included in the same files area.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 98
|
|||
|
|
|||
|
You may alter the colors used to display the various portions of
|
|||
|
the files list using the od_control variables:
|
|||
|
od_control.od_list_title_col
|
|||
|
od_control.od_list_name_col
|
|||
|
od_control.od_list_size_col
|
|||
|
od_control.od_list_comment_col
|
|||
|
od_control.od_list_offline_col
|
|||
|
|
|||
|
which are documented in the OpenDoors control structure section
|
|||
|
on this manual, which begins on page 148.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_send_file()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 99
|
|||
|
|
|||
|
OD_LOG_WRITE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to write an entry to the log file
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_log_write(char *pszMessage);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success, or FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function can be used to write entries to the log file. If
|
|||
|
the logfile has not already been opened when you call this
|
|||
|
function for the first time, OpenDoors will automatically open
|
|||
|
the log file at that time.
|
|||
|
|
|||
|
To create an entry in the log file, simply call the
|
|||
|
od_log_write() function, passing to it the string of the text
|
|||
|
you wish to write. You should not include any control characters
|
|||
|
in this string, simply the text that should appear on the line.
|
|||
|
OpenDoors will automatically format the log file, adding the
|
|||
|
time information and other control characters. It is recommended
|
|||
|
that the length of the string passed to od_log_write() not
|
|||
|
exceed 67 characters, in order that logfile lines will all be
|
|||
|
less than 80 characters in length.
|
|||
|
|
|||
|
Log file entries do not usually contain periods or other
|
|||
|
punctuation at the end of the line. Also, log file entries are
|
|||
|
usually written in the present tense. The first character of the
|
|||
|
entry is usually upper-case, with all other entries in lower
|
|||
|
case. Also, since excessive numbers or lengths of log file
|
|||
|
entries can quickly use a lot of disk space, it is best to think
|
|||
|
carefully about what events should be recorded in the log file.
|
|||
|
It is also a good idea to minimize the number of words used in
|
|||
|
the entry, without being too cryptic. As an example, "User
|
|||
|
entering options menu" should be used instead of "user entered
|
|||
|
the options menu."
|
|||
|
|
|||
|
|
|||
|
SEE ALSO Page 224.
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Calling the od_log_write() function is as simple as follows:
|
|||
|
|
|||
|
od_log_write("Awarding user with 5 minutes more time");
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 100
|
|||
|
|
|||
|
OD_MULTILINE_EDIT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Provides a multiple line text editor which can be used for
|
|||
|
entering editing any text that spans more than one line, such as
|
|||
|
messages or text files.
|
|||
|
|
|||
|
|
|||
|
FORMAT INT od_multiline_edit(char *pszBufferToEdit, UINT unBufferSize,
|
|||
|
tODEditOptions *pEditOptions);
|
|||
|
|
|||
|
|
|||
|
RETURNS OD_MULTIEDIT_SUCCESS on success, or OD_MULTIEDIT_ERROR on
|
|||
|
failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function provides a text editor with optional word wrap
|
|||
|
capabilities. This editor can be used for entering or editing
|
|||
|
text files, messages or other information that spans multiple
|
|||
|
lines. The editor can be configured to operate in full-screen
|
|||
|
mode, or to occupy any smaller area of the screen that you
|
|||
|
specify. It provides the navigation (home / end / page up / arrow
|
|||
|
keys) features and editing features (insert / overwrite mode,
|
|||
|
Ctrl-Y to delete a line, etc.) that you would expect.
|
|||
|
|
|||
|
The od_multiline_edit() function is designed to be both easy to
|
|||
|
use and very flexible. To that end, the function only takes three
|
|||
|
parameters. The first two parameters are required, and the third
|
|||
|
parameter is an optional options structure. The first parameter,
|
|||
|
pszBufferToEdit, is a pointer to the buffer of text to edit. This
|
|||
|
buffer must always be a '\0'-terminated string. This buffer must
|
|||
|
be initialized before calling od_multiline_edit(). The second
|
|||
|
parameter, unBufferSize, indicates the size of the buffer that is
|
|||
|
passed in pszBufferToEdit. Note that this should be the total
|
|||
|
amount of space that is available in the buffer for text entered
|
|||
|
by the user, not the length of data that is actually initially in
|
|||
|
the buffer. If you do not wish to customize any of the
|
|||
|
od_multiline_edit() options, then you may simply set the third
|
|||
|
parameter to 0. Hence, a simple example of how to use
|
|||
|
od_multiline_edit() is:
|
|||
|
|
|||
|
char szMyEditBuffer[4000] = "";
|
|||
|
od_multiline_edit(szMyEditBuffer, sizeof(szMyEditBuffer),
|
|||
|
NULL);
|
|||
|
|
|||
|
If you wish to customize od_multiline_edit(), you should pass a
|
|||
|
pointer to a tODEditOptions structure as the third parameter. You
|
|||
|
should initialize this entire structure to zeros before
|
|||
|
attempting to use it. You can then set any values of this
|
|||
|
structure which you wish to change from their default. Any values
|
|||
|
that are left at 0 will automatically revert to their defaults.
|
|||
|
For example, if you wanted to specify a text format other than
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 101
|
|||
|
|
|||
|
the default, you could create, initialize and pass in a
|
|||
|
tODEditOptions structure as follows:
|
|||
|
|
|||
|
char szMyEditBuffer[4000] = "";
|
|||
|
tODEditOptions MyEditOptions;
|
|||
|
memset(&MyEditOptions, 0, sizeof(MyEditOptions));
|
|||
|
MyEditOptions.TextFormat = FORMAT_LINE_BREAKS;
|
|||
|
od_multiline_edit(szMyEditBuffer, sizeof(szMyEditBuffer),
|
|||
|
&MyEditOptions);
|
|||
|
|
|||
|
The definition of the tODEditOptions structure is as follows:
|
|||
|
|
|||
|
typedef struct
|
|||
|
{
|
|||
|
INT nAreaLeft;
|
|||
|
INT nAreaTop;
|
|||
|
INT nAreaRight;
|
|||
|
INT nAreaBottom;
|
|||
|
tODEditTextFormat TextFormat;
|
|||
|
tODEditMenuResult (*pfMenuCallback)(void *pUnused);
|
|||
|
void * (*pfBufferRealloc)(void *pOriginalBuffer,
|
|||
|
UINT unNewSize);
|
|||
|
DWORD dwEditFlags;
|
|||
|
char *pszFinalBuffer;
|
|||
|
UINT unFinalBufferSize;
|
|||
|
} tODEditOptions;
|
|||
|
|
|||
|
nAreaLeft, nAreaTop, nAreaRight, nAreaBottom allows you to
|
|||
|
specify the portion of the screen that the text editor should
|
|||
|
use. This defaults to 1, 1 - 80, 23.
|
|||
|
|
|||
|
TextFormat allows you to specify what format the text should be
|
|||
|
stored in the buffer using. The default is
|
|||
|
FORMAT_PARAGRAPH_BREAKS, which specifies that a line break only
|
|||
|
appears at the end of each paragraph, and that the contents of a
|
|||
|
paragraph are word wrapped. FORMAT_LINE_BREAKS specifies that a
|
|||
|
line break appears at the end of each line of text on the screen,
|
|||
|
and that newly entered text is word wrapped. FORMAT_NO_WORDWRAP
|
|||
|
is equivalent to FORMAT_LINE_BREAKS, except that newly entered
|
|||
|
text is not word wrapped. Instead, lines may be arbitrarily long.
|
|||
|
For each of these text formats, od_multiline_edit() automatically
|
|||
|
decides whether line breaks should take the form of a carriage
|
|||
|
return ('\r'), line feed ('\n'), or some combination of these,
|
|||
|
based on what it sees in the buffer that you supply. If no line
|
|||
|
breaks are found in the buffer, then the default is to use just a
|
|||
|
line feed ('\n') character. FORMAT_FTSC_MESSAGE specifies a FTSC-
|
|||
|
compliant message, such as is used in a *.MSG message file. Among
|
|||
|
other things, this specifies that carriage returns ('\r') end
|
|||
|
paragraphs, and that line feeds ('\n') should be ignored.
|
|||
|
|
|||
|
pfMenuCallback allows you to provide a callback function that
|
|||
|
will be called when the user presses the escape (or control-Z)
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 102
|
|||
|
|
|||
|
key. This allows you to provide a menu that can be accessed from
|
|||
|
within the text editor. This function should return
|
|||
|
EDIT_MENU_DO_NOTHING if the editor should continue normally, or
|
|||
|
EDIT_MENU_EXIT_EDITOR if the od_multiline_edit() should return.
|
|||
|
If no menu callback function is provided, then
|
|||
|
od_multiline_edit() always returns when the escape or control-z
|
|||
|
key is pressed.
|
|||
|
|
|||
|
pfBufferRealloc allows you to provide a function which will
|
|||
|
attempt to reallocate a larger buffer if the user enters more
|
|||
|
text than will fit in the originally supplied buffer. You should
|
|||
|
only do this if you have dynamically allocated the buffer that
|
|||
|
you initially passed into od_multiline_edit(). If you allocated
|
|||
|
the buffer using malloc() or calloc(), then pfBufferRealloc can
|
|||
|
be set to point to the realloc() function. If you allocated the
|
|||
|
buffer using the C++ new operator, then you must write a your own
|
|||
|
reallocation function which obeys the same semantics as the C
|
|||
|
realloc() function. If no buffer reallocation function is
|
|||
|
provided, then od_multiline_edit() will never allow the user to
|
|||
|
enter more text than will fit in the buffer that you initially
|
|||
|
supply. If you are using the buffer reallocation option, you can
|
|||
|
obtain a pointer to the final buffer, and the size of the final
|
|||
|
buffer, from the pszFinalBuffer and unFinalBufferSize members.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_input_str(), od_edit_str(), od_get_input()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 103
|
|||
|
|
|||
|
OD_PAGE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to allow user to page the sysop
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_page(void);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function can be called to allow the user to page the sysop.
|
|||
|
This function will ask the user why they wish to chat with the
|
|||
|
sysop, and then page the sysop. The sysop will then be free to
|
|||
|
break into chat at any time. Sysop paging will also be aborted
|
|||
|
by the user, simply by pressing [Enter] when asked for a reason
|
|||
|
for chat. When the user pages the sysop, the [Wants-Chat]
|
|||
|
indicator will begin to flash on the main status line, and the
|
|||
|
status line will switch to show the user's reason for wanting to
|
|||
|
chat. Also, the user's total number of pages will be
|
|||
|
incremented.
|
|||
|
|
|||
|
Depending upon the setting of the od_control.od_okaytopage
|
|||
|
variable, this function will also optionally check sysop paging
|
|||
|
hours, and only allow the user to page the sysop during valid
|
|||
|
paging hours. For information on the variables containing the
|
|||
|
user's total number of pages, the user's want-chat status, valid
|
|||
|
sysop paging hours, and the od_control.od_okaytopage variable,
|
|||
|
see the section on the OpenDoors control structure, which begins
|
|||
|
on page 148.
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_page() function, see the
|
|||
|
EX_VOTE.C example program, which is described beginning on page
|
|||
|
38.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 104
|
|||
|
|
|||
|
OD_PARSE_CMD_LINE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Handles standard command line options.
|
|||
|
|
|||
|
|
|||
|
FORMAT Under DOS Version:
|
|||
|
void od_parse_cmd_line(INT nArgCount, char *papszArguments[]);
|
|||
|
|
|||
|
Under Win32 Version:
|
|||
|
void od_parse_cmd_line(LPSTR pszCmdLine);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This is the only OpenDoors function that uses a different
|
|||
|
calling format in the DOS and Win32 versions of OpenDoors. The
|
|||
|
reason for this is that od_parse_cmd_line() always allows you to
|
|||
|
pass command line parameters in the same format that the
|
|||
|
operating system passes them to you. Under the DOS version of
|
|||
|
OpenDoors, you should pass the argc and argv values that were
|
|||
|
passed to your main function as the two parameters to
|
|||
|
od_parse_cmd_line(). Under the Win32 version of OpenDoors, you
|
|||
|
should pass the pszCmdLine values that were passed to your
|
|||
|
WinMain() function as the one parameter to od_parse_cmd_line().
|
|||
|
|
|||
|
The od_parse_cmd_line() function should be called before your
|
|||
|
first call to any other OpenDoors function, with the possible
|
|||
|
exception of the od_add_personality() function.
|
|||
|
|
|||
|
It is recommended that any program which uses OpenDoors call
|
|||
|
od_parse_cmd_line() as part of its startup procedure. This
|
|||
|
allows your program to automatically handle many common command
|
|||
|
line options that will make it easier to setup and run your
|
|||
|
program. Among the helpful command line options processed by
|
|||
|
od_parse_cmd_line() are options to set serial port information
|
|||
|
(including information on non-standard serial port setups),
|
|||
|
specify the location of configuration and drop files, force the
|
|||
|
program to run in silent mode (without no local display), pass
|
|||
|
in user information, and the ability to start the program in
|
|||
|
local mode without a drop file. For a complete list of the
|
|||
|
options supported by od_parse_cmd_line(), run the example Vote
|
|||
|
door that is included in the OpenDoors packages, specifying -
|
|||
|
help on the command line.
|
|||
|
|
|||
|
If you wish to process your own command line parameters in
|
|||
|
addition to those supported by OpenDoors, simply check the
|
|||
|
command-line for your own parameters after calling
|
|||
|
od_parse_cmd_line(). You can do this in the same way that you
|
|||
|
would handle command line options if you weren't using
|
|||
|
od_parse_cmd_line(). The od_parse_cmd_line() function does not
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 105
|
|||
|
|
|||
|
generate an error message if it encounters unrecognized command
|
|||
|
line options. You can supply your own text to display when the
|
|||
|
user chooses the /Help option by setting
|
|||
|
od_control.od_cmd_line_help to point to your own string. Separate
|
|||
|
lines in your string with the \n character, and align text using
|
|||
|
the \t character.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_init()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE The following example shows how a program that uses
|
|||
|
od_parse_cmd_line() should be structured in order to compile
|
|||
|
under either DOS or Win32 versions of OpenDoors:
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
/* main() or WinMain() function - Program begins here. */
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
|
|||
|
LPSTR lpszCmdLine, int nCmdShow)
|
|||
|
#else
|
|||
|
int main(int argc, char *argv[])
|
|||
|
#endif
|
|||
|
{
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
#endif
|
|||
|
|
|||
|
/* Set program's name for use by OpenDoors. */
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
/* In Windows, pass in nCmdShow value to OpenDoors. */
|
|||
|
od_control.od_cmd_show = nCmdShow;
|
|||
|
|
|||
|
/* Call od_parse_cmd_line. */
|
|||
|
od_parse_cmd_line(lpszCmdLine);
|
|||
|
#else
|
|||
|
od_parse_cmd_line(argc, argv);
|
|||
|
#endif
|
|||
|
|
|||
|
|
|||
|
/* Start the rest of your program here. */
|
|||
|
|
|||
|
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 106
|
|||
|
|
|||
|
OD_POPUP_MENU()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Creates a popup menu which allows the user to make a selection
|
|||
|
by pressing a single key, or selecting the item with a highlight
|
|||
|
bar. After the user has made a selection, the menu may be
|
|||
|
removed from the screen, restoring the original screen contents
|
|||
|
"beneath" the window.
|
|||
|
|
|||
|
|
|||
|
FORMAT INT od_popup_menu(char *pszTitle, char *pszText, INT nLeft,
|
|||
|
INT nTop, INT nLevel, WORD uFlags);
|
|||
|
|
|||
|
|
|||
|
RETURNS POPUP_ERROR On error (od_control.od_error is set to
|
|||
|
indicate type of error).
|
|||
|
POPUP_ESCAPE If user exited menu by pressing [ESCape].
|
|||
|
POPUP_LEFT If user exited menu by pressing the left arrow
|
|||
|
key.
|
|||
|
POPUP_RIGHT If user exited menu by pressing the right arrow
|
|||
|
key.
|
|||
|
|
|||
|
Or, a postive integer indicating the menu item that was chosen
|
|||
|
if a selection was made.
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION od_popup_menu() creates a popup window with a menu of choices,
|
|||
|
for use in ANSI/AVATAR/RIP modes. The user is able to choose an
|
|||
|
item from the menu by moving the highlighted selection bar with
|
|||
|
the arrow keys, or by pressing a key associated with a
|
|||
|
particular menu item. The contents of the menu are defined by
|
|||
|
the string pointed to by the pszText parameter. This menu
|
|||
|
definition string contains each menu option, separated by a '|'
|
|||
|
(pipe) character. Keys associated with each menu entry can be
|
|||
|
defined by proceeding the letter with a '^' (carat) character.
|
|||
|
For example, the string:
|
|||
|
|
|||
|
"^Save|^Load|E^xit"
|
|||
|
|
|||
|
would produce a menu with three options: Save, Load and Exit.
|
|||
|
The user would be able to select the Save option by pressing the
|
|||
|
[S] key, the Load option by pressing the [L] key, and the Exit
|
|||
|
option by pressing the [X] key. Furthermore, the characters
|
|||
|
corresponding to each menu item would be displayed in a
|
|||
|
highlighted color.
|
|||
|
|
|||
|
Menus displayed with od_popup_menu() may optionally have a
|
|||
|
title, as specified by the pszTitle parameter. If this parameter
|
|||
|
is set to NULL, no title will be displayed. If this parameter is
|
|||
|
not NULL, the specified string will be displayed as a title on
|
|||
|
the window.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 107
|
|||
|
|
|||
|
The nLeft and nTop parameters specify the left and top locations
|
|||
|
of the menu window, were 1, 1 is the upper right corner of the
|
|||
|
screen. The bottom and right corners of the menu are
|
|||
|
automatically determined by the size and number of menu entries
|
|||
|
in the menu definition string.
|
|||
|
|
|||
|
The nLevel parameter specifies the menu level, an integer from 0
|
|||
|
to 10. Unless you are using the MENU_KEEP flag, this parameter
|
|||
|
can always be 0.
|
|||
|
|
|||
|
The uFlags parameter specifies one or more of the following
|
|||
|
options, joined by the bitwise-OR operator (|).
|
|||
|
|
|||
|
MENU_NORMAL Has no effect.
|
|||
|
MENU_ALLOW_CANCEL Allow user to exit menu with [ESCape].
|
|||
|
MENU_PULLDOWN Allow exit with arrow keys.
|
|||
|
MENU_KEEP Leave menu active on selection.
|
|||
|
MENU_DESTROY Remove a currently active menu.
|
|||
|
|
|||
|
If you are not using any of the other flags, you can use
|
|||
|
MENU_NORMAL as a place-holder for this parameter. If you specify
|
|||
|
MENU_ALLOW_CANCEL, the user will be able to exit the menu
|
|||
|
without making a selection by pressing the [ESCape] key. If the
|
|||
|
user presses [ESCape], od_popup_menu() returns POPUP_ESCAPE.
|
|||
|
|
|||
|
You can use the MENU_PULLDOWN option with od_popup_menu() to
|
|||
|
implement a set of pulldown menus. In this case, if the user
|
|||
|
presses the left arrow key or right arrow key while the menu is
|
|||
|
being displayed, od_popup_menu() returns with POPUP_LEFT or
|
|||
|
POPUP_RIGHT, allowing you to display a different menu.
|
|||
|
|
|||
|
Normally, od_popup_menu() will remove the menu from the screen
|
|||
|
as soon as the user makes a selection. However, there may be
|
|||
|
some cases when you want the menu to continue to be visible
|
|||
|
after the user makes a selection. For example, you may want some
|
|||
|
menu options to lead to further sub-menus, or you may wish to
|
|||
|
display a popup window, and return to this menu after the user
|
|||
|
has exited from the popup window. If the MENU_KEEP flag is
|
|||
|
specified, the menu will remain active (on-screen) after the
|
|||
|
user makes a selection. However, the menu will still be
|
|||
|
destroyed if the user cancels out of the menu (this will only
|
|||
|
happen if you have specified MENU_ALLOW_CANCEL), or if the user
|
|||
|
moves to another menu by pressing the left or right arrow keys
|
|||
|
(this will only happen if you have specified MENU_PULLDOWN). If
|
|||
|
MENU_KEEP has been specified, and the user makes a selection,
|
|||
|
you must eventually either return to the menu, or destroy it by
|
|||
|
calling MENU_DESTROY. If you want to return to the menu, simply
|
|||
|
call od_popup_menu() again with the same level value that was
|
|||
|
used to originally create the menu. The user will now be able to
|
|||
|
make another selection from the menu, and od_popup_menu() will
|
|||
|
once again return that selection to you. If you want to destroy
|
|||
|
the menu, simply call od_popup_menu() with the MENU_DESTROY flag
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 108
|
|||
|
|
|||
|
set, and the same level value that was used to create the
|
|||
|
original menu. If you wish to create another popup menu while
|
|||
|
the first one is still active, simply call od_popup_menu()
|
|||
|
again, this time with a different level value. The colors used
|
|||
|
by the od_popup_menu() function are set by the following
|
|||
|
OpenDoors control structure settings:
|
|||
|
|
|||
|
char od_control.od_menu_title_col;
|
|||
|
char od_control.od_menu_border_col;
|
|||
|
char od_control.od_menu_text_col;
|
|||
|
char od_control.od_menu_key_col;
|
|||
|
char od_control.od_menu_highlight_col;
|
|||
|
char od_control.od_menu_highkey_col;
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_window_create(), od_window_remove(), od_draw_box(),
|
|||
|
od_hotkey_menu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE The following example shows the use of multiple-level menus:
|
|||
|
|
|||
|
#include <stdlib.h>
|
|||
|
#include "opendoor.h"
|
|||
|
main()
|
|||
|
{
|
|||
|
for(;;)
|
|||
|
{
|
|||
|
switch(od_popup_menu("Main Menu",
|
|||
|
"^Files|^Electronic Mail|^News|E^xit",
|
|||
|
20, 5, 0, MENU_NORMAL | MENU_KEEP))
|
|||
|
{
|
|||
|
case 1:
|
|||
|
od_popup_menu("Files Menu",
|
|||
|
"^Search For Files|^Download|^Upload",
|
|||
|
30, 7, 2, MENU_NORMAL | MENU_ALLOW_CANCEL);
|
|||
|
break;
|
|||
|
case 2:
|
|||
|
od_popup_menu("EMail Menu",
|
|||
|
"Get ^New Mail|^Send Mail|Send ^Fax",
|
|||
|
30, 8, 1, MENU_NORMAL | MENU_ALLOW_CANCEL);
|
|||
|
break;
|
|||
|
case 3:
|
|||
|
od_popup_menu("News Menu",
|
|||
|
"Choose News^Group|^Read News|^Post News",
|
|||
|
30, 9, 1, MENU_NORMAL | MENU_ALLOW_CANCEL);
|
|||
|
break;
|
|||
|
case 4:
|
|||
|
od_popup_menu(NULL, NULL, 0, 0, 0, MENU_DESTROY);
|
|||
|
return(0);
|
|||
|
}
|
|||
|
}
|
|||
|
}
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 109
|
|||
|
|
|||
|
OD_PRINTF()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Performs formatted output (remote & local), with the ability to
|
|||
|
change display colors.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_printf(char * pszFormat,...);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This is one of two OpenDoors function which allows you to
|
|||
|
display a string of characters, the other being the
|
|||
|
od_disp_str() function. For a complete comparison of the various
|
|||
|
OpenDoors display function, see the description of the
|
|||
|
od_disp_str() function, on page 63. Like the od_disp_str()
|
|||
|
function, the od_printf() function will display its output both
|
|||
|
on the local screen, and on the remote user's screen (if the
|
|||
|
door is not operating in local mode). However, the od_printf()
|
|||
|
function also allows for formatted output, just as the printf()
|
|||
|
function does. In addition to providing all of the features of
|
|||
|
the normal C printf() function, the od_printf() function allows
|
|||
|
you to include codes to change the color of the display of text.
|
|||
|
This unique feature allows you to display multi-colored text,
|
|||
|
without having to use chains of alternating od_disp_str() and
|
|||
|
od_set_color() calls.
|
|||
|
|
|||
|
As with the printf() function, the od_printf() function accepts
|
|||
|
one or more parameters, the first parameter being the format
|
|||
|
string to be displayed, and the additional parameters being data
|
|||
|
to be displayed within the string. The OpenDoors od_printf()
|
|||
|
function recognizes all of the control characters and options
|
|||
|
recognized by the normal printf() function. For example, to
|
|||
|
display the amount of time that a user has left online, the
|
|||
|
following line would be a valid use of the od_printf() function:
|
|||
|
|
|||
|
od_printf("Time Left:%d\n\r", od_control.user_timelimit);
|
|||
|
|
|||
|
Note that a full discussion of the printf() function is beyond
|
|||
|
the scope of this manual. For more information on using
|
|||
|
printf(), please see your Turbo C(++) / Borland C++ manuals.
|
|||
|
|
|||
|
In addition to the normal control sequences, such as "%s", "%d",
|
|||
|
or "%12.12s", the od_printf() function also allows you to
|
|||
|
include special color-setting codes within the format string.
|
|||
|
These color code sequences BEGIN and END with a delimiter
|
|||
|
character, which is used to indicate that the sequence is a
|
|||
|
color setting. Consider, for example, the following line of
|
|||
|
code, which displays text in various colors:
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 110
|
|||
|
|
|||
|
od_printf("`blue`Blue `green`Green `red`Red \n\r");
|
|||
|
|
|||
|
In this case (assuming of course that a color monitor is being
|
|||
|
used) the word "Blue" will be displayed in the color blue, the
|
|||
|
word "Green" will be displayed in the color green, and the word
|
|||
|
"Red" will be displayed in the color red. In this case, the
|
|||
|
sequence `blue` sets the display color to dark blue on black.
|
|||
|
Here, the back-quote (`) is the delimiter character which
|
|||
|
indicates the beginning and end of the color sequence. Be sure
|
|||
|
not to confuse the back-quote character (`) with the normal
|
|||
|
forward quote ('). THIS IS THE MOST COMMON DIFFICULTY
|
|||
|
EXPERIENCED WITH THE OD_PRINTF() FUNCTION. The text between the
|
|||
|
back-quote characters indicates the color that should be set.
|
|||
|
This text can include the name of the foreground color, the name
|
|||
|
of the background color, the "bright" keyword and the "flashing"
|
|||
|
keyword. The first color mentioned is taken to be the foreground
|
|||
|
color, and the second the background color. Case is not
|
|||
|
sensitive, additional words can be included for legibility.
|
|||
|
Thus:
|
|||
|
|
|||
|
`bright white cyan`
|
|||
|
|
|||
|
is equivalent to:
|
|||
|
|
|||
|
`Bright white on a cyan background`.
|
|||
|
|
|||
|
The "bright" keyword indicates that the foreground color should
|
|||
|
be displayed in high intensity, and the "flashing" keyword
|
|||
|
indicates that the text should be flashing. If no background is
|
|||
|
specified, the background color defaults to black. If no
|
|||
|
foreground or background colors are specified, the color
|
|||
|
defaults to white on black.
|
|||
|
|
|||
|
The od_printf() function will automatically determine whether
|
|||
|
the user has ANSI, AVATAR or RIP graphics enabled, and will send
|
|||
|
the appropriate color codes to change the color of displayed
|
|||
|
text. If the user does not have either ANSI or AVATAR graphics
|
|||
|
modes turned on, then the od_printf() function will not send any
|
|||
|
color codes. Thus, a door program using color codes would work
|
|||
|
just as well when ANSI/AVATAR/RIP graphics are not available,
|
|||
|
except that all text will appear in the same color.
|
|||
|
|
|||
|
You may prefer to set colors by using the od_set_color() or
|
|||
|
od_set_attrib() functions, instead of using these cryptic color
|
|||
|
codes imbedded in od_printf() functions. In some cases, however,
|
|||
|
it will be much more advantageous to place the color codes
|
|||
|
within your od_printf() strings. As a case in point, consider
|
|||
|
the single od_printf() statement in the example, above. To
|
|||
|
accomplish the same result using the od_disp_str() and
|
|||
|
od_set_color() functions, you would have to use the following
|
|||
|
SIX function calls:
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 111
|
|||
|
|
|||
|
od_set_color(D_BLUE,D_BLACK);
|
|||
|
od_disp_str("Blue ");
|
|||
|
od_set_color(D_GREEN,D_BLACK);
|
|||
|
od_disp_str("Green ");
|
|||
|
od_set_color(D_RED,D_BLACK);
|
|||
|
od_disp_str("Red \n\r");
|
|||
|
|
|||
|
While this method MAY be easier understand, it certainly
|
|||
|
requires many more line of code to accomplish. However, either
|
|||
|
method will work, and the choice is up to you as to which method
|
|||
|
you prefer. Keep in mind, however, that if the color to be set
|
|||
|
is stored in a variable, instead of always being the same color,
|
|||
|
you must use either the od_set_color() or od_set_attrib()
|
|||
|
function to set the display color.
|
|||
|
|
|||
|
While the back-quote (`) character is normally used to delimit a
|
|||
|
color sequence in the od_printf() function, you may wish to be
|
|||
|
able to print a back-quote character using the od_printf()
|
|||
|
function. In this case, you may configure OpenDoors to use a
|
|||
|
different character to represent color code sequences. To do
|
|||
|
this, simply use the od_control.od_color_delimiter variable,
|
|||
|
which is described in the OpenDoors control structure section,
|
|||
|
beginning on page 148. For example, if you wished to use the
|
|||
|
tilde (~) character instead of the back-quote character to
|
|||
|
change colors, simply place the following line within your
|
|||
|
program, at some point after having called od_init() or some
|
|||
|
OpenDoors function:
|
|||
|
|
|||
|
od_control.od_color_delimiter='~';
|
|||
|
|
|||
|
Also, you may disable the color code interpretation within the
|
|||
|
od_printf() function altogether, by setting the
|
|||
|
od_control.od_color_delimiter variable to 0.
|
|||
|
|
|||
|
Note that the od_printf() function interprets the color codes
|
|||
|
AFTER parsing the other control sequences, such as "%d" or "%s".
|
|||
|
Thus, if you used the command:
|
|||
|
|
|||
|
od_printf("%s",string);
|
|||
|
|
|||
|
Any color codes contained in the string "string" would also be
|
|||
|
interpreted. If you did not wish to have any color code
|
|||
|
characters which might be contained in the string "string"
|
|||
|
treated as such, you could again disable od_printf()'s color
|
|||
|
code interpretation, by setting the od_control.od_color_char
|
|||
|
variable to 0.
|
|||
|
|
|||
|
Note that the string to be displayed by od_printf() should not
|
|||
|
exceed 511 characters in size, including the size of color
|
|||
|
sequences and expanded % fields.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 112
|
|||
|
|
|||
|
SEE ALSO od_disp_str(), od_disp(), od_putch(), od_repeat(), od_disp_emu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below is a simple example of a user statistics door program,
|
|||
|
which displays various pieces of information to the user, by
|
|||
|
using the od_printf() function. Notice the use of color code
|
|||
|
sequences in order to display the titles in a different color
|
|||
|
from the information fields. Note that since the information
|
|||
|
available to this door will depend on the BBS system under which
|
|||
|
it is running, not all of the information displayed by this door
|
|||
|
will be available under all BBS systems. For a description of
|
|||
|
what information is available under what BBS systems, see the
|
|||
|
OpenDoors control structure portion of this manual, which begins
|
|||
|
on page 148.
|
|||
|
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
int main(int argc,char *argv[])
|
|||
|
{
|
|||
|
od_init(); /* Begin OpenDoors program */
|
|||
|
|
|||
|
od_printf("`bright white` YOUR STATISTICS\n\r"); /* Display title */
|
|||
|
od_printf("---------------\n\r\n\r");
|
|||
|
|
|||
|
/* Display statistics */
|
|||
|
od_printf("`red`NAME : `blue`%s\n\r",od_control.user_logintime);
|
|||
|
od_printf("`red`LOCATION : `blue`%s\n\r",od_control.user_location);
|
|||
|
od_printf("`red`PHONE NUMBER : `blue`%s\n\r",od_control.user_homephone);
|
|||
|
od_printf("`red`LAST CALL : `blue`%s\n\r",od_control.user_lastdate);
|
|||
|
od_printf("`red`NUMBER OF CALLS : `blue`%u\n\r",od_control.user_numcalls);
|
|||
|
od_printf("`red`NUMBER OF PAGES : `blue`%u\n\r",od_control.user_numpages);
|
|||
|
od_printf("`red`REMAINING TIME : `blue`%d\n\r",od_control.user_timelimit);
|
|||
|
od_printf("`red`# OF DOWNLOADS : `blue`%u\n\r",od_control.user_downloads);
|
|||
|
od_printf("`red`# OF UPLOADS : `blue`%u\n\r",od_control.user_uploads);
|
|||
|
od_printf("`red`KBYTES DL TODAY : `blue`%u\n\r",od_control.user_todayk);
|
|||
|
|
|||
|
/* Ask user to press [Enter] */
|
|||
|
od_printf("`bright green on green`Press [Enter] to return to BBS...\n\r");
|
|||
|
|
|||
|
while(od_get_key(TRUE)!=13); /* Wait for user to press [Enter] */
|
|||
|
|
|||
|
od_exit(20,FALSE); /* Return to BBS */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
HELPFUL This section demonstrates use of the od_printf() color
|
|||
|
HINT sequences imbedded directly in the printf() format string, such
|
|||
|
as:
|
|||
|
|
|||
|
od_printf("Hello `bright green` there!");
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 113
|
|||
|
|
|||
|
However, there are also other ways that you can take advantage
|
|||
|
of this feature. For example, the C programming language
|
|||
|
concatenates string constants that are separated only by white
|
|||
|
space or carriage returns. For instance,
|
|||
|
|
|||
|
"Hello " "`bright green`" " there!"
|
|||
|
|
|||
|
is equivalent to:
|
|||
|
|
|||
|
"Hello `bright green` there!"
|
|||
|
|
|||
|
For this reason, you can create macros for common color
|
|||
|
sequences in your program, such as:
|
|||
|
|
|||
|
#define HIGHLIGHT "`bright green`"
|
|||
|
|
|||
|
You can then use such constants when calling the od_printf()
|
|||
|
function, as follows:
|
|||
|
|
|||
|
od_printf("Hello " HIGHLIGHT " there!");
|
|||
|
|
|||
|
You may find this method of setting the display color to be
|
|||
|
easier to read, and more easily configurable than including the
|
|||
|
color sequence directly in the format string. Below another use
|
|||
|
of the color sequences is describe, which allows the colors used
|
|||
|
by od_printf() not be "hard-wired".
|
|||
|
|
|||
|
|
|||
|
Since color control sequences are evaluated by od_printf() after
|
|||
|
it evaluates all format sequences (such as "%d"). For this
|
|||
|
reason, it is possible to change the display color using a
|
|||
|
string variable, instead of using a fixed color in the string.
|
|||
|
For example, if you program had the variable:
|
|||
|
|
|||
|
char highlight[40];
|
|||
|
|
|||
|
which was set at some point to be equal to:
|
|||
|
|
|||
|
"`bright green`"
|
|||
|
|
|||
|
you would be able to use od_printf() as follows:
|
|||
|
|
|||
|
od_printf("Hello %s there!", highlight);
|
|||
|
|
|||
|
The display color would then be changed at the location where
|
|||
|
the "%s" appears in the od_printf() format string. The advantage
|
|||
|
of using this method to change display colors is that unlike
|
|||
|
other methods, the value of the highlight variable can be
|
|||
|
changed. This could be used, for example, to allow the sysop to
|
|||
|
configure the colors they wish your door to use. You would only
|
|||
|
need to change the value of the highlight variable in order to
|
|||
|
change the color set by od_printf().
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 114
|
|||
|
|
|||
|
OD_PUTCH()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to display a single character.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_putch(int chToDisplay);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function performs a similar function to the other OpenDoors
|
|||
|
display functions. For information on the uses of the various
|
|||
|
OpenDoors display functions, see the description of the
|
|||
|
od_disp_str() function, on page 63. This function is most
|
|||
|
similar to the od_disp() and od_disp_str() functions, except
|
|||
|
that it only displays a single character at a time.
|
|||
|
|
|||
|
This function will display the character passed to it at the
|
|||
|
cursor position in the output window, and then advance the
|
|||
|
cursor to the next display position. If OpenDoors is not
|
|||
|
operating in local mode, the character will also be sent to the
|
|||
|
modem, and thus displayed on the user's screen in the same
|
|||
|
manner that it is displayed on the local screen. If ANSI, AVATAR
|
|||
|
or RIP graphics mode is activated the character will be
|
|||
|
displayed in the current color.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_disp_str(), od_disp(), od_printf(), od_repeat(),
|
|||
|
od_disp_emu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below is an example of the use of the od_putch() function. This
|
|||
|
example is a function which you could use in place of the
|
|||
|
od_get_key() function. This function inputs a single character
|
|||
|
from the keyboard, just as the od_get_key() function does.
|
|||
|
However, if the character entered is a printable character, the
|
|||
|
function will also echo the character to the local screen, using
|
|||
|
the od_putch() function.
|
|||
|
|
|||
|
char get_key_with_echo(int wait)
|
|||
|
{
|
|||
|
char pressed=od_get_key(wait); /* Get key from user */
|
|||
|
|
|||
|
if(pressed>=32 && pressed<=126) /* If key is printable */
|
|||
|
{
|
|||
|
od_putch(pressed); /* Display the character */
|
|||
|
}
|
|||
|
|
|||
|
return(pressed); /* Return key pressed by user */
|
|||
|
}
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 115
|
|||
|
|
|||
|
OD_PUTTEXT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Displays a rectangular region of text and color information, as
|
|||
|
previously stored using od_gettext()
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_puttext(INT nLeft, INT nTop, INT nRight, INT nBottom,
|
|||
|
void *pBlock);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function "pastes" a rectangular block of text and color
|
|||
|
information that has been previously retrieved using
|
|||
|
od_gettext(). The block is placed at the screen location
|
|||
|
indicated by the variables nLeft, nTop, nRight and nBottom,
|
|||
|
where nLeft and nRight are column numbers from 1 - 80, and nTop
|
|||
|
and nBottom are row numbers from 1 - 23. The length and width of
|
|||
|
the rectangle specified by nLeft, nTop, nRight and nBottom must
|
|||
|
be the same as the length and width of the rectangle passed to
|
|||
|
od_gettext() when storing the block of text.
|
|||
|
|
|||
|
This function attempts to display the pasted block as quickly as
|
|||
|
possible, only transmitting information on portions of the block
|
|||
|
that are different than the original screen contents. When this
|
|||
|
function returns, it leaves the cursor at its original position,
|
|||
|
and the display color at its original setting. This function
|
|||
|
requires ANSI or AVATAR mode.
|
|||
|
|
|||
|
The control structure variable od_control.od_full_put may be set
|
|||
|
to TRUE to force od_puttext() to always send all characters in
|
|||
|
the block to be displayed, instead of only displaying the
|
|||
|
portions of the block that differ from the original screen
|
|||
|
contents. If you wish to save and restore the entire screen, you
|
|||
|
can use od_save_screen() and od_restore_screen(), which work in
|
|||
|
all display modes.
|
|||
|
|
|||
|
You may also use the od_puttext() to display a rectangular block
|
|||
|
of text that you generate manually, instead of retrieving using
|
|||
|
od_gettext(). To do this, you pass an array which contains the
|
|||
|
text and color information for the rectangular area to be
|
|||
|
painted, in the pBlock parameter. The array passed to
|
|||
|
od_puttext() contains a two-byte sequence of information for
|
|||
|
each character in the rectangle. The first byte contains the
|
|||
|
ASCII code of the character to be displayed. The second byte
|
|||
|
contains the color attribute value of the character, in the same
|
|||
|
format as used by the od_set_attrib() function (described on
|
|||
|
page 128). These two byte sequences are stored in the order in
|
|||
|
which English is written; the array begins with the two byte
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 116
|
|||
|
|
|||
|
sequences for all of the characters on the first line, from left
|
|||
|
to right, followed by the characters for the second line, and so
|
|||
|
on. The length of each line must be exactly equal to the width
|
|||
|
of the rectangular region to be painted.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_gettext(), od_save_screen(), od_restore_screen(),
|
|||
|
od_scroll(), od_window_create(), od_window_remove()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 117
|
|||
|
|
|||
|
OD_REPEAT()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Repeatedly display the specified character any number of times,
|
|||
|
using special graphics codes for greater speed, if possible.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_repeat(char chValue, BYTE btTimes);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This display function will repeatedly display the character
|
|||
|
chValue, btTimes times. For a complete breakdown of the various
|
|||
|
OpenDoors display functions, see the description of the
|
|||
|
od_disp_str() function, located on page 63.
|
|||
|
|
|||
|
The advantage of using this function to display a series of
|
|||
|
identical characters is that this function will use special
|
|||
|
graphics-mode control sequences to display the repeated
|
|||
|
character very efficiently, if the required graphics mode is
|
|||
|
available. For example, in AVATAR mode, this function can
|
|||
|
display an entire line of one character, by sending a control
|
|||
|
sequence to the modem that is only three characters long. If
|
|||
|
graphics mode is not turned on, then the od_disp_str() function
|
|||
|
will simply send the specified character the appropriate number
|
|||
|
of times. As with the other display functions, the output of
|
|||
|
this function is sent to both the local and remote screens.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_putch(), od_disp_str(), od_disp(), od_printf(), od_disp_emu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE The example function below demonstrates the use of the
|
|||
|
od_repeat() function in drawing a window (a square box) on the
|
|||
|
screen. This function is essentially a simplified version of the
|
|||
|
od_draw_box() function, which is described on page 65. Unlike
|
|||
|
this function, the od_draw_box() function allows the
|
|||
|
customization of the characters used to draw the box's boarder,
|
|||
|
and if possible uses additional AVATAR graphics codes to display
|
|||
|
the window even faster than this function does. Thus, the
|
|||
|
function below is really provided for demonstration purposes
|
|||
|
only.
|
|||
|
|
|||
|
This function accepts four parameters, which indicate the
|
|||
|
location of the upper left and lower right corners of the window
|
|||
|
to be displayed. The function then displays the window with the
|
|||
|
current color attribute settings. Since this function uses the
|
|||
|
od_repeat() function, if AVATAR graphics are available, it can
|
|||
|
display the entire window in a fraction of a second, even if it
|
|||
|
is displaying a window the size of the entire screen at slow
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 118
|
|||
|
|
|||
|
baud rates. Note that this window display function requires that
|
|||
|
the user has ANSI, AVATAR or RIP graphics mode enabled.
|
|||
|
|
|||
|
void draw_window(char left, char top, char right, char bottom)
|
|||
|
{
|
|||
|
char line_counter; /* Number of current line being drawn */
|
|||
|
char between_size=(right-left)-1; /* X size of window */
|
|||
|
|
|||
|
od_set_cursor(top,left); /* move to top corner */
|
|||
|
od_putch(218); /* display corner character */
|
|||
|
od_repeat(196,between_size); /* display top line */
|
|||
|
od_putch(191); /* display corner character */
|
|||
|
/* loop through middle lines of window */
|
|||
|
for(line_counter=top+1;line_counter<bottom;++line_counter)
|
|||
|
{
|
|||
|
od_set_cursor(line_counter,left); /* move to line start */
|
|||
|
od_putch(179); /* display left line char */
|
|||
|
od_repeat(' ',between_size); /* display blank area */
|
|||
|
od_putch(179); /* display right line char */
|
|||
|
}
|
|||
|
|
|||
|
od_set_cursor(bottom,left); /* move to bottom corner */
|
|||
|
od_putch(192); /* display corner character */
|
|||
|
od_repeat(196,between_size); /* display bottom line */
|
|||
|
od_putch(217); /* display corner character */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 119
|
|||
|
|
|||
|
OD_RESTORE_SCREEN()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Restores the screen contents as previous saved using the
|
|||
|
od_save_screen() function. This function can be used in any
|
|||
|
display mode.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_restore_screen(void *pBuffer);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function restores the entire contents of the screen, along
|
|||
|
with the current cursor position and display color, which was
|
|||
|
previously stored using the od_save_screen() function. Unlike
|
|||
|
the od_get_text() and od_put_text() functions, the
|
|||
|
od_save_screen() and od_restore_screen() functions will work in
|
|||
|
all display modes (ASCII, ANSI, AVATAR and RIP).
|
|||
|
|
|||
|
The pBuffer parameter must point to the buffer previously passed
|
|||
|
to od_save_screen(). Note that the od_save_screen() and
|
|||
|
od_restore_screen() functions save the stored information in
|
|||
|
different formats than the od_getttext() and od_puttext()
|
|||
|
functions. For this reason, you cannot save the screen contents
|
|||
|
with od_gettext() and restore them with od_restore_screen(), or
|
|||
|
visa-versa.
|
|||
|
|
|||
|
If this function fails for any reason, a value of FALSE is
|
|||
|
returned, and the od_control.od_error variable is set to
|
|||
|
indicate the reason for the failure. For more information on the
|
|||
|
od_control.od_error variable, see page 185.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_save_screen(), od_gettext(), od_puttext(), od_clr_scr()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of how to use the od_restore_screen() function,
|
|||
|
see the example which accompanies the od_save_screen() function,
|
|||
|
on page 121.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 120
|
|||
|
|
|||
|
OD_SAVE_SCREEN()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Saves the contents of the screen, to later be restored using
|
|||
|
od_restore_screen(). Can be used in any display mode.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_save_screen(void *pBuffer);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function saves the entire contents of the screen, along
|
|||
|
with the current cursor position and display color, to be later
|
|||
|
restored using the od_restore_screen() function. Unlike the
|
|||
|
od_get_text() and od_put_text() functions, the od_save_screen()
|
|||
|
and od_restore_screen() functions will work in all display modes
|
|||
|
(ASCII, ANSI, AVATAR and RIP).
|
|||
|
|
|||
|
The pBuffer parameter should point to a buffer where the current
|
|||
|
screen information is to be stored. This buffer must be at least
|
|||
|
4004 bytes in size.
|
|||
|
|
|||
|
Note that the od_save_screen() and od_restore_screen() functions
|
|||
|
save the stored screen information in different formats than the
|
|||
|
od_getttext() and od_puttext() functions. For this reason, you
|
|||
|
cannot save the screen contents with od_save_screen() and
|
|||
|
restore them with od_puttext(), or visa-versa.
|
|||
|
|
|||
|
Also, note that when used in RIP graphics mode, this function
|
|||
|
only saves and restores textual information, and not bit-mapped
|
|||
|
graphical information.
|
|||
|
|
|||
|
If this function fails for any reason, a value of FALSE is
|
|||
|
returned, and the od_control.od_error variable is set to
|
|||
|
indicate the reason for the failure. For more information on the
|
|||
|
od_control.od_error variable, see page 185.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_restore_screen(), od_gettext(), od_puttext(), od_clr_scr()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE One case where you might wish to save and restore the contents
|
|||
|
of the screen is when sysop chat mode is activated. This can be
|
|||
|
accomplished by using the od_control.od_cbefore_chat and
|
|||
|
od_control.od_cafter_chat variables. The following example
|
|||
|
causes the screen contents to be saved and the entire screen
|
|||
|
cleared, prior to entering sysop chat mode when the sysop
|
|||
|
presses the "chat key". When the sysop ends chat mode, the
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 121
|
|||
|
|
|||
|
user's original screen is restored, and the user will be able to
|
|||
|
continue working in the door as though nothing had happened.
|
|||
|
|
|||
|
Code to perform screen saving and restoring:
|
|||
|
|
|||
|
/* Function prototypes */
|
|||
|
void before_chat_function(void);
|
|||
|
void after_chat_function(void);
|
|||
|
|
|||
|
/* Buffer to hold contents of screen prior to chat */
|
|||
|
char before_chat_buffer[4004];
|
|||
|
/* Variable to store whether screen save was successful */
|
|||
|
char before_chat_saved = FALSE;
|
|||
|
|
|||
|
/* Function which is called prior to entering chat mode */
|
|||
|
void before_chat_function(void)
|
|||
|
{
|
|||
|
/* Store current screen contents */
|
|||
|
before_chat_saved = od_save_screen(before_chat_buffer);
|
|||
|
|
|||
|
/* Present a blank screen for chat mode */
|
|||
|
od_clr_scr();
|
|||
|
}
|
|||
|
|
|||
|
/* Function which is called after exiting chat mode */
|
|||
|
void after_chat_function(void)
|
|||
|
{
|
|||
|
/* If screen was successfully saved prior to chat */
|
|||
|
if(before_chat_saved)
|
|||
|
{
|
|||
|
/* Restore original screen contents */
|
|||
|
od_restore_screen(before_chat_buffer);
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
Code included in main() function to enable screen saving and
|
|||
|
restoring code:
|
|||
|
|
|||
|
od_control.od_cbefore_chat = before_chat_function;
|
|||
|
od_control.od_cafter_chat = after_chat_function;
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 122
|
|||
|
|
|||
|
OD_SCROLL()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Scrolls any rectangular area of the screen a specified number of
|
|||
|
lines upwards or downwards. Requires ANSI/AVATAR/RIP graphics
|
|||
|
mode to be active.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_scroll(INT nLeft, INT nTop, INT nRight, INT nBottom,
|
|||
|
INT nDistance, WORD nFlags);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on FAILURE
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function scrolls a rectangular area of the screen described
|
|||
|
by the parameters nLeft, nTop, nRight and nBottom. The
|
|||
|
parameters nLeft and nRight are column numbers from 1 - 80, and
|
|||
|
the parameters nTop and nBottom are row numbers from 1 - 23.
|
|||
|
|
|||
|
The parameter nDistance indicates the direction and number of
|
|||
|
lines to scroll the text in the specified area. Positive values
|
|||
|
denote moving the text upwards, and negative values denote
|
|||
|
moving the text downwards.
|
|||
|
|
|||
|
The new lines created by scrolling text will appear in the
|
|||
|
current color. When this function returns, it leaves the cursor
|
|||
|
at its original position, and the display color at its original
|
|||
|
setting. This function requires ANSI or AVATAR modes. If ANSI
|
|||
|
mode is active, this function is equivalent to calling
|
|||
|
od_gettext(), od_puttext(), and then sending addition codes to
|
|||
|
the modem clear the newly created lines. In ANSI mode, scrolling
|
|||
|
can be accomplished more quickly if the area to be scrolled is
|
|||
|
equal in width to the entire screen. This is because the
|
|||
|
clearing of newly created lines is done by sending a simple
|
|||
|
control sequence, instead of a line of space characters. If
|
|||
|
AVATAR mode is active, scrolling of the window is accomplished
|
|||
|
by sending a single 6-byte control sequence.
|
|||
|
|
|||
|
The last parameter to od_scroll(), nFlags, should normally be
|
|||
|
set to SCROLL_NORMAL. However, if you set nFlags to
|
|||
|
SCROLL_NO_CLEAR, the newly created lines at the top or bottom of
|
|||
|
the screen are not cleared if it would take longer to do so.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_gettext(), od_puttext(), od_window_create(),
|
|||
|
od_window_remove()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of a program which uses the od_scroll() function,
|
|||
|
see the ex_chat.c example program, described on page 38.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 123
|
|||
|
|
|||
|
OD_SEND_FILE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Sends an ASCII/ANSI/AVATAR/RIP file from disk, using terminal
|
|||
|
emulation.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_send_file(char *pszFileName);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE if the file was successfully sent
|
|||
|
FALSE if OpenDoors was unable to send the file
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION: This powerful function will display any ASCII, ANSI, AVATAR or
|
|||
|
RIP file. The od_send_file() function can be used to display
|
|||
|
existing BBS text files, such as a "logoff screen", before your
|
|||
|
door hangs up on the user. You can also make use of the
|
|||
|
od_send_file() function to build many of your door screens as
|
|||
|
external files. This will allow you to easily create these
|
|||
|
screens in an ANSI editor program, such as "TheDraw". It will
|
|||
|
could also optionally allow sysops to customize your door for
|
|||
|
use on their own BBS.
|
|||
|
|
|||
|
The od_send_file() function is called with the full path and
|
|||
|
filename of the file you wish to have displayed. Thus, if you
|
|||
|
wished to send the ANSI file MAINMENU.SCR, you would simply
|
|||
|
call:
|
|||
|
|
|||
|
od_send_file("MAINMENU.SCR");
|
|||
|
|
|||
|
In many cases, instead of having just one file that you want
|
|||
|
displayed in particular, you will have several different files,
|
|||
|
and will want a different one displayed according to the user's
|
|||
|
graphics mode. For example, you might have the four files,
|
|||
|
MAINMENU.ASC, MAINMENU.ANS, MAINMENU.AVT and MAINMENU.RIP; the
|
|||
|
.ASC file containing no special control codes, the .ANS file
|
|||
|
containing ANSI control codes, the .AVT file containing AVATAR
|
|||
|
control codes, and the .RIP file containing RIP graphics control
|
|||
|
codes. In this case, you can have the od_send_file() function
|
|||
|
automatically select the appropriate file according to the
|
|||
|
user's current display mode, by omitting the extension
|
|||
|
altogether. Thus, a call to:
|
|||
|
|
|||
|
od_send_file("MAINMENU");
|
|||
|
|
|||
|
would cause OpenDoors to automatically send the appropriate
|
|||
|
file, according to the user's graphics mode settings. When the
|
|||
|
od_send_file() function is used in this "automatic mode" (where
|
|||
|
you do not specify a filename extension), it will look for one
|
|||
|
of the four filename extensions listed below.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 124
|
|||
|
|
|||
|
+----------------------------------------------------------+
|
|||
|
| Extension| File type |
|
|||
|
+----------+-----------------------------------------------|
|
|||
|
| .ASC | Does not require any graphics mode to display |
|
|||
|
| .ANS | Requires ANSI graphics mode to display |
|
|||
|
| .AVT | Requires AVATAR graphics mode to display |
|
|||
|
| .RIP | Requires RIP graphics mode to be displayed |
|
|||
|
+----------------------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
If the user has RIP graphics enabled, od_send_file() will first
|
|||
|
search for the .RIP file. If no file exists with the specified
|
|||
|
filename and a .RIP extension, od_send_file() will then search
|
|||
|
for .AVT, then .ANS, and if not found .ASC. If the user has only
|
|||
|
ANSI graphics enabled, od_send_file() will attempt first to
|
|||
|
display the .ANS file, and if not found will search for .ASC. In
|
|||
|
the case that the user is using plain-ASCII mode, this function
|
|||
|
will attempt only to display the .ASC file.
|
|||
|
|
|||
|
When displaying a .RIP file to the remote system, OpenDoors will
|
|||
|
attempt to locate and display a corresponding .AVT/.ANS/.ASC
|
|||
|
file on the local system. If no such file can be found, a window
|
|||
|
will be displayed, indicating the name of the .RIP file that is
|
|||
|
being sent to the remote system. When a .RIP file is being
|
|||
|
displayed, page pausing is disabled.
|
|||
|
|
|||
|
When displaying .AVT/.ANS/.ASC files, od_send_file() will send
|
|||
|
any ANSI or AVATAR codes in the file directly to the remote
|
|||
|
terminal, and interpret them to display on the local screen
|
|||
|
(regardless of the actual filename extension). This
|
|||
|
interpretation is accomplished by OpenDoor's built in terminal
|
|||
|
emulator. The terminal emulator fully supports all ANSI and
|
|||
|
AVATAR level 0 and level 0+ control codes. The terminal emulator
|
|||
|
will also translate Remote Access/QuickBBS style control codes,
|
|||
|
if enabled by setting od_control.od_no_ra_codes to FALSE. The
|
|||
|
control codes supported by OpenDoors are listed in the chart on
|
|||
|
the following pages. When these control codes are inserted into
|
|||
|
the file, OpenDoors will replace them with various pieces of
|
|||
|
user or system information.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 125
|
|||
|
|
|||
|
+-----------------------------------------------------+
|
|||
|
| CONTROL | ASCII | |
|
|||
|
| CODE | VALUE | DESCRIPTION |
|
|||
|
+---------+-------+-----------------------------------|
|
|||
|
| ^FA | 06,65 | Displays the user's full name |
|
|||
|
| ^FB | 06,66 | Location the user is calling from |
|
|||
|
| ^FC | 06,67 | Displays the user's password |
|
|||
|
| ^FD | 06,68 | Business/data phone number |
|
|||
|
| ^FE | 06,69 | Home/voice phone number |
|
|||
|
| ^FF | 06,70 | Date of the user's last call |
|
|||
|
| ^FG | 06,71 | Time of day of the last call |
|
|||
|
| ^FH | 06,72 | The user's `A' flags settings |
|
|||
|
| ^FI | 06,73 | The user's `B' flags settings |
|
|||
|
| ^FJ | 06,74 | The user's `C' flags settings |
|
|||
|
| ^FK | 06,75 | The user's `D' flags settings |
|
|||
|
| ^FL | 06,76 | User's remaining netmail credit |
|
|||
|
| ^FM | 06,77 | Number of messages posted by user |
|
|||
|
| ^FN | 06,78 | Last read message number by user |
|
|||
|
| ^FO | 06,79 | Displays security level of user |
|
|||
|
| ^FP | 06,80 | Number of times user has called |
|
|||
|
| ^FQ | 06,81 | Total # of uploads by user |
|
|||
|
| ^FR | 06,82 | Total KBytes uploaded by user |
|
|||
|
| ^FS | 06,83 | Total # of downloads by user |
|
|||
|
| ^FT | 06,84 | Total Kbytes downloaded by user |
|
|||
|
| ^FU | 06,85 | # of minute user has used today |
|
|||
|
| ^FV | 06,86 | User's screen length setting |
|
|||
|
| ^FW | 06,87 | User's first name only |
|
|||
|
| ^FX | 06,88 | User's ANSI setting |
|
|||
|
| ^FY | 06,89 | User's "continue?" prompt setting |
|
|||
|
| ^FZ | 06,90 | Does user have screen clearing on |
|
|||
|
| ^F0 | 06,48 | User's Full-screen editor setting |
|
|||
|
| ^F1 | 06,49 | User's Quiet mode setting |
|
|||
|
| ^F2 | 06,50 | User's hot-keys setting |
|
|||
|
| ^F3 | 06,51 | Displays the user's alias |
|
|||
|
| ^F4 | 06,52 | The date of the User's first call |
|
|||
|
| ^F5 | 06,53 | The user's date of birth |
|
|||
|
| ^F6 | 06,54 | User's subscription expiry date |
|
|||
|
| ^F7 | 06,55 | Number of days until expiry |
|
|||
|
| ^F8 | 06,56 | User's AVATAR setting |
|
|||
|
| ^F9 | 06,57 | The user's upload:download ratio |
|
|||
|
| ^F: | 06,58 | User's Upload K:download K ratio |
|
|||
|
+-----------------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 126
|
|||
|
|
|||
|
+-----------------------------------------------------+
|
|||
|
| CONTROL | ASCII | |
|
|||
|
| CODE | VALUE | DESCRIPTION |
|
|||
|
+---------+-------+-----------------------------------|
|
|||
|
| ^F; | 06,59 | Full-screen message reader |
|
|||
|
| ^KA | 11,65 | Total # of calls BBS has received |
|
|||
|
| ^KB | 11,66 | Name of the last caller to BBS |
|
|||
|
| ^KC | 11,67 | Total # of active messages on BBS |
|
|||
|
| ^KD | 11,68 | Displays # of the first message |
|
|||
|
| ^KE | 11,69 | Displays # of the last message |
|
|||
|
| ^KF | 11,70 | # of times user has paged sysop |
|
|||
|
| ^KG | 11,71 | Full name of the current weekday |
|
|||
|
| ^KH | 11,72 | Displays total number of users |
|
|||
|
| ^KI | 11,73 | Displays the current time |
|
|||
|
| ^KJ | 11,74 | Displays the current date |
|
|||
|
| ^KK | 11,75 | Minutes the user has been online |
|
|||
|
| ^KL | 11,76 | Seconds the user has been online |
|
|||
|
| ^KM | 11,77 | Minutes the user has used today |
|
|||
|
| ^KN | 11,78 | Seconds the user has used today |
|
|||
|
| ^KO | 11,79 | Minutes remaining for user today |
|
|||
|
| ^KP | 11,80 | Seconds remaining for user today |
|
|||
|
| ^KQ | 11,81 | The user's daily time limit |
|
|||
|
| ^KR | 11,82 | Displays the current baud rate |
|
|||
|
| ^KS | 11,83 | The current weekday in short-form |
|
|||
|
| ^KT | 11,84 | The user's daily download limit |
|
|||
|
| ^KU | 11,85 | # of minutes until the next event |
|
|||
|
| ^KV | 11,86 | Time of the next system event |
|
|||
|
| ^KW | 11,87 | # of node user is currently on |
|
|||
|
| ^KX | 11,88 | Disconnects the user |
|
|||
|
+-----------------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_disp_emu(), od_list_files(), od_hotkey_menu()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_send_file() function in
|
|||
|
displaying a custom door menu, see the EX_VOTE.C example
|
|||
|
program, which is described beginning on page 38.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 127
|
|||
|
|
|||
|
OD_SET_ATTRIB()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to change the text color in ANSI or AVATAR mode, using
|
|||
|
a single IBM-PC color attribute value.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_set_attrib(INT nColor);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION od_set_attrib() is one of two functions which change the color
|
|||
|
of the currently displayed text. This function allows you to set
|
|||
|
the text color using a single IBM-PC style color attribute. On
|
|||
|
the other hand, the od_set_color() function allows you to set
|
|||
|
the display color by specifying a foreground and background text
|
|||
|
color. Generally speaking, which of these two functions you use
|
|||
|
will be only a matter of personal preference. You will, however,
|
|||
|
most likely find it more convenient to use the od_set_color()
|
|||
|
function for changing display color. However the od_set_attrib()
|
|||
|
offers the advantage of allowing you to manipulate the color to
|
|||
|
be displayed as a single value, instead of two separate values.
|
|||
|
This could be convenient, for example, when displaying text in a
|
|||
|
user configured color. Using a single byte to represent the
|
|||
|
color will likely be easier than using two. An alternative
|
|||
|
method of setting the color of displayed text is to include the
|
|||
|
color codes within a string displayed by the od_printf()
|
|||
|
function. The benefits of doing this, along with instructions on
|
|||
|
how to do this, are described in the section on the od_printf()
|
|||
|
function, which begins on page 110.
|
|||
|
|
|||
|
This function will only have an effect if the user has ANSI,
|
|||
|
AVATAR or RIP modes enabled. As a result, you can use this
|
|||
|
function within your door program, and have your text
|
|||
|
automatically displayed in multiple colors if graphics mode is
|
|||
|
available, and displayed without colors if graphics mode is not
|
|||
|
available.
|
|||
|
|
|||
|
Note that the color to be set is passed to this function as an
|
|||
|
IBM-style screen attribute. Hence, you can set the color of text
|
|||
|
to be displayed by a single hexidecimal value, encoded as
|
|||
|
follows:
|
|||
|
|
|||
|
+------------- Background color
|
|||
|
|
|
|||
|
0x7f
|
|||
|
|
|
|||
|
+------------ Foreground color
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 128
|
|||
|
|
|||
|
Where the left digit (most significant nibble) of the
|
|||
|
hexidecimal number represents the background color, and the
|
|||
|
right digit (least significant nibble) represents the foreground
|
|||
|
color. Each of the possible colors, along with their
|
|||
|
corresponding hexidecimal values, are listed in the charts,
|
|||
|
below.
|
|||
|
|
|||
|
+-----------------------+ +--------------------------+
|
|||
|
| Foreground colors | | Background | Flashing |
|
|||
|
+-----------------------| +---------------+----------|
|
|||
|
| 0 | Black | | 0 | Black | Off |
|
|||
|
| 1 | Blue | | 1 | Blue | Off |
|
|||
|
| 2 | Green | | 2 | Green | Off |
|
|||
|
| 3 | Cyan | | 3 | Cyan | Off |
|
|||
|
| 4 | Red | | 4 | Red | Off |
|
|||
|
| 5 | Magenta | | 5 | Magenta | Off |
|
|||
|
| 6 | Brown | | 6 | Brown | Off |
|
|||
|
| 7 | White (grey) | | 7 | White | Off |
|
|||
|
| 8 | Bright Black | | 8 | Black | On |
|
|||
|
| 9 | Bright Blue | | 9 | Blue | On |
|
|||
|
| a | Bright Green | | a | Green | On |
|
|||
|
| b | Bright Cyan | | b | Cyan | On |
|
|||
|
| c | Bright Red | | c | Red | On |
|
|||
|
| d | Bright Magenta | | d | Magenta | On |
|
|||
|
| e | Yellow | | e | Brown | On |
|
|||
|
| f | White (bright) | | f | White | On |
|
|||
|
+-----------------------+ +--------------------------+
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_set_color(), od_disp_emu(), od_clr_scr(), od_clr_line(),
|
|||
|
od_set_cursor()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE At times, you may wish to allow the user to select the color of
|
|||
|
text they wish to have displayed, perhaps to configure your door
|
|||
|
for the ideal colors to be displayed on their system. To
|
|||
|
demonstrate the use of the od_set_attrib() function, we show
|
|||
|
another function, which shows the user all 256 possible colors
|
|||
|
that can be displayed, and allows the user to choose which color
|
|||
|
they prefer. The function will then return the color attribute
|
|||
|
value of the user's chosen color.
|
|||
|
|
|||
|
unsigned char choose_color(void)
|
|||
|
{
|
|||
|
register unsigned char counter; /* for displaying colors */
|
|||
|
char string[4]; /* string input by user */
|
|||
|
|
|||
|
od_set_attrib(0x07); /* display title */
|
|||
|
od_disp_str("Available colors:\n\r\n\r");
|
|||
|
|
|||
|
for(counter=0;counter<=255;) /* loop through all colors */
|
|||
|
{
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 129
|
|||
|
|
|||
|
od_set_attrib(counter); /* set appropriate color */
|
|||
|
od_printf("%03.3u",counter); /* display color's number */
|
|||
|
if(((++counter)%16)==0) /* after every 16 colors ... */
|
|||
|
{
|
|||
|
od_set_attrib(0x07); /* ... reset display color ... */
|
|||
|
od_disp_str("\n\r"); /* ... and start a new line */
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
od_set_attrib(0x07); /* Allow user to choose color */
|
|||
|
od_disp_str("Which color do you prefer : ");
|
|||
|
od_input_str(string,3,'0','9');
|
|||
|
return(atoi(string)); /* Return chosen color */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 130
|
|||
|
|
|||
|
OD_SET_COLOR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to change the current display color in ANSI, AVATAR or
|
|||
|
RIP modes, using foreground and background color values.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_set_color(INT nForeground, INT nBackground);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION od_set_color() is one of two functions which change the color of
|
|||
|
the currently displayed text. This function allows you to set
|
|||
|
the text color using separate foreground an background text
|
|||
|
colors, whereas od_set_attrib() allows you to set the text color
|
|||
|
using a single IBM-PC style color attribute. Generally speaking,
|
|||
|
which of these two functions you use is only a matter of
|
|||
|
personal preference. An alternative method of setting the color
|
|||
|
of displayed text is to include the color codes within a string
|
|||
|
displayed by the od_printf() function. The benefits of doing
|
|||
|
this, along with instructions on how to do this, are described
|
|||
|
in the section on the od_printf() function, which begins on page
|
|||
|
110.
|
|||
|
|
|||
|
This function will only have an effect if the user has ANSI,
|
|||
|
AVATAR or RIP mode turned on. As a result, you can use this
|
|||
|
function within your door program, and have your text
|
|||
|
automatically displayed in multiple colors if graphics mode is
|
|||
|
available, and displayed without colors if graphics mode is not
|
|||
|
available.
|
|||
|
|
|||
|
The od_set_color() function accepts two parameters, the first
|
|||
|
parameter being the foreground color to be used in displaying
|
|||
|
text, and the second parameter being the background color to be
|
|||
|
used in displaying text. For example,
|
|||
|
|
|||
|
od_set_color(L_WHITE,D_BLACK);
|
|||
|
|
|||
|
would set the current color to Light White on Dark Black. The
|
|||
|
foreground and background text colors can be any one of the
|
|||
|
color values listed on the following page.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 131
|
|||
|
|
|||
|
|
|||
|
|
|||
|
+-------------------+-----------+
|
|||
|
| Foreground Color | Value |
|
|||
|
+-------------------+-----------+
|
|||
|
| Dark Black | D_BLACK |
|
|||
|
| Dark Blue | D_BLUE |
|
|||
|
| Dark Green | D_GREEN |
|
|||
|
| Dark Cyan | D_CYAN |
|
|||
|
| Dark Red | D_RED |
|
|||
|
| Dark Magenta | D_MAGENTA |
|
|||
|
| Dark Brown | D_BROWN |
|
|||
|
| Grey (Dark White) | D_GREY |
|
|||
|
| Light Black (Grey)| L_BLACK |
|
|||
|
| Light Blue | L_BLUE |
|
|||
|
| Light Green | L_GREEN |
|
|||
|
| Light Cyan | L_CYAN |
|
|||
|
| Light Red | L_RED |
|
|||
|
| Light Magenta | L_MAGENTA |
|
|||
|
| Yellow | L_YELLOW |
|
|||
|
| White | L_WHITE |
|
|||
|
+-------------------+-----------+
|
|||
|
|
|||
|
|
|||
|
+-------------------+-----------+
|
|||
|
| Background Color | Value |
|
|||
|
+-------------------+-----------+
|
|||
|
| Black | D_BLACK |
|
|||
|
| Blue | D_BLUE |
|
|||
|
| Green | D_GREEN |
|
|||
|
| Cyan | D_CYAN |
|
|||
|
| Red | D_RED |
|
|||
|
| Magenta | D_MAGENTA |
|
|||
|
| Brown | D_BROWN |
|
|||
|
| Grey | D_GREY |
|
|||
|
| Blinking Black | B_BLACK |
|
|||
|
| Blinking Blue | B_BLUE |
|
|||
|
| Blinking Green | B_GREEN |
|
|||
|
| Blinking Cyan | B_CYAN |
|
|||
|
| Blinking Red | B_RED |
|
|||
|
| Blinking Magenta | B_MAGENTA |
|
|||
|
| Blinking Brown | B_BROWN |
|
|||
|
| Blinking Grey | B_WHITE |
|
|||
|
+-------------------+-----------+
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_set_attrib(), od_disp_emu(), od_clr_scr(), od_clr_line(),
|
|||
|
od_set_cursor()
|
|||
|
|
|||
|
EXAMPLE As an example of using the od_set_color() function to set the
|
|||
|
color of displayed text, we show a pair of two functions. These
|
|||
|
functions will allow a program to set the foreground OR
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 132
|
|||
|
|
|||
|
background color of text, without setting the other. In
|
|||
|
contrast, the od_set_color() function sets both the foreground
|
|||
|
and background color at the same time. These function presume
|
|||
|
that they are the only functions used within the door to set the
|
|||
|
color of displayed text, and that the original text color prior
|
|||
|
to calling either of these functions is dark white on black.
|
|||
|
These function must also have access to the two global variables
|
|||
|
"current_foreground" and "current_background", as defined below.
|
|||
|
|
|||
|
|
|||
|
void set_foreground(char foreground);
|
|||
|
void set_background(char background);
|
|||
|
unsigned char current_foreground=D_BLACK;
|
|||
|
unsigned char current_background=D_GREY;
|
|||
|
|
|||
|
void set_foreground(char foreground)
|
|||
|
{ /* set new text color */
|
|||
|
od_set_color(foreground, current_background);
|
|||
|
current_foreground=foreground; /* save new foreground */
|
|||
|
}
|
|||
|
|
|||
|
void set_background(char background)
|
|||
|
{ /* set new text color */
|
|||
|
od_set_color(current_foreground, background);
|
|||
|
current_background=background; /* save new background */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
Using these functions, you would then be able to set just the
|
|||
|
foreground text color by a function call like:
|
|||
|
|
|||
|
set_foreground(L_YELLOW);
|
|||
|
|
|||
|
Or set just the background text color by a function call like:
|
|||
|
|
|||
|
set_background(D_GREY);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 133
|
|||
|
|
|||
|
OD_SET_CURSOR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Function to reposition the text cursor in ANSI, AVATAR or RIP
|
|||
|
mode
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_set_cursor(INT nRow, INT nColumn);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function repositions the cursor to the specified row and
|
|||
|
column on the screen. nRow can have a value of 1 to 23, and
|
|||
|
nColumn can have a value of 1 to 80. ANSI, AVATAR or RIP mode
|
|||
|
must be active.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_disp_emu(), od_clr_scr(), od_clr_line(), od_set_color(),
|
|||
|
od_set_attrib()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below is a simple example that demonstrates the use of the
|
|||
|
od_set_cursor() function. Note that this example detects whether
|
|||
|
or not graphics mode is available, and if it is not, will carry
|
|||
|
out the same task without the use of od_set_cursor().
|
|||
|
|
|||
|
od_init(); /* Initialize door operations */
|
|||
|
od_clr_scr(); /* Clear the screen */
|
|||
|
if(od_control.user_ansi || od_control.user_avatar)
|
|||
|
{ /* If graphics mode is available */
|
|||
|
od_set_cursor(1,1); /* Display demo */
|
|||
|
od_disp_str("Top, Left Corner");
|
|||
|
|
|||
|
od_set_cursor(1,70);
|
|||
|
od_disp_str("Top, Right Corner");
|
|||
|
|
|||
|
od_set_cursor(15,1);
|
|||
|
od_disp_str("Fifteenth line\n\r");
|
|||
|
}
|
|||
|
else /* If graphics mode is not available */
|
|||
|
{ /* Display demo */
|
|||
|
od_disp_str("Top, Left Corner");
|
|||
|
od_repeat(' ', 54);
|
|||
|
od_disp_str("Top, Right Corner\n\r");
|
|||
|
od_disp_str("\n\n\n\n\n\n\n\n\n\n\n\n\n");
|
|||
|
od_disp_str("Fifteenth line\n\r");
|
|||
|
}
|
|||
|
od_get_key(TRUE); /* Wait for user to press key */
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 134
|
|||
|
|
|||
|
OD_SET_DTR()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Controls the DTR (Data Terminal Ready) signal to the modem. Used
|
|||
|
primarily to cause the modem to "hang up".
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_set_dtr(BOOL bHigh);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION In certain circumstances (such as call back verification doors),
|
|||
|
you may wish to "hang up" the modem without exiting your door
|
|||
|
program. This can be accomplished with most modems by
|
|||
|
controlling the DTR (Data Terminal Ready) signal to the modem.
|
|||
|
Passing a FALSE value to od_set_dtr() causes the DTR signal to
|
|||
|
be set low, and passing a TRUE value causes the DTR signal to be
|
|||
|
set high. Normally, OpenDoors maintains the DTR signal in its
|
|||
|
high state. Since most (but not all) modems are configured to
|
|||
|
disconnect from the remote modem when the DTR signal is set low,
|
|||
|
calling od_set_dtr(FALSE) can be used to hangup the modem. When
|
|||
|
hanging up by this method, you should be sure to set the DTR
|
|||
|
signal high again, after the carrier detect signal has
|
|||
|
disappeared. For more information on determining the state of
|
|||
|
the carrier detect signal, see the od_carrier() function, which
|
|||
|
is described on page 51. Note that not all modems will
|
|||
|
disconnect from the remote user in response to your lowering the
|
|||
|
DTR signal. If your software may be used with such modems, you
|
|||
|
may wish to also provide the option of disconnecting the modem
|
|||
|
by sending a "hang up" command sequence to the modem.
|
|||
|
|
|||
|
Since OpenDoors normally monitors the carrier detect signal, and
|
|||
|
exits when this signal disappears, you will have to disable
|
|||
|
OpenDoor's carrier detection if you wish your program to
|
|||
|
continue executing after hanging up the modem. OpenDoor's
|
|||
|
automatic carrier detection can be disabled using the
|
|||
|
od_control.od_disable OpenDoors control structure variable, as
|
|||
|
follows:
|
|||
|
|
|||
|
od_control.od_disable |= DIS_CARRIERDETECT;
|
|||
|
|
|||
|
SEE ALSO od_carrier(), od_exit()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of using the od_set_dtr() function to "hang up"
|
|||
|
the modem, see the example that accompanies the od_carrier()
|
|||
|
function, which is described on page 52.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 135
|
|||
|
|
|||
|
OD_SET_PERSONALITY()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Sets the current status line / sysop function key personality to
|
|||
|
be used.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_set_personality(char *pszName);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function changes the current status line / sysop function
|
|||
|
key personality. The pszName parameter should contain the string
|
|||
|
which uniquely identifies the personality to be set. This
|
|||
|
function may only be used by OpenDoors programs which include
|
|||
|
the OpenDoors "Multiple Personality System". To enable use of
|
|||
|
the MPS, include the following line before your first call to
|
|||
|
any OpenDoors function:
|
|||
|
|
|||
|
od_control.od_mps=INCLUDE_MPS;
|
|||
|
|
|||
|
OpenDoors includes a number of built-in personalities.
|
|||
|
Additional personalities may be added using the
|
|||
|
od_add_personality() function, which is described on page 47.
|
|||
|
The following personalities are included with this version of
|
|||
|
OpenDoors:
|
|||
|
|
|||
|
Name Description
|
|||
|
-----------------------------------------------------------
|
|||
|
Standard OpenDoors style, similar to RA 1.11
|
|||
|
PCBoard Similar to PC-Board
|
|||
|
RemoteAccess Similar to RemoteAccess 2.x
|
|||
|
Wildcat Similar to Wildcat!
|
|||
|
|
|||
|
Personality names are not case sensitive. For more information
|
|||
|
on the OpenDoors Multiple Personality System, see the section
|
|||
|
which begins on page 233.
|
|||
|
|
|||
|
This function returns TRUE on success, or FALSE on failure. In
|
|||
|
the case of a failure, the od_control.od_error variable is set
|
|||
|
to indicate the nature of the failure. For more information on
|
|||
|
the od_control.od_error variables, see page 185.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_add_personality(), od_set_statusline()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 136
|
|||
|
|
|||
|
OD_SET_STATUSLINE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE To set the currently displayed status line.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_set_statusline(INT nSetting);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION If you have the OpenDoors status line enabled within your door
|
|||
|
program (as is the default), the sysop will be able to control
|
|||
|
the setting of the status line using the F1 - F10 keys on the
|
|||
|
keyboard. These function keys are as follows:
|
|||
|
|
|||
|
[F1] - Display basic door and user information
|
|||
|
[F2] - Display phone numbers and important dates
|
|||
|
[F3] - Display security flags and up/download info
|
|||
|
[F4] - Display system information and current time
|
|||
|
[F5] - Display message info and user's settings
|
|||
|
[F6] - Display chat reason and sysop's comment
|
|||
|
[F9] - Display help information for sysop
|
|||
|
[F10] - Turn off the status line
|
|||
|
|
|||
|
Using the od_set_statusline() function, you can manually set
|
|||
|
which of these status line settings is currently selected. The
|
|||
|
od_set_statusline() accepts a single parameter, which should be
|
|||
|
one of the values listed below, which indicates which status
|
|||
|
line you would like to have selected:
|
|||
|
|
|||
|
+---------------+---------------+------------------------------+
|
|||
|
| | Corresponding | |
|
|||
|
| Value | Function Key | Meaning |
|
|||
|
+---------------+---------------+------------------------------+
|
|||
|
| STATUS_NORMAL | [F1] | Basic door and user info |
|
|||
|
| STATUS_NONE | [F10] | Turn off status line |
|
|||
|
| STATUS_HELP | [F9] | Displays help for the sysop |
|
|||
|
| STATUS_USER1 | [F2] | Phone Numbers and dates |
|
|||
|
| STATUS_USER2 | [F3] | Security flags & up/downloads|
|
|||
|
| STATUS_USER3 | [F5] | Message info & user settings |
|
|||
|
| STATUS_USER4 | [F6] | Chat reason and sysop comment|
|
|||
|
| STATUS_SYSTEM | [F4] | System info & current time |
|
|||
|
+---------------+---------------+------------------------------+
|
|||
|
(Note that these keys may be customized using variables in the
|
|||
|
OpenDoors control structure.)
|
|||
|
|
|||
|
Keep in mind that the od_set_statusline() function only
|
|||
|
temporarily changes the current status line setting, and that
|
|||
|
the sysop will still be able to change the status line to any of
|
|||
|
the other settings using the function keys. For instance, if you
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 137
|
|||
|
|
|||
|
wished to allow the sysop to normally see all 25 lines of text
|
|||
|
displayed by your door, but at the same time to still allow the
|
|||
|
sysop to turn on the status line at any time, you could place
|
|||
|
the line
|
|||
|
|
|||
|
od_set_statusline(STATUS_NONE);
|
|||
|
|
|||
|
at the beginning of your program. Similarly, when the user pages
|
|||
|
the sysop, OpenDoors itself calls
|
|||
|
|
|||
|
od_set_statusline(STATUS_USER4);
|
|||
|
|
|||
|
in order to display the status line which shows the user's
|
|||
|
reason for chat, while still allowing the sysop to switch back
|
|||
|
to any of the other status lines.
|
|||
|
|
|||
|
If you wish to permanently turn off the OpenDoor's status line,
|
|||
|
without allowing the sysop to be able to turn it back on using
|
|||
|
the sysop function keys, simply set the
|
|||
|
"od_control.od_status_on" variable to FALSE. This variable is
|
|||
|
described in the OpenDoors control structure section of this
|
|||
|
manual, which begins on page 148.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 138
|
|||
|
|
|||
|
OD_SLEEP()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Suspends program execution, yielding control to other tasks in a
|
|||
|
multitasking environment.
|
|||
|
|
|||
|
|
|||
|
FORMAT void od_sleep(tODMilliSec Milliseconds);
|
|||
|
|
|||
|
|
|||
|
RETURNS N/A
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION od_sleep() suspends execution of your program for the specified
|
|||
|
number of milliseconds. Note that under the DOS version of
|
|||
|
OpenDoors, this value is rounded to the nearest 55 milliseconds.
|
|||
|
While the program's execution is suspended, od_sleep() yields
|
|||
|
control of the processor to other tasks in a multitasking
|
|||
|
environment.
|
|||
|
|
|||
|
Calling od_sleep() with a sleep time of 0 causes control to be
|
|||
|
yielded to other waiting processes without imposing a minimum
|
|||
|
sleep time. If no other processes are waiting to execute, the
|
|||
|
function returns immediately. OpenDoors automatically calls
|
|||
|
od_sleep(0) itself in most of the situations where there is a
|
|||
|
need to do so. However, there may be circumstances under which
|
|||
|
od_sleep(0) can be used to improve performance. In particular,
|
|||
|
od_sleep(0) can be used to improve the performance of other
|
|||
|
applications that are also running at the same time as yours. By
|
|||
|
calling od_sleep(0), you are essentially telling the operating
|
|||
|
system that your program doesn't currently need all of the
|
|||
|
processing time that has been allocated to it. While appropriate
|
|||
|
use of od_sleep(0) can improve overall system performance,
|
|||
|
overusing od_sleep(0) can dramatically degrade the performance
|
|||
|
of your own program. The only way to determine the optimal use
|
|||
|
of od_sleep(0) is by trial and error.
|
|||
|
|
|||
|
The most common situation where you might want to use
|
|||
|
od_sleep(0) is when your program cannot do anything useful until
|
|||
|
you receive input from the user, but for some reason you cannot
|
|||
|
call od_get_key(TRUE). Rather than sitting in a tight loop,
|
|||
|
repeatedly checking where the user has pressed a key yet, it is
|
|||
|
better to call od_sleep(0) to let other tasks run for a while
|
|||
|
before checking again. OpenDoors calls od_sleep(0) itself under
|
|||
|
any of the following circumstances:
|
|||
|
|
|||
|
- When transmitting characters, if the outbound serial
|
|||
|
buffer is full, OpenDoors yields while waiting for some
|
|||
|
of the characters in the buffer to be sent.
|
|||
|
- During od_get_key(), if called with the wait parameter
|
|||
|
set to TRUE.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 139
|
|||
|
|
|||
|
- While waiting for input, during the execution of any of
|
|||
|
the following input functions: od_get_answer(),
|
|||
|
od_hotkey_menu() (after menu has been displayed),
|
|||
|
od_popup_menu(), od_edit_str(), od_input_str().
|
|||
|
- While pausing at the end of a screen during
|
|||
|
od_send_file(), od_list_files(), od_hotkey_menu().
|
|||
|
- During chat mode.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_kernel()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 140
|
|||
|
|
|||
|
OD_SPAWN()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE To facilitate easy execution of child tasks from doors.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_spawn(char *pszCommandLine);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success,
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function allows you to easily run other programs from
|
|||
|
within your door programs, such as external file transfer
|
|||
|
utilities, compression utilities, and so on.
|
|||
|
|
|||
|
This function will attempt to swap OpenDoors and your entire
|
|||
|
door to expanded memory or disk. OpenDoors swapping can be
|
|||
|
controlled by the OpenDoors control structure variables,
|
|||
|
od_swapping_disable, od_swapping_ems and od_swap_path. The
|
|||
|
od_spawn...() functions first attempt to swap OpenDoors to EMS
|
|||
|
memory. If enough EMS 3.2 or later memory is available, it will
|
|||
|
be used. If not, OpenDoors will swap to a disk file in the
|
|||
|
directory specified by the od_control.od_swap_path variable.
|
|||
|
|
|||
|
Unlike the other Turbo C(++) / Borland C++ library functions
|
|||
|
such as system() or spawnf(), this function will automatically
|
|||
|
store the door screen prior to executing the sub-program, and
|
|||
|
will restore the screen upon return. This function will also
|
|||
|
store the current drive and directory settings prior to
|
|||
|
executing the program, and restore them after the program has
|
|||
|
returned.
|
|||
|
|
|||
|
Normally, the user's time will continue to be decreased during
|
|||
|
the execution of the od_spawn() function. However, you can
|
|||
|
freeze the user's time during the spawn process by using the
|
|||
|
OpenDoors control structure variable od_spawn_freeze_time.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_spawnvpe()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE Below are a few examples of various uses of the od_spawn()
|
|||
|
function:
|
|||
|
|
|||
|
To run the command processor from within your door program, to
|
|||
|
allow the sysop access to the DOS shell, simply use the
|
|||
|
following line of code:
|
|||
|
|
|||
|
od_spawn(getenv("COMSPEC"));
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 141
|
|||
|
|
|||
|
The following function is an example of using the od_spawn()
|
|||
|
function to call DSZ, allowing the user to download a file. You
|
|||
|
pass the name of the file that you wish to send to the user.
|
|||
|
This function will then ask the user what transfer protocol they
|
|||
|
would like to use, generate the appropriate DSZ command line,
|
|||
|
and then transmit the file to the user. Note that in order to
|
|||
|
use a door which implements this function, the external file
|
|||
|
transfer program "DSZ" must be available in the current search
|
|||
|
path. As an alternative, you may want to allow the sysop to
|
|||
|
specify the location of the DSZ file from within a configuration
|
|||
|
program. If you wish to receive a file (allow the user to
|
|||
|
upload), instead of sending one, simply change the "s" in the
|
|||
|
command line to a "r".
|
|||
|
|
|||
|
char download(char *filename)
|
|||
|
{
|
|||
|
char commandline[80];/* string containing DSZ command line */
|
|||
|
char protocol; /* character representing chosen protocol */
|
|||
|
|
|||
|
/* display protocol menu */
|
|||
|
od_printf("Select File Transfer Protocol:\n\r");
|
|||
|
od_printf(" [X] XModem\n\r");
|
|||
|
od_printf(" [Y] YModem\n\r");
|
|||
|
od_printf(" [Z] ZModem\n\r");
|
|||
|
od_printf("or press [A] to abort transfer\n\r");
|
|||
|
|
|||
|
do /* loop until valid protocol has been chosen */
|
|||
|
{
|
|||
|
protocol=od_get_key(); /* get key */
|
|||
|
/* abort if [A] key is pressed */
|
|||
|
if(protocol=='a' || protocol=='A') return(FALSE);
|
|||
|
} while(protocol!='x' && protocol!='y' && protocol!='z' &&
|
|||
|
protocol!='X' && protocol!='Y' && protocol!='Z');
|
|||
|
|
|||
|
od_printf("Begin receiving file now or press [CTRL]-[X] to
|
|||
|
abort\n\r");
|
|||
|
/* generate DSZ command line */
|
|||
|
sprintf(commandline,"dsz port %d s%c %s",
|
|||
|
od_control.port+1,
|
|||
|
protocol,
|
|||
|
filename);
|
|||
|
|
|||
|
return(od_spawn(commandline)); /* spawn to DSZ */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 142
|
|||
|
|
|||
|
|
|||
|
OD_SPAWNVPE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE To facilitate easy execution of child tasks from doors. Allows
|
|||
|
specification of child's environment, returns errorlevel
|
|||
|
returned by child task, and searches path for the executable
|
|||
|
file.
|
|||
|
|
|||
|
|
|||
|
FORMAT INT16 od_spawnvpe(INT16 nModeFlag, char *pszPath,
|
|||
|
char *papszArg[], char *papszEnv[]);
|
|||
|
|
|||
|
|
|||
|
RETURNS -1 on failure
|
|||
|
errorlevel returned by child process on success
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function behaves very similarly to the od_spawn() function.
|
|||
|
Thus, to save space in the manual, I will not recapitulate what
|
|||
|
is already said in the description of the od_spawn() function.
|
|||
|
Instead, this description concentrates on the additional
|
|||
|
features available through the od_spawnvpe() function. If you
|
|||
|
are not already familiar with the od_spawn() function, take a
|
|||
|
moment now to review the description of that function.
|
|||
|
|
|||
|
The od_spawn() function (the OpenDoors "quick-spawn" function)
|
|||
|
is designed to be quick and easy to use, but does not have all
|
|||
|
of the features available in the od_spawnvpe() function. In
|
|||
|
addition to the features of the od_spawn() function, the
|
|||
|
od_spawnvpe() function also provides the following features:
|
|||
|
|
|||
|
- od_spawnvpe() will search the "path" for the file
|
|||
|
to be executed.
|
|||
|
|
|||
|
- od_spawnvpe() allows you to pass an altered
|
|||
|
environment to the child process.
|
|||
|
|
|||
|
- od_spawnvpe() returns the errorlevel returned by
|
|||
|
the child process.
|
|||
|
|
|||
|
The parameters passed to the od_spawnvpe() function are
|
|||
|
identical to those passed to the C spawnvpe() function. The
|
|||
|
first parameter should usually the be P_WAIT flag. The second
|
|||
|
parameter is the name of the child program to execute. If a full
|
|||
|
path to the child program is not specified, and the child
|
|||
|
program does not exist in the current directory, OpenDoors will
|
|||
|
search the directories listed by the PATH environment variable.
|
|||
|
Also, if the .EXE or .COM extension is not provide, OpenDoors
|
|||
|
will look first for a .COM file, and if not found, for a .EXE
|
|||
|
file. The third parameter is an array of arguments to pass to
|
|||
|
the child process, or NULL if no arguments are to be passed. The
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 143
|
|||
|
|
|||
|
fourth parameter is the environment to be passed to the child
|
|||
|
process, or NULL if the a copy of the current environment should
|
|||
|
be used.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_spawn()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_spawn...() functions, see
|
|||
|
the example accompanying the od_spawn() function. As a specific
|
|||
|
example of the od_spawnvpe function, consider the following code
|
|||
|
which executes the "TEST.EXE" program.
|
|||
|
|
|||
|
od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL);
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 144
|
|||
|
|
|||
|
OD_WINDOW_CREATE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Creates a popup window of the specified size and color, storing
|
|||
|
the contents of the screen "under" the window. The window can
|
|||
|
later be removed from the screen, restoring the original
|
|||
|
contents of the screen "under" the window, using the
|
|||
|
od_window_remove() function. Requires ANSI, AVATAR or RIP mode.
|
|||
|
|
|||
|
|
|||
|
FORMAT void *od_window_create(INT nLeft, INT nTop, INT nRight, INT
|
|||
|
nBottom,
|
|||
|
char *pszTitle, BYTE btBorderCol, BYTE btTitleCol,
|
|||
|
BYTE btInsideCol, INT nReserved);
|
|||
|
|
|||
|
|
|||
|
RETURNS Pointer to newly allocated window structure on success
|
|||
|
NULL on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION This function creates a pop-up window on the remote and local
|
|||
|
screens. The contents of the screen beneath the window are
|
|||
|
stored, to allow the window to later be removed from the screen
|
|||
|
using the od_window_remove() function. The window is drawn using
|
|||
|
the boarder characters defined in the already existing
|
|||
|
od_control.od_box_chars[] array. The boarder is displayed using
|
|||
|
the color attribute specified in btBorderCol. The working area
|
|||
|
of the window is created in the color specified in btInsideCol.
|
|||
|
A title may optionally be displayed on the window by specifying
|
|||
|
a string in pszTitle. This title will be displayed in the color
|
|||
|
specified by btTitleCol. If you do not wish a title to be
|
|||
|
displayed, pass an empty string or NULL pointer in pszTitle. On
|
|||
|
success, od_window_create() will return a pointer to a buffer
|
|||
|
which was allocated to store information on the window and the
|
|||
|
contents of the screen "under" the window. This pointer should
|
|||
|
at some point be passed in a call to od_window_remove().
|
|||
|
|
|||
|
This function requires ANSI, AVATAR or RIP graphics mode. If
|
|||
|
AVATAR mode is active, this function will take advantage of
|
|||
|
special AVATAR control sequences to display the window much
|
|||
|
faster than is possible in ANSI mode. In ANSI mode, window
|
|||
|
display will be slightly faster if btBorderCol and btTitleCol
|
|||
|
are equal. Note that the nReserved parameter of this function is
|
|||
|
not currently used. To preserve compatibility with future
|
|||
|
versions of OpenDoors, this parameter should always be set to 0.
|
|||
|
Currently, the size of the buffer allocated to store the window
|
|||
|
information will be (length*width*2) + 4 bytes in size.
|
|||
|
|
|||
|
If od_window_create() fails for any reason, a value of NULL is
|
|||
|
returned, and the od_control.od_error variable is set to
|
|||
|
indicate the reason for the failure. For more information on the
|
|||
|
od_control.od_error variable, see page 185.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 145
|
|||
|
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_window_remove(), od_draw_box(), od_gettext(), od_puttext(),
|
|||
|
od_save_screen(), od_restore_screen(), od_scroll()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_window_create() function,
|
|||
|
see the included ex_chat.c example program.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 146
|
|||
|
|
|||
|
OD_WINDOW_REMOVE()
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
PURPOSE Removes a window previously created using od_window_create(),
|
|||
|
restoring the original screen background.
|
|||
|
|
|||
|
|
|||
|
FORMAT BOOL od_window_remove(void *pWinInfo);
|
|||
|
|
|||
|
|
|||
|
RETURNS TRUE on success
|
|||
|
FALSE on failure
|
|||
|
|
|||
|
|
|||
|
DESCRIPTION The od_window_remove() function removes a window from the screen
|
|||
|
which was previously created by od_window_create(), and
|
|||
|
deallocates the memory which was allocated to store the window
|
|||
|
information. The contents of the screen beneath the window is
|
|||
|
restored to appear as it did prior to the call to
|
|||
|
od_window_create(). pWinInfo must point to the value returned by
|
|||
|
od_window_create().
|
|||
|
|
|||
|
Note that overlapping windows must be removed in the reverse
|
|||
|
order from which they were created for proper display results.
|
|||
|
The last window to be created must be the first window to be
|
|||
|
removed.
|
|||
|
|
|||
|
If od_window_remove() fails for any reason, a value of FALSE is
|
|||
|
returned, and the od_control.od_error variable is set to
|
|||
|
indicate the reason for the failure. For more information on the
|
|||
|
od_control.od_error variable, see page 185.
|
|||
|
|
|||
|
|
|||
|
SEE ALSO od_window_create(), od_draw_box(), od_gettext(), od_puttext(),
|
|||
|
od_save_screen(), od_restore_screen(), od_scroll()
|
|||
|
|
|||
|
|
|||
|
EXAMPLE For an example of the use of the od_window_remove() function,
|
|||
|
see the included ex_chat.c example program.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 147
|
|||
|
|
|||
|
555555
|
|||
|
55
|
|||
|
55
|
|||
|
55555
|
|||
|
55
|
|||
|
55
|
|||
|
55555
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
INTRODUCTION TO THE CONTROL STRUCTURE
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors "Control Structure" is used by OpenDoors in order
|
|||
|
to provide you with a wide range of information about the system
|
|||
|
on which you door is running, and the user who is currently
|
|||
|
using the door, along with providing you a means by which to
|
|||
|
customize much of OpenDoor's behavior. Using the OpenDoors
|
|||
|
control structure, you can access or alter information about the
|
|||
|
user who is online, information about the system on which your
|
|||
|
door is running, and information about OpenDoors itself. You can
|
|||
|
also use the control structure to customize all of the text
|
|||
|
displayed by OpenDoors, the function keys to which it responds,
|
|||
|
and many other aspects of OpenDoor's behavior.
|
|||
|
|
|||
|
The OpenDoors control structure is quite simply a normal C
|
|||
|
"struct", named od_control, and is defined in the OPENDOOR.H
|
|||
|
file. This "struct" contains many different variables, which
|
|||
|
provide you access to the information provided by the control
|
|||
|
structure. Hence, to access the contents of a control structure
|
|||
|
variable, for example the variable "system_name" which contains
|
|||
|
the name of the BBS the door is running under, you would use:
|
|||
|
|
|||
|
od_control.system_name
|
|||
|
|
|||
|
The following section of this chapter contains a complete
|
|||
|
reference to all of the variables which make up the OpenDoors
|
|||
|
control structure. This reference includes the name, type and
|
|||
|
complete description of the use of each variable. The reference
|
|||
|
is divided into the following categories of variables, with the
|
|||
|
reference to the variables in each section beginning on the
|
|||
|
listed page.
|
|||
|
|
|||
|
Door Information File Statistics..................150
|
|||
|
Modem Settings....................................153
|
|||
|
BBS and Caller Information........................158
|
|||
|
Door Settings.....................................182
|
|||
|
OpenDoors Behavior Customization..................187
|
|||
|
Function Keys Customization.......................212
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 148
|
|||
|
|
|||
|
Color Customization...............................237
|
|||
|
Text Customization................................217
|
|||
|
|
|||
|
Within each section, variables are listed alphabetically by
|
|||
|
name.
|
|||
|
|
|||
|
Also, in order to make use of some of the variables in the
|
|||
|
OpenDoors control structure, it is important to understand the
|
|||
|
concepts of Boolean (TRUE/FALSE), and bit-mapped flag variables.
|
|||
|
If you are not familiar with these two terms, they are described
|
|||
|
in detail in the glossary, located towards the end of this
|
|||
|
manual.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 149
|
|||
|
|
|||
|
CONTROL STRUCTURE - DOOR INFO FILE STATS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The following OpenDoors control structure variables provide your
|
|||
|
program with information concerning the door information file
|
|||
|
from which OpenDoors obtained the BBS and caller information
|
|||
|
that is found elsewhere in the control structure. The following
|
|||
|
control structure items are listed in this section:
|
|||
|
|
|||
|
info_path Sets the location and, optionally, the
|
|||
|
name of the door information file
|
|||
|
|
|||
|
od_info_type Type of door information file that was
|
|||
|
found
|
|||
|
|
|||
|
od_node Node number the door is running under
|
|||
|
|
|||
|
user_timeofcreation The time at which the door information
|
|||
|
file was created
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
info_path char od_control.info_path[60];
|
|||
|
|
|||
|
If used, this variable should be set prior to calling od_init()
|
|||
|
or any other OpenDoors function. This variable allows you to
|
|||
|
control where OpenDoors will look for the door information (drop
|
|||
|
file). By default, OpenDoors searches for the door information
|
|||
|
file in the current directory. If this variable is set to the
|
|||
|
name of some other directory, OpenDoors will first search for
|
|||
|
any door information files in that directory. If you only wish
|
|||
|
OpenDoors to look for a particular type of door information file
|
|||
|
(for instance, you want OpenDoors to only read a DORINFO1.DEF,
|
|||
|
and ignore any DOOR.SYS file), you can specify the full path and
|
|||
|
filename of the file you wish OpenDoors to use.
|
|||
|
|
|||
|
It is usually a good idea to design your door to allow the
|
|||
|
system operator to set the location of the door information
|
|||
|
file. This will allow the sysop to place your door in its own
|
|||
|
directory, and will facilitate the use of your door on multi-
|
|||
|
line BBS systems. If you are using the OpenDoors configuration
|
|||
|
file system, then the system operator can set the door
|
|||
|
information file location and/or name using the BBSDir keyword.
|
|||
|
However, you may also wish to allow the location of the door
|
|||
|
information file to be set on the command line. The following
|
|||
|
example illustrates a method of reading and setting the location
|
|||
|
of the door information file from the door's command line:
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 150
|
|||
|
|
|||
|
main(int argc, char *argv[])
|
|||
|
{
|
|||
|
if(argc>1) strncpy(od_control.info_path,argv[1],59);
|
|||
|
|
|||
|
od_disp_str("This is a sample OpenDoors door.\n\r");
|
|||
|
od_disp_str("Press any key to continue...\n\r");
|
|||
|
od_get_key(TRUE);
|
|||
|
od_exit(20);
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_info_type char od_control.od_info_type;
|
|||
|
|
|||
|
This variable indicates the type of information file from which
|
|||
|
OpenDoors has obtained the BBS and caller information that is
|
|||
|
found elsewhere in the OpenDoors control structure. This
|
|||
|
variable will have one of the following values, indicating that
|
|||
|
the door information file was of the corresponding type:
|
|||
|
|
|||
|
+----------------+----------------------------+
|
|||
|
| od_info_type | Door Information File Type |
|
|||
|
| Value | |
|
|||
|
+----------------+----------------------------+
|
|||
|
| DORINFO1 | DORINFO?.DEF |
|
|||
|
| EXITINFO | EXITINFO.BBS (Normal) |
|
|||
|
| RA1EXITINFO | EXITINFO.BBS (Extended) |
|
|||
|
| RA2EXITINFO | EXITINFO.BBS (RA 2.x) |
|
|||
|
| QBBS275EXITINFO| EXITINFO.BBS (QuickBBS) |
|
|||
|
| CHAINTXT | CHAIN.TXT |
|
|||
|
| SFDOORSDAT | SFDOORS.DAT |
|
|||
|
| CALLINFO | CALLINFO.BBS |
|
|||
|
| DOORSYS_GAP | DOOR.SYS (GAP/PC-Board) |
|
|||
|
| DOORSYS_DRWY | DOOR.SYS (Doorway style) |
|
|||
|
| DOORSYS_WILDCAT| DOOR.SYS (WildCat standard)|
|
|||
|
| CUSTOM | Custom door information |
|
|||
|
| | file, defined in config |
|
|||
|
| | file. |
|
|||
|
| NO_DOOR_FILE | No drop file was found. |
|
|||
|
+----------------+----------------------------+
|
|||
|
|
|||
|
The value of this variable is only valid AFTER od_init() or some
|
|||
|
OpenDoors function has been called.
|
|||
|
|
|||
|
Note that this variable should be treated as a read-only
|
|||
|
variable, and should not normally be altered by your program.
|
|||
|
Altering this variable may cause OpenDoors to re-write a
|
|||
|
different type of door information file upon exiting, than was
|
|||
|
read upon startup.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 151
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_node char od_control.od_node;
|
|||
|
|
|||
|
This variable indicates the node number that the door is running
|
|||
|
under. If this information is supplied by the BBS in the door
|
|||
|
information file, the node number will be automatically by
|
|||
|
OpenDoors. Specifically, the node number can be determined
|
|||
|
automatically from systems that produce an SFDOORS.DAT, PC-
|
|||
|
Board/GAP style DOOR.SYS or Wildcat style DOOR.SYS door
|
|||
|
information file. If this information is not supplied in the
|
|||
|
door information file, but is provided by the sysop in the
|
|||
|
door's configuration file, OpenDoors will use the value found
|
|||
|
there. Alternatively, you can set this variable manually.
|
|||
|
|
|||
|
On systems that produce a DORINFO?.DEF file, OpenDoors will use
|
|||
|
this variable to determine which DORINFO?.DEF file to search
|
|||
|
for. For instance, if od_control.od_node is set to 3, OpenDoors
|
|||
|
will first search for a DORINFO3.DEF file. If this file is not
|
|||
|
found, OpenDoors will then default to the DORINFO1.DEF filename.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_timeofcreation[6];
|
|||
|
_timeof
|
|||
|
creation This variable contains the time of day at which the door
|
|||
|
information file was created. This variable is available only
|
|||
|
when the door is running under a system that produces an
|
|||
|
EXITINFO.BBS file. To determine what type of door information
|
|||
|
file your door is running under, see the od_control.od_info_type
|
|||
|
variable, below.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 152
|
|||
|
|
|||
|
CONTROL STRUCTURE - SERIAL PORT SETTINGS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The following OpenDoors control structure items store the
|
|||
|
communications settings that OpenDoors uses to communicate with
|
|||
|
the modem. These values are normally set upon the first call to
|
|||
|
an OpenDoors function, during the od_init() procedure. However,
|
|||
|
you may need to manual set this variables if:
|
|||
|
|
|||
|
- you wish to allow greater configurability of your door
|
|||
|
- you are reading the door information file yourself
|
|||
|
- you are using the OpenDoors to write a non-door
|
|||
|
program
|
|||
|
|
|||
|
Some of these variables are always used by OpenDoors, while
|
|||
|
others are only relevant if OpenDoor's built-in serial
|
|||
|
communications code is being used instead of a FOSSIL driver.
|
|||
|
Those that are only used when no FOSSIL driver is present are
|
|||
|
denoted by an [*] in the list below.
|
|||
|
|
|||
|
The control structure variables controlling OpenDoor's serial
|
|||
|
port settings are as follows:
|
|||
|
|
|||
|
od_control.baud Serial Port BPS rate
|
|||
|
|
|||
|
od_control.od_connect_sppedThe modem connection BPS rate
|
|||
|
|
|||
|
od_control.od_com_address Serial Port address [*]
|
|||
|
|
|||
|
" " .od_com_fifo_trigger 16550A FIFO trigger size
|
|||
|
|
|||
|
" " .od_com_flow_control Type of flow control to use.
|
|||
|
|
|||
|
od_control.od_com_irq Serial Port IRQ number [*}
|
|||
|
|
|||
|
od_control.od_com_method Is FOSSIL or built-in serial I/O
|
|||
|
being used
|
|||
|
|
|||
|
od_control.od_com_no_fifo Disables use of 16550A FIFOs [*]
|
|||
|
|
|||
|
od_control.od_com_rx_buf Size of receive buffer [*]
|
|||
|
|
|||
|
od_control.od_com_tx_buf Size of transmit buffer [*]
|
|||
|
|
|||
|
od_control.od_no_fossil Prevents OpenDoors from using a
|
|||
|
FOSSIL driver, even if one is
|
|||
|
available.
|
|||
|
|
|||
|
od_control.od_open_handle Allows a live serial port handle to
|
|||
|
be passed to OpenDoors.
|
|||
|
|
|||
|
od_control.port Serial port number, 0 based.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 153
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
baud unsigned long od_control.baud;
|
|||
|
|
|||
|
This variable contains the BPS rate at which the computer is
|
|||
|
communicating with the modem, not to be confused with the BPS
|
|||
|
rate at which the local modem is communicating with the remote
|
|||
|
modem.
|
|||
|
|
|||
|
A value of 0 indicates that the program is operating in local
|
|||
|
mode.
|
|||
|
|
|||
|
If a FOSSIL driver is being used for serial I/O, this value is
|
|||
|
ignored if it does not correspond to one of the baud rates that
|
|||
|
an application can directly set a FOSSIL driver to. The BPS
|
|||
|
rates recognized by FOSSIL drivers are: 300, 600, 1200, 2400,
|
|||
|
4800, 9600, 19200, 38400. If any other BPS rate is to be used,
|
|||
|
the FOSSIL driver must be locked at that BPS from the FOSSIL
|
|||
|
driver command-line. When locked, FOSSIL drivers ignore any
|
|||
|
attempt by an application to change the BPS rate of the locked
|
|||
|
port. For this reason, the od_control.baud setting has no effect
|
|||
|
on the FOSSIL driver if it is locked.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ int od_control.od_com_address;
|
|||
|
address
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the serial port address can be set from the FOSSIL driver
|
|||
|
command line).
|
|||
|
|
|||
|
This variable may optionally be set to specify the base address
|
|||
|
of the serial port to be used. For ports COM1: through COM4:,
|
|||
|
OpenDoors can normally determine the serial port address
|
|||
|
automatically. However, for other serial ports, the port address
|
|||
|
must be specified using this variable. If you are not specifying
|
|||
|
a serial port address with this variable, do not change it's
|
|||
|
default value of 0.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ char od_control.od_com_fifo_trigger;
|
|||
|
fifo_trigger
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the IRQ line can be set from the FOSSIL driver command
|
|||
|
line).
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 154
|
|||
|
|
|||
|
|
|||
|
This variable sets the number of bytes that will be placed in
|
|||
|
the 16550A UART FIFO buffers before an interrupt is triggered,
|
|||
|
if the 16550A UART FIFOs are used. Valid values are 1, 4, 8 and
|
|||
|
14.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ unsigned char od_control.od_com_flow_control;
|
|||
|
flow_control
|
|||
|
This variable sets the type of serial I/O flow control to use.
|
|||
|
By default, this variable is set to COM_DEFAULT_FLOW, which
|
|||
|
specifies the default mode of flow control. Most often, this
|
|||
|
will be RTS/CTS flow control. A value of COM_RTSCTS_FLOW
|
|||
|
explicitly enables RTS/CTS flow control. A value of COM_NO_FLOW
|
|||
|
disables all flow control. If you are going to change the value
|
|||
|
of this variable, it should be set prior to your first call to
|
|||
|
any OpenDoors function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ unsigned char od_control.od_com_irq;
|
|||
|
irq
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the IRQ line can be set from the FOSSIL driver command
|
|||
|
line).
|
|||
|
|
|||
|
This variable may optionally be set to specify the IRQ line to
|
|||
|
be used for the serial port. By default, OpenDoors uses the
|
|||
|
normal IRQ 4 line for ports COM1: and COM3:, and IRQ 3 for ports
|
|||
|
COM2: and COM4:. To override this default, the IRQ line can be
|
|||
|
set using this variable. If you are not specifying an IRQ line
|
|||
|
with this variable, do not change it's default value of 0.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ char od_control.od_com_method;
|
|||
|
method
|
|||
|
This read-only variable reports the method that OpenDoors is
|
|||
|
using for serial I/O. This variable is set during od_init() or
|
|||
|
the first call to an OpenDoors function. This variable can be
|
|||
|
one of the following values:
|
|||
|
|
|||
|
COM_FOSSIL - Indicates that a FOSSIL driver is being
|
|||
|
used
|
|||
|
COM_INTERNAL - Indicates that OpenDoor's internal serial I/O
|
|||
|
code is being used.
|
|||
|
COM_WIN32 - Indicates that the Win32 communication system
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 155
|
|||
|
|
|||
|
is being used.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ char od_control.od_com_no_fifo;
|
|||
|
no_fifo
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the receive buffer size can be set from the FOSSIL driver
|
|||
|
command line).
|
|||
|
|
|||
|
Normally, OpenDoors will use a 16550A FIFO buffer if a 16550A
|
|||
|
UART is installed. You can disable the use of the 16550A FIFO
|
|||
|
buffer by setting this variable to TRUE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ unsigned int od_control.od_com_rx_buf;
|
|||
|
rx_buf
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the receive buffer size can be set from the FOSSIL driver
|
|||
|
command line).
|
|||
|
|
|||
|
This variable allows you to set the size of OpenDoor's serial
|
|||
|
I/O receive buffer. If you do not set this buffer size, a
|
|||
|
default value of 256 characters is used. Normally, this buffer
|
|||
|
size is more than large enough for door programs. However, if
|
|||
|
you find that inbound characters are lost before they can be
|
|||
|
processed by your program, you may wish to increase the size of
|
|||
|
this buffer.
|
|||
|
|
|||
|
This variable should only be changed before your first call to
|
|||
|
od_init() or any other OpenDoors function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_com_ unsigned int od_control.od_com_tx_buf;
|
|||
|
tx_buf
|
|||
|
This variable is only used when OpenDoors is NOT performing
|
|||
|
serial I/O using a FOSSIL driver. (When a FOSSIL driver is being
|
|||
|
used, the receive buffer size can be set from the FOSSIL driver
|
|||
|
command line).
|
|||
|
|
|||
|
This variable allows you to set the size of OpenDoor's serial
|
|||
|
I/O transmit buffer. If you do not set this buffer size, a
|
|||
|
default value of 1024 characters is used.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 156
|
|||
|
|
|||
|
This variable should only be changed before your first call to
|
|||
|
od_init() or any other OpenDoors function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_connect_ DWORD od_control.od_connect_speed;
|
|||
|
speed
|
|||
|
This variable contains the best guess at the current modem
|
|||
|
connection speed. This information is currently only accurate if
|
|||
|
a DOOR.SYS file is being used. In other situations, it will
|
|||
|
always be set to be equal to od_control.baud.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_open_ DWORD od_control.od_open_handle;
|
|||
|
handle
|
|||
|
Under platforms where this is supported (currently only the
|
|||
|
Win32 version of OpenDoors), this variable can be used to pass a
|
|||
|
live serial port handle to OpenDoors, which OpenDoors will use.
|
|||
|
OpenDoors will not close this handle when it exits. If this
|
|||
|
value is set to 0, OpenDoors will open and close the serial port
|
|||
|
itself.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
port char od_control.port;
|
|||
|
|
|||
|
This variable contains the serial port number that the modem is
|
|||
|
connected. This number is 0 based, so that a value of 0
|
|||
|
corresponds to COM1:, a value of 1 corresponds to COM2:, and so
|
|||
|
on. This value will normally be set by the od_init() function,
|
|||
|
when the door information file is read, and should not be
|
|||
|
changed after modem initialization has been carried out by the
|
|||
|
od_init() function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 157
|
|||
|
|
|||
|
CONTROL STRUCTURE - BBS AND CALLER INFORMATION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
As we have already described, there are two types of variables
|
|||
|
in the OpenDoors control structure. Some of the variables are
|
|||
|
simply used to allow you to customize OpenDoor's various
|
|||
|
features, such as altering colors, prompts, timeouts, etc. Other
|
|||
|
variables in the OpenDoors control structure serve to provide
|
|||
|
you with information about the user who is online and the BBS
|
|||
|
system your door is running under. This section deals with those
|
|||
|
variables that provide you with information about the BBS and
|
|||
|
the user.
|
|||
|
|
|||
|
The information in these variables is read from the door
|
|||
|
information file, a small file created by the BBS specifically
|
|||
|
for the purpose of communicating with door programs. Depending
|
|||
|
on what BBS system your door is running under, the type of door
|
|||
|
information file will vary. Since different door information
|
|||
|
files do not all provide the same pieces of information, some
|
|||
|
variables in this section will only be available when your door
|
|||
|
is running under particular BBS systems. Other variables will
|
|||
|
be available with many or all BBS systems. In the description of
|
|||
|
each variable in this section, we indicate under which door
|
|||
|
information files the particular variable will be . So, if you
|
|||
|
wish to access a variable that is only under certain door
|
|||
|
information files, your program should test whether or not the
|
|||
|
required information is available under the particular door
|
|||
|
information file that was found. In order to determine which
|
|||
|
door information file your door is running under, you should use
|
|||
|
the od_control.od_info_type variable. This variable is described
|
|||
|
in the section which begins on page 150. If you test the value
|
|||
|
of the od_control.od_info_type variable, and find that the
|
|||
|
required information is not available, you may wish to simply
|
|||
|
use some sort of default value for the variable, or
|
|||
|
alternatively, not allow your door to run under certain BBS
|
|||
|
systems. Another possibility, if the required information is not
|
|||
|
available, is imply to obtain this information from the user
|
|||
|
yourself. For example, if you wished to know the length of the
|
|||
|
user's screen, when this information is not available from the
|
|||
|
door information file, you could simply prompt the user for
|
|||
|
their screen length the first time they use your door. This
|
|||
|
information could then be stored in your door's data files for
|
|||
|
future reference.
|
|||
|
|
|||
|
As an example of testing what door information file your door is
|
|||
|
running under, consider the case where you wanted to display the
|
|||
|
user's birthday. The example below will display the user's
|
|||
|
birthday if it is known, and otherwise, print the string
|
|||
|
"unknown".
|
|||
|
|
|||
|
if(od_control.od_info_type == RA1EXITINFO
|
|||
|
od_control.od_info_type == RA2EXITINFO)
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 158
|
|||
|
|
|||
|
{
|
|||
|
od_disp_str(od_control.user_birthday);
|
|||
|
}
|
|||
|
else
|
|||
|
{
|
|||
|
od_disp_str("Unknown");
|
|||
|
}
|
|||
|
|
|||
|
The chart below lists the door information file formats that
|
|||
|
OpenDoors recognizes, along with example BBS systems that
|
|||
|
produce these files and a reference letter for each type. Thus,
|
|||
|
an OpenDoors door can run DIRECTLY under ANY BBS SYSTEM that
|
|||
|
produces one of these files formats, and under ANY OTHER BBS
|
|||
|
system when used in conjunction with a door information file
|
|||
|
conversion utility.
|
|||
|
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| FILE FORMAT | EXAMPLE BBS SYSTEMS |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| CHAIN.TXT | WWIV |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DORINFO1.DEF | RBBS-PC |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DORINFO1.DEF | QuickBBS |
|
|||
|
| & | Remote Access (versions 0.01-0.04) |
|
|||
|
| EXITINFO.BBS (Std. Ver.) | |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DOOR.SYS (DoorWay Style) | Remote Access |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DOOR.SYS (PCB/GAP Style) | PC-Board |
|
|||
|
| | GAP |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DOOR.SYS (WildCat Style) | Wildcat 3.00 and above |
|
|||
|
| | Telegard |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| SFDOORS.DAT | Spitfire |
|
|||
|
| | TriBBS |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| CALLINFO.BBS | WildCat 2.xx |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
| DORINFO1.DEF | Remote Access (versions 1.00 and later)|
|
|||
|
| & | |
|
|||
|
| EXITINFO.BBS (Ext. Ver.) | |
|
|||
|
+--------------------------+----------------------------------------+
|
|||
|
|
|||
|
|
|||
|
|
|||
|
The chart on the following page lists all of the OpenDoors
|
|||
|
control structure variables in this section, along with a brief
|
|||
|
description of their use. The variables are then described in
|
|||
|
detail, below.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 159
|
|||
|
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
| VARIABLE NAME | VARIABLE CONTENTS |
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
| EMSI INFORMATION | Information on current IEMSI session |
|
|||
|
| event_status | The status of the next system event |
|
|||
|
| event_starttime | The start time of the next system event |
|
|||
|
| event_errorlevel | The errorlevel of the next system event |
|
|||
|
| event_days | The days of the week to execute the event |
|
|||
|
| event_force | Whether the next system event is forced |
|
|||
|
| event_last_run | When the next system event was last run |
|
|||
|
| sysop_name | The name of the BBS's sysop |
|
|||
|
| system_calls | Total number of calls BBS has received |
|
|||
|
| system_last_caller | The name of the last caller to the BBS |
|
|||
|
| system_last_handle | The handle (alias) of the last caller |
|
|||
|
| system_name | The name of the BBS |
|
|||
|
| TIMELOG VARIABLES | The times at which the BBS has been most busy |
|
|||
|
| user_ansi | Whether the user has ANSI graphics mode on |
|
|||
|
| user_attribute | User attribute bit-mapped flags |
|
|||
|
| user_attrib2 | Second set of user attribute bit-mapped flags |
|
|||
|
| user_attrib3 | Third set of user attribute flags |
|
|||
|
| user_avatar | Whether the user has AVATAR graphics mode on |
|
|||
|
| user_birthday | The date the user was born |
|
|||
|
| user_callsign | The user's amateur radio call sign |
|
|||
|
| user_combinedrecord | The user's combined message areas settings |
|
|||
|
| user_comment | Sysop's comment about the user |
|
|||
|
| user_credit | Amount of NetMail credit the user has |
|
|||
|
| user_dataphone | The user's data phone number |
|
|||
|
| user_date_format | Format user wishes to have dates displayed in |
|
|||
|
| user_deducted_time | Total time that has been subtracted from user |
|
|||
|
| user_downk | Total Kilobytes downloaded by the user |
|
|||
|
| user_downlimit | User's daily download limit |
|
|||
|
| user_downloads | Total number of files downloaded by the user |
|
|||
|
| user_echomailentered | Whether or not the user has entered EchoMail |
|
|||
|
| user_error_free | Whether or not connection is error-free |
|
|||
|
| user_file_area | The user's current file area |
|
|||
|
| user_firstcall | Date of the user's first call to the BBS |
|
|||
|
| user_flags | User's sysop-defined flag settings |
|
|||
|
| user_forward_to | Name to forward user's mail to |
|
|||
|
| user_group | User's group number |
|
|||
|
| user_handle | User's alias |
|
|||
|
| user_homephone | User's home telephone number |
|
|||
|
| user_language | User's language setting |
|
|||
|
| user_last_pwdchange | Total calls since last password change |
|
|||
|
| user_lastdate | Date of the user's last call |
|
|||
|
| user_lastread | Highest message number read by user |
|
|||
|
| user_lasttime | Time of the user's last call |
|
|||
|
| user_location | Name of the city where the user lives |
|
|||
|
| user_logindate | Date on which the current call began |
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 160
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
| VARIABLE NAME | VARIABLE CONTENTS |
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
| user_loginsec | User's security at the beginning of this call |
|
|||
|
| user_logintime | Time at which the current call began |
|
|||
|
| user_logonpassword | User's password at the beginning of this call |
|
|||
|
| user_menustack | Contents of the user's current menu stack |
|
|||
|
| user_menustackpointer | Pointer to the top of the menu stack |
|
|||
|
| user_messages | Total number of messages written by the user |
|
|||
|
| user_msg_area | The user's current message area |
|
|||
|
| user_name | The user's name |
|
|||
|
| user_net_credit | The user's remaining netmail credit |
|
|||
|
| user_netmailentered | Whether or not the user has entered NetMail |
|
|||
|
| user_num | The user's record number in the user file |
|
|||
|
| user_numcalls | Number of calls the user has made to the BBS |
|
|||
|
| user_numpages | Number of times the user has paged the sysop |
|
|||
|
| user_password | The user's current password |
|
|||
|
| user_pending | The value of unsent NetMail written by user |
|
|||
|
| user_reasonforchat | The reason the user wishes to chat with sysop |
|
|||
|
| user_rip_ver | RIP protocol version being used |
|
|||
|
| user_screen_length | The length of the user's screen |
|
|||
|
| user_screenwidth | The width of the user's screen |
|
|||
|
| user_security | The user's security access level |
|
|||
|
| user_sex | The user's gender |
|
|||
|
| user_subdate | The date the user's subscription expires |
|
|||
|
| user_timelimit | The user's daily time limit |
|
|||
|
| user_todayk | Kilobytes downloaded by the user today |
|
|||
|
| user_upk | Total Kilobytes uploaded by the user |
|
|||
|
| user_uploads | Total number of files uploaded by the user |
|
|||
|
| user_wantchat | Whether or not the user wishes to chat |
|
|||
|
| user_xi_record | The user's record in the USERSXI.BBS file |
|
|||
|
+-----------------------+-----------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
EMSI char od_control.ra_emsi_session;
|
|||
|
INFORMATION char od_control.ra_emsi_crtdef[41];
|
|||
|
char od_control.ra_emsi_protocols[41];
|
|||
|
char od_control.ra_emsi_capabilities[41];
|
|||
|
char od_control.ra_emsi_requests[41];
|
|||
|
char od_control.ra_emsi_software[41];
|
|||
|
char od_control.ra_hold_attr1;
|
|||
|
char od_control.ra_hold_attr2;
|
|||
|
char od_control.ra_hold_len;
|
|||
|
|
|||
|
These variables provide your door with information pertaining to
|
|||
|
an interactive EMSI session that has been established. Note that
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 161
|
|||
|
|
|||
|
these variables are only available under systems that produce an
|
|||
|
RA 1.00 and later style extended EXITINFO.BBS door information
|
|||
|
file.
|
|||
|
|
|||
|
If an IEMSI session has been established, the Boolean variable
|
|||
|
od_control.ra_emsi_session will be TRUE, and if no session has
|
|||
|
not been established, this variable will be FALSE.
|
|||
|
|
|||
|
A full discussion of the IEMSI protocol is beyond the scope of
|
|||
|
this manual. Specifications for the IEMSI protocol are available
|
|||
|
from the OpenDoors support BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event_days unsigned char od_control.event_days;
|
|||
|
|
|||
|
This variable is a bit-mapped flag of the days of the week on
|
|||
|
which the next system event is run. The bit-map bits are as
|
|||
|
follows:
|
|||
|
|
|||
|
+-----+------+-----------+
|
|||
|
| BIT | MASK | MEANING |
|
|||
|
+-----+------+-----------+
|
|||
|
| 0 | 0x01 | Sunday |
|
|||
|
| 1 | 0x02 | Monday |
|
|||
|
| 2 | 0x04 | Tuesday |
|
|||
|
| 3 | 0x08 | Wednesday |
|
|||
|
| 4 | 0x10 | Thursday |
|
|||
|
| 5 | 0x20 | Friday |
|
|||
|
| 6 | 0x40 | Saturday |
|
|||
|
| 7 | 0x80 | All Days |
|
|||
|
+-----+------+-----------+
|
|||
|
|
|||
|
For more information on bit-mapped flags, see the glossary item
|
|||
|
entitled "BIT-MAPPED FLAGS".
|
|||
|
|
|||
|
This variable is only available under systems that produce an
|
|||
|
EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event_ unsigned char od_control.event_errorlevel;
|
|||
|
errorlevel
|
|||
|
This variable contains the ErrorLevel associated with the next
|
|||
|
system event. This variable is only available under systems that
|
|||
|
produce an EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 162
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event char od_control.event_force;
|
|||
|
_force
|
|||
|
This variable indicates whether the next system event should be
|
|||
|
forced to run at a particular time. If this variable contains a
|
|||
|
value of TRUE, then the user should be forced off-line in order
|
|||
|
to accommodate the event, and if this variable is false, then
|
|||
|
the event can wait until after the user logs off normally. This
|
|||
|
variable is only available under systems that produce an
|
|||
|
EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event char od_control.event_last_run[9];
|
|||
|
_last_run
|
|||
|
This variable contains a string representing the date on which
|
|||
|
the next system event was last run, and is in the same format as
|
|||
|
the user_lastdate variable. This variable is only available
|
|||
|
under systems that produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event char od_control.event_starttime[6];
|
|||
|
_starttime
|
|||
|
This variable contains a string representing the time at which
|
|||
|
the next system event is scheduled to start, in the same format
|
|||
|
as the user_lasttime variable. This variable is only available
|
|||
|
under systems that produce an EXITINFO.BBS or Wildcat style
|
|||
|
DOOR.SYS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
event unsigned char od_control.event_status;
|
|||
|
_status
|
|||
|
This variable represents the status of the next system event,
|
|||
|
and will be equal to the value
|
|||
|
|
|||
|
ES_ENABLED
|
|||
|
|
|||
|
if and only if the other event information contained in the
|
|||
|
control structure is valid. This variable is only available
|
|||
|
under systems that produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 163
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
sysop_name char od_control.sysop_name[40];
|
|||
|
|
|||
|
The od_control.sysop_name variable contains the name of the
|
|||
|
sysop of the BBS under which your door is running. This variable
|
|||
|
is available under any BBS system that produces a DORINFO?.DEF
|
|||
|
(including RA & QBBS which process both DORINFO1.DEF and
|
|||
|
EXITINFO.BBS files), or Wildcat style DOOR.SYS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
system_calls long od_control.system_calls;
|
|||
|
|
|||
|
This variable contains the total number of calls that have been
|
|||
|
placed to the BBS, and is available under any BBS which produces
|
|||
|
an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
system_last char od_control.system_last_caller[36];
|
|||
|
_caller
|
|||
|
This string contains the name of the previous caller to the BBS,
|
|||
|
on any line, and is available under EXITINFO.BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
system_last char od_control.system_last_handle[36];
|
|||
|
_handle
|
|||
|
This string contains the handle (alias) of the previous caller
|
|||
|
to the BBS, on any line, and is available under EXITINFO.BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
system_name char od_control.system_name[40];
|
|||
|
|
|||
|
The od_control.system_name variable contains the name of the BBS
|
|||
|
under which your door is running. This variable is available
|
|||
|
under any BBS system that produces a DORINFO?.DEF (including RA
|
|||
|
& QBBS which process both DORINFO1.DEF and EXITINFO.BBS files).
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
TIMELOG char od_control.timelog_start_date[9];
|
|||
|
VARIABLES
|
|||
|
This string contains the date of the beginning of the time
|
|||
|
period for which the time log is recorded. This variable is
|
|||
|
available under any system that produces an EXITINFO.BBS file.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 164
|
|||
|
|
|||
|
|
|||
|
|
|||
|
int od_control.timelog_busyperhour[24];
|
|||
|
|
|||
|
This variable is an array of 24 elements, with each element
|
|||
|
indicating the total number of times the BBS was in use during
|
|||
|
each of the 24 hours of the day. Element 0 corresponds to the
|
|||
|
time period of 0:00-1:00, element 1 corresponds to the time
|
|||
|
period of 1:00-2:00, and so on. In order to determine the
|
|||
|
frequency of system use during any hour as a percentage, simply
|
|||
|
calculate the total of all 24 entries in the array, and divide
|
|||
|
any given entry by the total, in order to come up with an
|
|||
|
average. This variable is available under any system that
|
|||
|
produces an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
int od_control.timelog_busyperday[7];
|
|||
|
|
|||
|
This variable is an array of 7 elements, with each element
|
|||
|
indicating the total number of times the BBS was in use during
|
|||
|
each of the 7 days of the week. Here, elements 0 corresponds to
|
|||
|
Sunday, element 1 to Monday, and so on. In order to calculate
|
|||
|
the frequency of system use during any day of the week, use the
|
|||
|
same method as for calculating the frequency of calls during
|
|||
|
each hour, as described above. This is only available under
|
|||
|
systems that produces an EXITINFO.BBS file. Note that at least
|
|||
|
some, if not all, versions of RemoteAccess do not maintain this
|
|||
|
variable correctly, and thus even with the presence of an
|
|||
|
EXITINFO.BBS file, this array may contain all zero entries.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ansi char od_control.user_ansi;
|
|||
|
|
|||
|
This variable contains a Boolean value, indicating whether or
|
|||
|
not the user has ANSI mode turned on. If ANSI graphics mode is
|
|||
|
enabled, this variable will contain a value of TRUE, and if ANSI
|
|||
|
graphics mode is disabled, this variable will contain a value of
|
|||
|
FALSE. Many of the OpenDoors functions test the setting of this
|
|||
|
variable in order to determine whether or not they should send
|
|||
|
ANSI-graphics control characters. Also, if this variable
|
|||
|
contains a TRUE value, OpenDoors will display an "[ANSI]"
|
|||
|
indicator on the status line.
|
|||
|
|
|||
|
You may change the value of this variable at any time after the
|
|||
|
first call to od_init() or any other OpenDoors functions.
|
|||
|
Depending upon what BBS system your door is running under,
|
|||
|
changes to this variable may or may not result in changes to the
|
|||
|
user's ANSI setting upon return to the BBS.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 165
|
|||
|
|
|||
|
This variable is available under all door information file
|
|||
|
formats.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned char od_control.user_attribute;
|
|||
|
attribute
|
|||
|
This variable is a bitmap of eight flags, each of which
|
|||
|
represent individual pieces of information pertaining to the
|
|||
|
user that is currently online. These flags are as follows:
|
|||
|
|
|||
|
+-----+------+-----------------------+
|
|||
|
| BIT | MASK | DESCRIPTION |
|
|||
|
+-----+------+-----------------------+
|
|||
|
| 0 | 0x01 | Is the user deleted |
|
|||
|
| 1 | 0x02 | Is screen clearing on |
|
|||
|
| 2 | 0x04 | Is "more" prompt on |
|
|||
|
| 3 | 0x08 | Is ANSI mode on |
|
|||
|
| 4 | 0x10 | User no-kill setting |
|
|||
|
| 5 | 0x20 | Transfer-priority |
|
|||
|
| 6 | 0x40 | Full screen editor |
|
|||
|
| 7 | 0x80 | Quiet mode |
|
|||
|
+-----+------+-----------------------+
|
|||
|
|
|||
|
For more information on using and setting bit-mapped flags,
|
|||
|
please see the entry entitled "BITMAPED FLAGS" in the glossary
|
|||
|
of this manual.
|
|||
|
|
|||
|
Note that this variable is only available under systems that
|
|||
|
produce and EXITINFO.BBS format door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned char od_control.user_attrib2;
|
|||
|
attrib2
|
|||
|
See the user_attrib variable for more information. This variable
|
|||
|
is like the user_attrib variable, except that it contains
|
|||
|
different information. The bit-mapped flags for the
|
|||
|
od_control.user_attrib2 variable are as follows:
|
|||
|
|
|||
|
+-----+------+-----------------------+
|
|||
|
| BIT | MASK | DESCRIPTION |
|
|||
|
+-----+------+-----------------------+
|
|||
|
| 0 | 0x01 | User hot-keys setting |
|
|||
|
| 1 | 0x02 | Is AVATAR graphics on |
|
|||
|
| 2 | 0x04 | Full screen reader |
|
|||
|
| 3 | 0x08 | Hidden from userlist |
|
|||
|
+-----+------+-----------------------+
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 166
|
|||
|
|
|||
|
Note that this variable is only available under systems that
|
|||
|
produce an EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned char od_control.user_attrib3;
|
|||
|
attrib3
|
|||
|
This variable contains user attribute flags when a RA 2.50 or
|
|||
|
later EXITINFO.BBS file is used.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_avatar char od_control.user_avatar;
|
|||
|
|
|||
|
This variable is a Boolean value indicating whether or not
|
|||
|
AVATAR graphics mode is on. If AVATAR graphics is available,
|
|||
|
then many of the OpenDoors functions will make use of AVATAR
|
|||
|
graphics codes for greater display speed. If AVATAR graphics
|
|||
|
mode is on, a [AVT] indicator will appear on the status line. If
|
|||
|
your door is running under a system which produces an RA 1.00+
|
|||
|
style extended EXITINFO.BBS door information file, the
|
|||
|
user_avatar variable is set automatically. If the extended
|
|||
|
EXITINFO.BBS file is not available, this value will default to
|
|||
|
FALSE. In this case, you may wish to ask the user whether or not
|
|||
|
they wish to use AVATAR graphics, and thus set this variable
|
|||
|
yourself.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_birthday[9];
|
|||
|
_birthday
|
|||
|
This variable is a string, in the same format as the
|
|||
|
od_control.user_lastcall variable, which stores the date of the
|
|||
|
user's birthday, if it is available. This variable is only
|
|||
|
available under systems that produce an RA 1.00 and later style
|
|||
|
extended EXITINFO.BBS or Wildcat style DOOR.SYS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_callsign[12];
|
|||
|
_callsign
|
|||
|
This variable is a string which contains the user's amateur
|
|||
|
radio call sign, if any. This variable is only available under
|
|||
|
systems that produce a CHAIN.TXT file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 167
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_combined unsigned char od_control.user_combinedrecord[25];
|
|||
|
record
|
|||
|
This variable is an array of bit-mapped flags, with each flag
|
|||
|
corresponding to an individual message area. In this case, the
|
|||
|
first bit of od_control.ra_combinedrecord[0] corresponds to the
|
|||
|
first message area, the second bit to the second message area,
|
|||
|
and so on. If any given bit-flag is turned on, then the user has
|
|||
|
corresponding message area enabled for combined access, and if
|
|||
|
the bit is turned off, the user does not have the area enabled
|
|||
|
for combined access. A detailed description of the combined
|
|||
|
message access is beyond the scope of this manual. This variable
|
|||
|
is only available under systems that produce an RA 1.00 or later
|
|||
|
style extended EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_comment char od_control.user_comment[81];
|
|||
|
|
|||
|
This variable is a string which contains the sysop's comment
|
|||
|
about the user that is currently online. This comment may be
|
|||
|
displayed on the OpenDoors status line, if this variable is
|
|||
|
available. This variable is available under systems that produce
|
|||
|
an RA 1.00 and later style extended EXITINFO.BBS or Wildcat
|
|||
|
style DOOR.SYS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_credit unsigned int od_control.user_credit;
|
|||
|
|
|||
|
This variable contains the total amount of NetMail credit that
|
|||
|
the caller has left. Changes to this variable will be by the BBS
|
|||
|
when your door exits and control is returned to the BBS. This
|
|||
|
variable is only available under systems that produce an
|
|||
|
EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ char od_control.user_dataphone[13];
|
|||
|
dataphone
|
|||
|
This string contains the user's data or business phone number,
|
|||
|
if available. This value is only available under system that
|
|||
|
produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS and WildCat
|
|||
|
DOOR.SYS format door information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 168
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user int od_control.user_deducted_time;
|
|||
|
_deducted
|
|||
|
_time This variable contains a signed integer value, which indicates
|
|||
|
the total amount of time that has been deducted from the user
|
|||
|
during this call. This variable is only available under systems
|
|||
|
that produce an RA 1.00 and later style extended EXITINFO.BBS
|
|||
|
door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_downk unsigned int od_control.user_downk;
|
|||
|
|
|||
|
This variable contains the total kilobytes of files that the
|
|||
|
current user has downloaded from the BBS, and is available under
|
|||
|
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
|
|||
|
SFDOORS.DAT format door information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_downlimit;
|
|||
|
_downlimit
|
|||
|
This variable contains the total number of kilobytes that the
|
|||
|
caller is permitted to download during this call. If your door
|
|||
|
allows files do be downloaded, you will probably want to compare
|
|||
|
the value of this variable to the size of any file to be
|
|||
|
transferred and the total kilobytes already downloaded, as
|
|||
|
stored in the od_control.user_todayk variable. This variable is
|
|||
|
only available under systems that produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_downloads;
|
|||
|
_downloads
|
|||
|
This variable contains the total number of files that the
|
|||
|
current user has downloaded from the BBS, and is available under
|
|||
|
systems that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS,
|
|||
|
WildCat style DOOR.SYS or SFDOORS.DAT format door information
|
|||
|
files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_echo char od_control.user_echomailentered;
|
|||
|
mailentered
|
|||
|
This variable is a Boolean value, indicating whether or not the
|
|||
|
user has entered new EchoMail during this call. If this variable
|
|||
|
has a value of TRUE, then EchoMail has been entered, and if it
|
|||
|
has a value of FALSE, then EchoMail has not been entered. This
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 169
|
|||
|
|
|||
|
variable will contain a valid value only after od_init() or some
|
|||
|
OpenDoors function has been called. Any changes made to this
|
|||
|
variable will be reflected within the BBS software when control
|
|||
|
is returned to the BBS. This variable is accessible only under
|
|||
|
systems which produce an EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_error char od_control.user_error_free;
|
|||
|
_free
|
|||
|
This variable contains a Boolean value indicating whether or not
|
|||
|
the user is connected to the BBS via an error free connection
|
|||
|
(eg. a V.42/MNP or similar modem protocol). This variable is
|
|||
|
only available under systems that produce an SFDOORS.DAT,
|
|||
|
Wildcat style DOOR.SYS or RA 1.00 or later style extended
|
|||
|
EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_first char od_control.user_firstcall[9];
|
|||
|
call
|
|||
|
This variable is a string which contains the date of the user's
|
|||
|
first call, in the same format as the od_control. user_lastcall
|
|||
|
variable. This variable is only available under systems which
|
|||
|
produce an RA 1.00 and later style extended EXITINFO.BBS door
|
|||
|
information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned char od_control.user_flags[4];
|
|||
|
flags
|
|||
|
The od_control.user_flags variable is an array of four sysop
|
|||
|
defined bit-mapped flags, which represent some sort of
|
|||
|
information about the user. od_control.user_flags[0] stores
|
|||
|
flags A1 - A8 in bits 0 through 7, respectively. Likewise,
|
|||
|
od_control.user_flags[1] stores flags B1 - B8, and so on. This
|
|||
|
variable is only available under systems that produce
|
|||
|
EXITINFO.BBS format door information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_handle char od_control.user_handle[36];
|
|||
|
|
|||
|
This variable contains the user's alias or handle name, if any.
|
|||
|
If the user does not have and alias or handle, this variable
|
|||
|
will be blank. This variable is only available under systems
|
|||
|
that produce a CHAIN.TXT, RA 1.00 and later extended
|
|||
|
EXITINFO.BBS or Wildcat style DOOR.SYS door information file.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 170
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ char od_control.user_homephone[13];
|
|||
|
homephone
|
|||
|
This string contains the user's home or data phone number, if
|
|||
|
available. This value is only available under system that
|
|||
|
produce one of the following door information files:
|
|||
|
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
|
|||
|
DOOR.SYS or SFDOORS.DAT.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned char od_control.user_last_pwdchange;
|
|||
|
_last
|
|||
|
_pwdchange This variable contains the number of calls that the user has
|
|||
|
made since they last changed their password. This variable is
|
|||
|
only available under EXITINFO.BBS files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_lastdate[9];
|
|||
|
_lastdate
|
|||
|
This variable is a string containing the date of the user's last
|
|||
|
call to the BBS, and should always be of the format:
|
|||
|
|
|||
|
"MM-DD-YY"
|
|||
|
|
|||
|
Where MM is two digits representing the number of the month of
|
|||
|
the user's call, with 1 being January, 2 being February, and so
|
|||
|
on. DD should be two digits representing the day of the month of
|
|||
|
the user's last call, beginning with 1, and MM should be the
|
|||
|
last two digits of the year of the user's last call.
|
|||
|
|
|||
|
This variable is only available under systems that produce one
|
|||
|
of the following door information files: CHAIN.TXT,
|
|||
|
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS or WildCat style
|
|||
|
DOOR.SYS files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned int od_control.user_lastread;
|
|||
|
lastread
|
|||
|
This variable contains the number of the highest message number
|
|||
|
that the user has read, and is only available under EXITINFO.BBS
|
|||
|
format door information files.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 171
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_lasttime[6];
|
|||
|
_lasttime
|
|||
|
This variable contains a string representing the time of the
|
|||
|
user's last call to the BBS, and should always be of the format:
|
|||
|
|
|||
|
"HH:MM"
|
|||
|
|
|||
|
Where HH is two digits representing the 24-hour format hour of
|
|||
|
the user's last call, and MM is two digits representing the
|
|||
|
minute of the user's last call. Thus, the following strings
|
|||
|
would be valid entries for this string:
|
|||
|
|
|||
|
"00:01" (12:01 am)
|
|||
|
"03:47" (3:47 am)
|
|||
|
"18:20" (6:20 pm)
|
|||
|
|
|||
|
This variable is only available under systems that produce an
|
|||
|
EXITINFO.BBS or Wildcat style DOOR.SYS format door information
|
|||
|
file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_location[26];
|
|||
|
_location
|
|||
|
This string contains the name of the location from which the
|
|||
|
current user is calling from. This will usually be the name of
|
|||
|
the city, region (province, state, etc.) and sometimes country
|
|||
|
where the user lives. The contents of this variable are
|
|||
|
displayed on the OpenDoors status line. The value of this
|
|||
|
variable is valid after od_init() or any other OpenDoors
|
|||
|
function has been called. Also, you may change the value of this
|
|||
|
variable if you wish. However, not that these changes may not
|
|||
|
immediately be reflected in the status line, and may or may not
|
|||
|
cause the setting to be changed after the user returns to the
|
|||
|
BBS. This variable is available under systems that produce one
|
|||
|
of the following door information files: DORINFO?.DEF,
|
|||
|
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat style
|
|||
|
DOOR.SYS SFDOORS.DAT and CALLINFO.BBS, but is not available
|
|||
|
under CHAIN.TXT or DoorWay style DOOR.SYS files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.caller_logindate[9];
|
|||
|
_logindate
|
|||
|
This variable contains a string representing the date on which
|
|||
|
the current call to the BBS began. This variable is in the same
|
|||
|
format as the od_control.user_lastdate variable, described
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 172
|
|||
|
|
|||
|
below. This variable is only available under systems which
|
|||
|
produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user long od_control.user_loginsec;
|
|||
|
_loginsec
|
|||
|
This variable contains the user's security at login, and can be
|
|||
|
used to detect changes by the sysop or other programs during the
|
|||
|
course of the call, by comparing it's value with the
|
|||
|
od_control.user_security variable. This variable is only
|
|||
|
available under systems which produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_logintime[6];
|
|||
|
_logintime
|
|||
|
This variable contains a string representing the time of day at
|
|||
|
which the current call to the BBS began. This variable is in the
|
|||
|
same format as the od_control.user_lasttime variable, which is
|
|||
|
also described below. This variable is available under systems
|
|||
|
which produce an EXITINFO.BBS, a Wildcat style DOOR.SYS, or an
|
|||
|
SFDOORS.DAT file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_logonpassword[16];
|
|||
|
_logon
|
|||
|
password This variable is a string which contains the user's password
|
|||
|
at the time at which the current call to the BBS began. This
|
|||
|
variable can be used to detect changes by the sysop or other
|
|||
|
programs to the user's password, which have taken place during
|
|||
|
the course of the call. In order to detect such changes, simply
|
|||
|
compare the contents of this string with the contents of the
|
|||
|
od_control.user_password variable. This variable is only
|
|||
|
available under systems which produce an EXITINFO.BBS format
|
|||
|
door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_menustack[50][9];
|
|||
|
_menustack
|
|||
|
This variable is an array of 50 strings, containing the stack of
|
|||
|
BBS menus that have been executed, and is used to record the
|
|||
|
current position of the user within the BBS's menu system. Each
|
|||
|
string contains just the base portion of the filename of the
|
|||
|
menu, without the extension. The od_control.ra_menustackpointer
|
|||
|
variable points to the top of the menu stack. However, a
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 173
|
|||
|
|
|||
|
complete discussion of the menu stack is beyond the scope of
|
|||
|
this manual. This variable is only available under systems that
|
|||
|
produce an RA 1.00 and later style extended EXITINFO.BBS door
|
|||
|
information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned char od_control.user_menustackpointer;
|
|||
|
_menustack
|
|||
|
pointer This variable points to the top of the current menu stack. For
|
|||
|
more information on the menu stack, please refer to the
|
|||
|
od_control.ra_menustack variable, above. This variable is only
|
|||
|
available under systems that produce an RA 1.00 and later style
|
|||
|
extended EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_messages;
|
|||
|
_messages
|
|||
|
This variable contains a value representing the total number of
|
|||
|
messages that have been written by the user, and is available
|
|||
|
under EXITINFO.BBS or Wildcat style DOOR.SYS format door
|
|||
|
information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_name char od_control.user_name[36];
|
|||
|
|
|||
|
This string contains the name of the user that is currently on-
|
|||
|
line, and is used by OpenDoors to display the current user name
|
|||
|
on the status line, and will most likely be used by your door
|
|||
|
for differentiating among different users. In most cases, you
|
|||
|
should probably not change the value of this variable, as a
|
|||
|
user's name does not usually change, and doing so could results
|
|||
|
in problems when returning to some BBS systems. For an example
|
|||
|
of using this variable, see the EX_VOTE.C example program. This
|
|||
|
variable is available under all BBS systems.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_net_ unsigned int od_control.user_net_credit;
|
|||
|
credit
|
|||
|
This variable contains the amount of NetMail credit that the
|
|||
|
current user has to his or her name. This variable is only
|
|||
|
available under systems that produce an EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 174
|
|||
|
|
|||
|
Note that if you wish to change the value of the user's
|
|||
|
remaining NetMail credit, you should use the od_control.
|
|||
|
user_credit variable, instead of this variable.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_net char od_control.user_netmailentered;
|
|||
|
mailentered
|
|||
|
This variable is a Boolean value, indicating whether or not the
|
|||
|
user has entered new NetMail or GroupMail during this call. If
|
|||
|
this variable has a value of TRUE, then NetMail/GroupMail has
|
|||
|
been entered, and if it has a value of FALSE, then
|
|||
|
NetMail/GroupMail has not been entered. This variable will
|
|||
|
contain a valid value only after od_init() or some OpenDoors
|
|||
|
function has been called. Any changes made to this variable will
|
|||
|
be reflected within the BBS software when control is returned to
|
|||
|
the BBS. This variable is accessible only under systems which
|
|||
|
produce an EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_num unsigned int od_control.user_num;
|
|||
|
|
|||
|
This variable contains the number of the user's record in the
|
|||
|
user database file, where 0 is the first record. This can be
|
|||
|
useful for changing user settings that are not re-read by the
|
|||
|
BBS, such as the user's phone number or security level which
|
|||
|
might be altered by a call back verification door. However, the
|
|||
|
value of this variable itself should not be altered.
|
|||
|
|
|||
|
This variable is available under systems which produce any of
|
|||
|
the following door information file formats: CHAIN.TXT, PC-
|
|||
|
Board/GAP style DOOR.SYS, Wildcat style DOOR.SYS SFDOORS.DAT and
|
|||
|
EXITINFO.BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned int od_control.user_numcalls;
|
|||
|
numcalls
|
|||
|
This variable contains the total number of calls that the
|
|||
|
current user has placed to the BBS, and is available under
|
|||
|
systems that produce EXITINFO.BBS or PC-Board/GAP and Wildcat
|
|||
|
style DOOR.SYS door information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 175
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_numpages;
|
|||
|
_numpages
|
|||
|
The value of this variable contains the total number of times
|
|||
|
that the user has paged the sysop, and can be used to limit the
|
|||
|
number of times that the user is permitted to page the sysop.
|
|||
|
OpenDoors increments this variable every time that the user
|
|||
|
pages the sysop, via the od_page() function. This variable is
|
|||
|
used with all types of door information files. However, this
|
|||
|
variable will only reflect the value within the BBS if an
|
|||
|
EXITINFO.BBS file is produced. Otherwise, the variable will only
|
|||
|
contain the number of times that the user has paged within the
|
|||
|
door, but not the total number of times the user has paged.
|
|||
|
Under EXITINFO.BBS systems, changes to the value of this
|
|||
|
variable will be reflected within the BBS upon return by the
|
|||
|
DOOR.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_password[16];
|
|||
|
_password
|
|||
|
This variable contains the user's password for accessing the
|
|||
|
BBS. OpenDoors does not use this value itself. This variable
|
|||
|
will contain a valid value only after od_init() or some
|
|||
|
OpenDoors function has been called. You may change the value of
|
|||
|
this variable. Note, however, that changes in this variable may
|
|||
|
or may not cause the setting to be changed when control returns
|
|||
|
to the BBS - this will depend upon the particular BBS system
|
|||
|
your door is running under. This variable is only available
|
|||
|
under systems that produce one of the following door information
|
|||
|
files: EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS,
|
|||
|
SFDOORS.DAT, and CALLINFO.BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_pending unsigned int od_control.user_pending;
|
|||
|
|
|||
|
This variable represents the total value of NetMail that has
|
|||
|
been written by the current user, but not yet exported from the
|
|||
|
message base. This variable is only available under systems that
|
|||
|
produce an EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_reason char od_control.user_reasonforchat[78];
|
|||
|
forchat
|
|||
|
This variable is a string, containing the reason for which the
|
|||
|
user wishes to chat with the sysop, as they entered at the time
|
|||
|
of paging the sysop. This variable will contain an empty string
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 176
|
|||
|
|
|||
|
if the user has not paged the sysop, or if the reason the user
|
|||
|
wishes to chat is unknown. See also the od_control.user_wantchat
|
|||
|
variable. This variable is available under all BBS systems,
|
|||
|
regardless of what style of door information file they produce.
|
|||
|
However, this variable will not be passed between the door and
|
|||
|
BBS, and thus the user's reason for chat within the door will
|
|||
|
not necessarily correspond to their reason for chat outside the
|
|||
|
door.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_rip char user_rip;
|
|||
|
|
|||
|
This variable is set to TRUE if the user has RIP (Remote Imaging
|
|||
|
Protocol) graphics enabled, and FALSE if they do not. This
|
|||
|
setting can be determined from the door information (drop) file
|
|||
|
in many cases. In other cases, you can automatically determine
|
|||
|
whether or not the user's system supports RIP graphics using the
|
|||
|
od_autodetect() function (see page 48).
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_rip_ver BYTE user_rip_ver;
|
|||
|
|
|||
|
This variable contains the version of the RIP protocol that is
|
|||
|
in use. This variable is only available under a RemoteAccess
|
|||
|
2.50 EXITINFO.BBS file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_screen_length;
|
|||
|
_screen
|
|||
|
_length This value of this variable represents the total number of
|
|||
|
lines that can be displayed on the user's screen at once, and is
|
|||
|
usually either 24 or 25. You may wish to make use of this
|
|||
|
variable to allow your door to pause the display of long pieces
|
|||
|
of text after every screen length, in order to allow the user to
|
|||
|
read this information before it passes off of their screen. In
|
|||
|
this case, you would simply maintain a counter of the total
|
|||
|
number of lines displayed, and when this value reaches one less
|
|||
|
than the length of the user screen, display a prompt asking the
|
|||
|
user to whether or not they wish to continue.
|
|||
|
|
|||
|
This variable is set to the user's setting within the BBS under
|
|||
|
systems that produce any of the following door information file
|
|||
|
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
|
|||
|
DOOR.SYS and CALLINFO.BBS files.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 177
|
|||
|
|
|||
|
This variable is used by the OpenDoors function,
|
|||
|
od_list_files(). If this variable contains a valid value,
|
|||
|
OpenDoors will pause the listing of files after every screen,
|
|||
|
and give the user the option of continuing, aborting, or
|
|||
|
disabling the "Continue?" prompt for the rest of the file
|
|||
|
listing. Thus, if you are using the od_list_files() under a
|
|||
|
system that does not produce one of the door information files
|
|||
|
listed above, you may wish to obtain the user's screen length
|
|||
|
from the user themselves. If the screen length is not available
|
|||
|
from the particular type of door information file that is found,
|
|||
|
and you do not set this value yourself, this variable will
|
|||
|
default to 23. If you are going to set the value of this
|
|||
|
variable yourself, you should do so after having called
|
|||
|
od_init() or some OpenDoors function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_ unsigned char od_control.user_screenwidth;
|
|||
|
screenwidth
|
|||
|
This variable contains a value representing the width of the
|
|||
|
user's screen, and will most often be equal to 80. This variable
|
|||
|
is only available under systems that produce a CHAIN.TXT or RA
|
|||
|
1.00 and later style extended EXITINFO.BBS door information
|
|||
|
file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_security;
|
|||
|
_security
|
|||
|
This variable contains a numerical value representing the user's
|
|||
|
security access level on the BBS. You may wish to use this value
|
|||
|
to determine whether or not the current user of your door should
|
|||
|
have access to certain sysop-only functions. In this case, you
|
|||
|
may wish to have a configuration file used by your door, in
|
|||
|
which the sysop may define the minimum security level for sysop
|
|||
|
access. You would then be able to compare this configuration
|
|||
|
setting to the security level stored in this variable, in order
|
|||
|
to determine whether or not sysop function should be available.
|
|||
|
An alternative method, used by the EX_VOTE.C sample door, of
|
|||
|
determining whether or not the current user is the sysop is to
|
|||
|
compare the user's name with the value of the
|
|||
|
od_control.sysop_name variable. This method has the advantage of
|
|||
|
not requiring a configuration program, but the disadvantage that
|
|||
|
the door will not function correctly under all BBS systems, as
|
|||
|
the od_control.sysop_name variable is not available under all
|
|||
|
BBS systems.
|
|||
|
|
|||
|
The od_control.user_security variable is available under BBS
|
|||
|
systems that produce any of the following door information file
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 178
|
|||
|
|
|||
|
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
|
|||
|
DOOR.SYS, SFDOORS.DAT or CALLINFO.BBS.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_sex char od_control.user_sex;
|
|||
|
|
|||
|
This variable contains a single character representing the
|
|||
|
gender of the user that is currently online. This variable will
|
|||
|
contain an upper-case 'F' if the user is female, and an upper-
|
|||
|
case 'M' if the user is male. This variable is available under
|
|||
|
systems that produce a CHAIN.TXT or RA 2.x style EXITINFO.BBS
|
|||
|
file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_subdate char od_control.user_subdate[9];
|
|||
|
|
|||
|
This variable is a string, in the same format as the
|
|||
|
od_control.user_lastdate variable, which stores the date of
|
|||
|
expiry of the user's subscription to the BBS. This variable is
|
|||
|
only available under systems which produce a PC-Board/GAP and
|
|||
|
Wildcat style DOOR.SYS or RA 1.00 and later style extended
|
|||
|
EXITINFO.BBS door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user int od_control.user_timelimit;
|
|||
|
_timelimit
|
|||
|
This variable contains the amount of time, in minutes, that the
|
|||
|
user has left in the door. Note that this value may or may not
|
|||
|
be equal to the total amount of time that the user has left on
|
|||
|
the BBS, depending upon whether the BBS or a third-party door
|
|||
|
manager program only allows a limited amount of time in this
|
|||
|
door. This variable contains a valid value after od_init() or
|
|||
|
some OpenDoors function has been called. OpenDoors uses this
|
|||
|
variable to keep track of how much time the user has left in the
|
|||
|
door, and will automatically warn the user when nearly all of
|
|||
|
his or her time has been used up. OpenDoors will also force the
|
|||
|
user out of the door when their time in the door has expired.
|
|||
|
OpenDoors automatically subtracts one minute from this variable
|
|||
|
every minute that OpenDoors is active, unless chat mode has been
|
|||
|
activated (in which case the user's time will freeze), and also
|
|||
|
adjusts the value of this variable when the sysop uses the time
|
|||
|
adjustment function keys. Hence, you will not normally have any
|
|||
|
need to alter the value of this variable yourself. However,
|
|||
|
there may be some cases in which you wish to subtract a penalty
|
|||
|
or add a bonus to the user's time, such as in a "timebank" door
|
|||
|
or a door game that permits the user to "gamble time".
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 179
|
|||
|
|
|||
|
|
|||
|
Depending on which BBS system your door is running under, the
|
|||
|
value of this variable may or may not effect the user's time
|
|||
|
left upon return to the BBS. The BBS system will either reset
|
|||
|
the user's time to the value re-written to the door information
|
|||
|
file (this variable), or will always subtract the amount of time
|
|||
|
spent in the door from the user's remaining time.
|
|||
|
|
|||
|
This variable is available under all door information file
|
|||
|
formats.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_todayk;
|
|||
|
_todayk
|
|||
|
This variable contains the total kilobytes of files that the
|
|||
|
current user has downloaded from the BBS during the current day,
|
|||
|
and is available under systems that produce EXITINFO.BBS, PC-
|
|||
|
Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door
|
|||
|
information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_upk unsigned int od_control.user_upk;
|
|||
|
|
|||
|
This variable contains the total kilobytes of files that the
|
|||
|
current user has uploaded to the BBS, and is available under
|
|||
|
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
|
|||
|
SFDOORS.DAT files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user_uploads unsigned int od_control.user_uploads;
|
|||
|
|
|||
|
This variable contains the total number of files that the
|
|||
|
current user has uploaded to the BBS, and is available under
|
|||
|
systems that produce EXITINFO.BBS, PC-Board/GAP and Wildcat
|
|||
|
style DOOR.SYS, or SFDOORS.DAT format door information files.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user char od_control.user_wantchat;
|
|||
|
_wantchat
|
|||
|
This variable is a Boolean value which indicates whether or not
|
|||
|
the user wishes to chat with the sysop (ie, the user has paged
|
|||
|
the sysop, but has yet to receive a chat with the sysop). This
|
|||
|
variable is used under all door information file formats.
|
|||
|
However, changes to this variable are only reflected on the BBS
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 180
|
|||
|
|
|||
|
when the door is running under a system that produces an
|
|||
|
EXITINFO.BBS door information file.
|
|||
|
|
|||
|
This variable is automatically turned on (ie., set to TRUE),
|
|||
|
when the user begins to page the sysop for chat, within the
|
|||
|
od_page() function, and is automatically turned off (ie., set to
|
|||
|
FALSE), when the sysop breaks in for chat via the chat function
|
|||
|
key. Also, setting this variable to TRUE will turn on the
|
|||
|
flashing want-chat indicator on the OpenDoors status line.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
user unsigned int od_control.user_xi_record;
|
|||
|
_xi_record
|
|||
|
This variable contains the number of the user's record in the
|
|||
|
USERXI.BBS file, if any. This variable is only available under
|
|||
|
system that produce a Remote Access 1.00 and later style
|
|||
|
extended door information file.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 181
|
|||
|
|
|||
|
CONTROL STRUCTURE - DOOR SETTINGS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section deals with those variables in the OpenDoors control
|
|||
|
structure which reflect the current door settings. These
|
|||
|
variables are as follows:
|
|||
|
|
|||
|
od_cur_attrib The current display attribute, or -1 if
|
|||
|
unknown.
|
|||
|
|
|||
|
od_okaytopage Controls whether the user is currently
|
|||
|
permitted to page the sysop.
|
|||
|
|
|||
|
od_pageendmin End of valid paging hours.
|
|||
|
|
|||
|
od_pagestartmin Start of valid paging hours.
|
|||
|
|
|||
|
od_silent_mode Turns off local user interface.
|
|||
|
|
|||
|
od_user_keyboard_on Controls whether OpenDoors will
|
|||
|
currently accept input from the remote
|
|||
|
user's keyboard.
|
|||
|
|
|||
|
od_update_status_now Forces immediate update of the status
|
|||
|
line.
|
|||
|
|
|||
|
sysop_next Indicates whether or not the sysop has
|
|||
|
reserved use of the system after the
|
|||
|
current calls.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cur int od_control.od_cur_attrib;
|
|||
|
_attrib
|
|||
|
This read-only values stores the current display color
|
|||
|
attribute, or the value -1 if the current display color is
|
|||
|
unknown (such as when the door first begins execution).
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od char od_control.od_okaytopage;
|
|||
|
_okaytopage
|
|||
|
This variable allows you to control whether or not the user is
|
|||
|
currently permitted to page the sysop via the od_page()
|
|||
|
function. A value of PAGE_ENABLE indicates that paging is
|
|||
|
currently permitted, regardless of the sysop page hours setting.
|
|||
|
A value of PAGE_DISABLE indicates that paging is not current
|
|||
|
permitted. A value of PAGE_USE_HOURS indicates that the
|
|||
|
od_page() function should check the values of the
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 182
|
|||
|
|
|||
|
od_pagestartmin and od_pageendmin variables in order to
|
|||
|
determine whether or not paging should be permitted.
|
|||
|
The od_okaytopage variable should only be set after you call
|
|||
|
od_init() or some other OpenDoors function. The default value is
|
|||
|
PAGE_USE_HOURS. For more information on the od_page() function
|
|||
|
itself, see page 101.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od unsigned int od_control.od_pageendmin;
|
|||
|
_pageendmin
|
|||
|
This variable can be used to set the beginning of valid sysop
|
|||
|
paging hours within the od_page() function. If the
|
|||
|
od_control.od_okaytopage variable (which is described above) is
|
|||
|
set to MAYBE, then OpenDoors will check the value of this
|
|||
|
variable prior to paging the sysop via the od_page() function.
|
|||
|
This variable should contain the time at which the valid sysop
|
|||
|
paging hours end, represented as the a number of minutes since
|
|||
|
midnight. For more information on the od_page() function itself,
|
|||
|
see page 101.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od unsigned int od_control.od_pagestartmin;
|
|||
|
_pagestartmin
|
|||
|
This variable can be used to set the beginning of valid sysop
|
|||
|
paging hours within the od_page() function. If the
|
|||
|
od_control.od_okaytopage variable (which is described above) is
|
|||
|
set to MAYBE, then OpenDoors will check the value of this
|
|||
|
variable prior to paging the sysop via the od_page() function.
|
|||
|
This variable should contain the time at which the valid sysop
|
|||
|
paging hours begin, represented as the a number of minutes since
|
|||
|
midnight. For more information on the od_page() function itself,
|
|||
|
see page 101.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_silent BOOL od_control.od_silent_mode;
|
|||
|
_mode
|
|||
|
If this variable is set to TRUE prior to the first call to any
|
|||
|
OpenDoors function, OpenDoors will operate in silent mode, where
|
|||
|
the local display and sysop commands are not used. Silent mode
|
|||
|
is automatically disabled if the program is running in local
|
|||
|
mode.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 183
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_update char od_control.od_update_status_now;
|
|||
|
_status_now
|
|||
|
Setting this variable to TRUE forces OpenDoors to update the
|
|||
|
status line during the next od_kernel() execution. When the
|
|||
|
status line is updated, this variable is reset to its default
|
|||
|
value of FALSE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_user char od_control.od_user_keyboard_on;
|
|||
|
_keyboard_on
|
|||
|
This variable is a Boolean value, indicating whether OpenDoors
|
|||
|
will currently accept input from a remote user. OpenDoors
|
|||
|
provides a function key (usually [ALT]-[K], unless you have
|
|||
|
changed the default), which will allow the sysop to temporarily
|
|||
|
prevent the user from having any control over the door. When the
|
|||
|
sysop activates this feature, a flashing [Keyboard-Off]
|
|||
|
indicator will appear on the status line, and this variable will
|
|||
|
be set to FALSE. When the sysop presses the [ALT]-[K]
|
|||
|
combination a second time, to toggle the user's keyboard back
|
|||
|
on, the flashing indicator will disappear, and this variable
|
|||
|
will be set back to TRUE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
sysop_next char od_control.sysop_next;
|
|||
|
|
|||
|
This variable is a Boolean value, indicating whether or not the
|
|||
|
"sysop next" feature has been activated. The "sysop next"
|
|||
|
feature, which reserves the system for the sysop after the call
|
|||
|
has ended, can be toggled on and off within OpenDoors by use of
|
|||
|
a function key (Alt-N by default). Also, when the "sysop next"
|
|||
|
feature has been activated, an indicator will appear on the
|
|||
|
OpenDoors status line. This variable is only available under
|
|||
|
systems that produce an SFDOORS.DAT or RA 1.00 and later style
|
|||
|
extended EXITINFO.BBS door information file. For more
|
|||
|
information on testing the type of door information file
|
|||
|
available, please see page 158.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 184
|
|||
|
|
|||
|
CONTROL STRUCTURE - DIAGNOSTICS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
To help in diagnosing problems in your OpenDoors programs,
|
|||
|
OpenDoors stores information on the most recent error which
|
|||
|
occurred. When any of the OpenDoors functions return an "error"
|
|||
|
or "failure" state, the reason for this failure is recorded.
|
|||
|
|
|||
|
The following OpenDoors control structure variable provides
|
|||
|
diagnostics information:
|
|||
|
|
|||
|
od_error Stores a "reason code" for the last
|
|||
|
failed OpenDoors API function call.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_error int od_control.od_error;
|
|||
|
|
|||
|
When any of the OpenDoors API functions return an "error" or
|
|||
|
"failure" state (usually denoted by either of the values FALSE
|
|||
|
or NULL), the reason for the failure is recorded in this
|
|||
|
variable. Since successful function calls do not alter the value
|
|||
|
of the od_control.od_error variable, you must be careful not
|
|||
|
only to check the value of the od_control.od_error variable, but
|
|||
|
also to check the OpenDoors function return codes, in order to
|
|||
|
determine which function failed.
|
|||
|
|
|||
|
This variable will always store the reason for the most recent
|
|||
|
function call failure, or ERR_NONE if no functions have failed.
|
|||
|
od_error may take on any of the following values:
|
|||
|
|
|||
|
ERR_NONE Indicates that no error has occurred
|
|||
|
yet.
|
|||
|
|
|||
|
ERR_MEMORY Function was unable to allocate
|
|||
|
required memory. This usually indicates
|
|||
|
that there is not enough available
|
|||
|
memory. This failure may also be due to
|
|||
|
memory corruption caused by your
|
|||
|
program inadvertently overwriting heap
|
|||
|
structures. If your program has been
|
|||
|
compiled in either the small or the
|
|||
|
medium memory model, try recompiling it
|
|||
|
in the compact, large, or huge memory
|
|||
|
models. If your program is already
|
|||
|
compiled in the compact, large, or huge
|
|||
|
memory models, try making more system
|
|||
|
memory available to your program.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 185
|
|||
|
|
|||
|
ERR_NOGRAPHICS This setting indicates that the
|
|||
|
function called requires ANSI, AVATAR
|
|||
|
or RIP graphics mode, but none of these
|
|||
|
modes are active.
|
|||
|
|
|||
|
ERR_PARAMETER An invalid parameter was passed to an
|
|||
|
OpenDoors functions. Check the
|
|||
|
function's description in chapter four,
|
|||
|
to determine the required values for
|
|||
|
each function parameter.
|
|||
|
|
|||
|
ERR_FILEOPEN OpenDoors was unable to open a file.
|
|||
|
This can be due to the specified
|
|||
|
filename not existing, due to the file
|
|||
|
being locked for exclusive access by
|
|||
|
another process, or due to a hardware
|
|||
|
failure.
|
|||
|
|
|||
|
ERR_FILEREAD OpenDoors was able to open the
|
|||
|
specified file, but unable to read the
|
|||
|
required data from the file. This error
|
|||
|
may be due to an invalid file format,
|
|||
|
due to a portion of the file being
|
|||
|
locked by another process, or due to a
|
|||
|
hardware failure.
|
|||
|
|
|||
|
ERR_LIMIT An internal function limit has been
|
|||
|
exceeded. Refer to the function's
|
|||
|
description in chapter four for
|
|||
|
information on the function's
|
|||
|
limitations.
|
|||
|
|
|||
|
ERR_NOREMOTE Indicates that a function has been
|
|||
|
called which is not valid in local
|
|||
|
mode, such as od_carrier() or
|
|||
|
od_set_dtr().
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 186
|
|||
|
|
|||
|
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors control structure provides many variables which
|
|||
|
allow you to customize OpenDoor's behavior and appearance. These
|
|||
|
customization variables fit into one of the following
|
|||
|
categories:
|
|||
|
|
|||
|
General Behavior Customization Variables
|
|||
|
Sysop Function Keys Customization Variables
|
|||
|
Color Customization Variables
|
|||
|
Language-Specific Prompts Customization Variables
|
|||
|
|
|||
|
This section deals with those variables that fit into the first
|
|||
|
category, "General Behavior Customization Variables". The other
|
|||
|
categories are dealt with in the following sections of this
|
|||
|
chapter.
|
|||
|
|
|||
|
Below is a brief overview of the variables grouped into this
|
|||
|
section of the OpenDoors control structure. Following the
|
|||
|
overview is a detailed description of each of these variables.
|
|||
|
|
|||
|
|
|||
|
od_app_icon Program icon for Win32 version.
|
|||
|
|
|||
|
od_box_chars Array of characters used by the
|
|||
|
od_draw_box() function.
|
|||
|
|
|||
|
od_before_exit Function to call prior to exiting.
|
|||
|
|
|||
|
od_cafter_chat Function to call after sysop chat.
|
|||
|
|
|||
|
od_cafter_shell Function to call after DOS shell.
|
|||
|
|
|||
|
od_cbefore_chat Function to call prior to sysop chat.
|
|||
|
|
|||
|
od_cbefore_shell Function to call prior to DOS shell.
|
|||
|
|
|||
|
od_cfg_lines Sets the configuration file's custom
|
|||
|
door information file line keywords.
|
|||
|
|
|||
|
od_cfg_text Sets the built-in configuration file
|
|||
|
keywords that OpenDoors will recognize.
|
|||
|
|
|||
|
od_chat_active Controls whether or not sysop chat mode
|
|||
|
is active.
|
|||
|
|
|||
|
od_clear_on_exit Controls whether the screen is cleared
|
|||
|
upon door exit.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 187
|
|||
|
|
|||
|
od_color_delimiter Indicates what character should delimit
|
|||
|
imbedded color codes for the
|
|||
|
od_printf() function.
|
|||
|
|
|||
|
od_color_names Strings which OpenDoors recognizes as
|
|||
|
the names of various text colors.
|
|||
|
|
|||
|
od_config_file Used to enable or disable the OpenDoors
|
|||
|
configuration file system.
|
|||
|
|
|||
|
od_config_filename Sets the filename that will be read by
|
|||
|
the configuration file system.
|
|||
|
|
|||
|
od_config_function The callback function that OpenDoors
|
|||
|
will call to allow your program to
|
|||
|
process custom configuration file
|
|||
|
entries.
|
|||
|
|
|||
|
od_default_personality Sets the default personality to be used
|
|||
|
with the OpenDoors Multiple Personality
|
|||
|
System, and also sets the personality
|
|||
|
to use when the MPS is not active.
|
|||
|
|
|||
|
od_default_rip_win Whether OpenDoors should use the
|
|||
|
default 43-line RIP window for ANSI
|
|||
|
text (TRUE), or a 23-line window
|
|||
|
(FALSE).
|
|||
|
|
|||
|
od_disable Disable OpenDoors activities such as
|
|||
|
reading door information file and
|
|||
|
monitoring carrier detect / remaining
|
|||
|
time.
|
|||
|
|
|||
|
od_disable_dtr Specifies the string that will be sent
|
|||
|
to the modem to prevent the modem from
|
|||
|
hanging up when DTR is lowered.
|
|||
|
|
|||
|
od_emu_simluate_modem Simulates modem display speed for
|
|||
|
emulation functions such as
|
|||
|
od_send_file(), od_disp_emu() and
|
|||
|
od_hotkey_menu().
|
|||
|
|
|||
|
od_errorlevel Sets the errorlevel OpenDoors exits
|
|||
|
with under various conditions.
|
|||
|
|
|||
|
od_force_local Forces door to operate in local mode,
|
|||
|
ignoring any door information file and
|
|||
|
using default user settings.
|
|||
|
|
|||
|
od_help_callback Allows you to provide a help menu item
|
|||
|
under the Win32 version of OpenDoors
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 188
|
|||
|
|
|||
|
od_in_buf_size Sets size of OpenDoor's internal
|
|||
|
local/remote inbound buffer.
|
|||
|
|
|||
|
od_inactive_warning Number of seconds before hanging up
|
|||
|
that OpenDoors displays the inactivity
|
|||
|
timeout warning.
|
|||
|
|
|||
|
od_inactivity Controls user inactivity timeout.
|
|||
|
|
|||
|
od_ker_exec Is called whenever od_kernel()
|
|||
|
executes.
|
|||
|
|
|||
|
od_last_input Indicates whether the last input came
|
|||
|
from the remote user (==0) or the local
|
|||
|
sysop (==1).
|
|||
|
|
|||
|
od_list_pause Controls whether or not the user may
|
|||
|
pause display within the
|
|||
|
od_list_files() and od_send_file()
|
|||
|
functions by using the [P] key.
|
|||
|
|
|||
|
od_list_stop Controls whether or not the user may
|
|||
|
terminate display within the
|
|||
|
od_list_files() and od_send_file()
|
|||
|
functions using [S], [CTRL]-[K], etc.
|
|||
|
|
|||
|
od_logfile Enables or disables the OpenDoors log
|
|||
|
file system.
|
|||
|
|
|||
|
od_logfile_disable Prevents the logfile from being opened,
|
|||
|
even if the logfile is enabled by
|
|||
|
od_logfile.
|
|||
|
|
|||
|
od_logfile_messages Array of message strings that OpenDoors
|
|||
|
will use when writing log file entries.
|
|||
|
|
|||
|
od_logfile_name Contains the filename and possibly path
|
|||
|
of the logfile.
|
|||
|
|
|||
|
od_maxtime Indicates the maximum length of time
|
|||
|
any user is permitted to use the door.
|
|||
|
|
|||
|
od_maxtime_deduction Indicates the amount of time that has
|
|||
|
temporarily been taken away from the
|
|||
|
user's remaining time, as a result of
|
|||
|
the maximum door time setting.
|
|||
|
|
|||
|
od_mps Enables or disables the OpenDoors
|
|||
|
Multiple Personality System.
|
|||
|
|
|||
|
od_no_file_func Called when no door information file
|
|||
|
can be read.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 189
|
|||
|
|
|||
|
|
|||
|
od_no_ra_codes Disables translation of RA/QBBS control
|
|||
|
codes.
|
|||
|
|
|||
|
od_nocopyright Prevents OpenDoors from displaying it's
|
|||
|
name and version number when a door
|
|||
|
program begins execution.
|
|||
|
|
|||
|
od_noexit Prevents OpenDoors from exiting when
|
|||
|
the od_exit() function is called.
|
|||
|
|
|||
|
od_page_len Controls length of the sysop page beep.
|
|||
|
|
|||
|
od_page_pausing Enables or disables page pausing in
|
|||
|
od_send_file(), od_hotkey_menu() and
|
|||
|
od_list_files() functions.
|
|||
|
|
|||
|
od_page_startmin Indicates the time of day at which
|
|||
|
sysop paging is first enabled.
|
|||
|
|
|||
|
od_page_statusline Which status line (if any) is activated
|
|||
|
when the user pages the sysop.
|
|||
|
|
|||
|
od_page_endmin Indicates the time of day at which
|
|||
|
sysop paging is disabled.
|
|||
|
|
|||
|
od_prog_name Stores the name of your program.
|
|||
|
|
|||
|
od_prog_version Stores the version number of your
|
|||
|
program.
|
|||
|
|
|||
|
od_prog_copyright Place your copyright information here.
|
|||
|
|
|||
|
od_reg_key Stores the registration key that you
|
|||
|
receive when purchasing OpenDoors.
|
|||
|
|
|||
|
od_reg_name Stores your name or your companies name
|
|||
|
when you have purchased an OpenDoors
|
|||
|
license (registration).
|
|||
|
|
|||
|
od_spawn_freeze_time Indicates whether the user's time
|
|||
|
remaining continues to be decreased
|
|||
|
during the execution of the
|
|||
|
od_spawn...() functions (FALSE), or if
|
|||
|
the timer should be "frozen" (TRUE).
|
|||
|
|
|||
|
od_swapping_disable Disables swapping during DOS shell and
|
|||
|
od_spawn...() functions.
|
|||
|
|
|||
|
od_swapping_noems Prevents swapping form being done to
|
|||
|
EMS expanded memory.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 190
|
|||
|
|
|||
|
od_swapping_path Location where disk swap file should be
|
|||
|
created.
|
|||
|
|
|||
|
od_status_on Controls whether the status line sub-
|
|||
|
system is active.
|
|||
|
|
|||
|
od_time_msg_func Called instead of displaying time limit
|
|||
|
warning messages.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_app HICON od_control.od_app_icon;
|
|||
|
_icon
|
|||
|
Normally, the Win32 version of OpenDoors displays its own icon
|
|||
|
on the application title bar, on the Windows taskbar, and in the
|
|||
|
help|about dialog box. You can supply your own icon by setting
|
|||
|
this variable to point to the handle of the icon, as returned by
|
|||
|
LoadIcon();
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_box char od_control.od_box_chars[8];
|
|||
|
_chars
|
|||
|
This variable allows you to specify which character the
|
|||
|
od_draw_box() function uses in drawing the boarder of a window.
|
|||
|
The elements of this array are as follows:
|
|||
|
|
|||
|
od_box_chars[BOX_UPPERLEFT] - Upper left corner of box
|
|||
|
od_box_chars[BOX_TOP] - Top horizontal line
|
|||
|
od_box_chars[BOX_UPPERRIGHT] - Upper right corner of box
|
|||
|
od_box_chars[BOX_LEFT] - Left Vertical line
|
|||
|
od_box_chars[BOX_LOWERLEFT] - Lower left corner of box
|
|||
|
od_box_chars[BOX_LOWERRIGHT] - Lower right corner of box
|
|||
|
od_box_chars[BOX_BOTTOM] - Bottom horizontal line
|
|||
|
od_box_chars[BOX_RIGHT] - Right horizontal line
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_before void (*od_control.od_before_exit)();
|
|||
|
_exit
|
|||
|
This variable contains a pointer to a function which OpenDoors
|
|||
|
should call prior to exiting, or NULL if you do not wish to have
|
|||
|
any function called at exit time. For an example of the use of
|
|||
|
this variable, see the description of the EX_VOTE.C example
|
|||
|
program, which begins on page 38.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 191
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cafter void (*od_control.od_cafter_chat)();
|
|||
|
_chat
|
|||
|
The function pointed to by this variable will be called after
|
|||
|
sysop chat mode has ended. This may be useful for allowing you
|
|||
|
to save the user's screen contents prior to chat, and restoring
|
|||
|
the afterwards. If this variable contains its default value of
|
|||
|
NULL, no function will be called. To alter the string of text
|
|||
|
which is displayed after sysop chat, see the
|
|||
|
od_control.od_after_chat variable, which is described in the
|
|||
|
section on the prompts customization portion of the control
|
|||
|
structure.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cafter void (*od_control.od_cafter_shell)();
|
|||
|
_shell
|
|||
|
The function pointed to by this variable will be called after
|
|||
|
the sysop has returned from a DOS shell. If this variable
|
|||
|
contains its default value of NULL, no function will be called.
|
|||
|
To alter the string of text which is displayed after a DOS
|
|||
|
shell, see the od_control.od_after_shell variable, which is
|
|||
|
described in the section on the prompts customization portion of
|
|||
|
the control structure.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cbefore void (*od_control.od_cbefore_chat)();
|
|||
|
_chat
|
|||
|
The function pointed to by this variable will be called prior to
|
|||
|
entering sysop chat mode. This may be useful for allowing you to
|
|||
|
save the user's screen contents prior to chat, and restoring the
|
|||
|
afterwards. If this variable contains its default value of NULL,
|
|||
|
no function will be called. To alter the string of text which is
|
|||
|
displayed prior to sysop chat, see the od_control.od_before_chat
|
|||
|
variable, which is described in the section on the prompts
|
|||
|
customization portion of the control structure. To replace the
|
|||
|
OpenDoors sysop chat facility with your own, simply activate
|
|||
|
your chat mode when this function is called. Your chat mode
|
|||
|
facility should remain active until OpenDoors sets the
|
|||
|
od_control.od_chat_active variable to FALSE. If you wish to
|
|||
|
terminate chat mode prior to this variable being set to FALSE,
|
|||
|
you should set this variable to FALSE yourself if you do not
|
|||
|
wish OpenDoors to activate its own chat mode.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 192
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cbefore void (*od_control.od_cbefore_shell)();
|
|||
|
_shell
|
|||
|
The function pointed to by this variable will be called prior to
|
|||
|
executing a sysop DOS shell. If this variable contains its
|
|||
|
default value of NULL, no function will be called. To alter the
|
|||
|
string of text which is displayed before a DOS shell, see the
|
|||
|
od_control.od_before_shell variable, which is described in the
|
|||
|
section on the prompts customization portion of the control
|
|||
|
structure.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cfg_lines char od_control.cfg_lines[25][33];
|
|||
|
|
|||
|
This array contains the strings for the keywords that represent
|
|||
|
various lines in the definition of a custom door information
|
|||
|
file. Each keyword must be 32 character or less in length. These
|
|||
|
keywords are not case sensitive. See page 230 for more
|
|||
|
information on defining custom door information (drop) file
|
|||
|
formats. The default values for this array are as follows:
|
|||
|
|
|||
|
[0] "Ignore"
|
|||
|
[1] "ComPort"
|
|||
|
[2] "FossilPort"
|
|||
|
[3] "ModemBPS"
|
|||
|
[4] "LocalMode"
|
|||
|
[5] "UserName"
|
|||
|
[6] "UserFirstName"
|
|||
|
[7] "UserLastName"
|
|||
|
[8] "Alias"
|
|||
|
[9] "HoursLeft"
|
|||
|
[10] "MinutesLeft"
|
|||
|
[11] "SecondsLeft"
|
|||
|
[12] "ANSI"
|
|||
|
[13] "AVATAR"
|
|||
|
[14] "PagePausing"
|
|||
|
[15] "ScreenLength"
|
|||
|
[16] "ScreenClearing"
|
|||
|
[17] "Security"
|
|||
|
[18] "City"
|
|||
|
[19] "Node"
|
|||
|
[20] "SysopName"
|
|||
|
[21] "SysopFirstName"
|
|||
|
[22] "SysopLastName"
|
|||
|
[23] "SystemName"
|
|||
|
[24] "RIP"
|
|||
|
|
|||
|
If you wish to change any of these variable, you must do so
|
|||
|
before calling any OpenDoors functions.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 193
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_cfg_text char od_control.od_cfg_text[47][33];
|
|||
|
|
|||
|
This array of strings contains the built-in configuration file
|
|||
|
keywords that are recognized by OpenDoors. These keywords may be
|
|||
|
up to 32 characters in size, and are not case sensitive. If you
|
|||
|
wish to change any of these settings, you must do so before
|
|||
|
calling any OpenDoors functions. The default values for this
|
|||
|
array are as follows:
|
|||
|
|
|||
|
[0] "Node"
|
|||
|
[1] "BBSDir"
|
|||
|
[2] "DoorDir"
|
|||
|
[3] "LogFileName"
|
|||
|
[4] "DisableLogging"
|
|||
|
[5] "SundayPagingHours"
|
|||
|
[6] "MondayPagingHours"
|
|||
|
[7] "TuesdayPagingHours"
|
|||
|
[8] "WednesdayPagingHours"
|
|||
|
[9] "ThursdayPagingHours"
|
|||
|
[10] "FridayPagingHours"
|
|||
|
[11] "SaturdayPagingHours"
|
|||
|
[12] "MaximumDoorTime"
|
|||
|
[13] "SysopName"
|
|||
|
[14] "SystemName"
|
|||
|
[15] "SwappingDisable"
|
|||
|
[16] "SwappingDir"
|
|||
|
[17] "SwappingNoEMS"
|
|||
|
[18] "LockedBPS"
|
|||
|
[19] "SerialPort"
|
|||
|
[20] "CustomFileName"
|
|||
|
[21] "CustomFileLine"
|
|||
|
[22] "InactivityTimeout"
|
|||
|
[23] "PageDuration"
|
|||
|
[24] "ChatUserColor"
|
|||
|
[25] "ChatSysopColor"
|
|||
|
[26] "FileListTitleColor"
|
|||
|
[27] "FileListNameColor"
|
|||
|
[28] "FileListSizeColor"
|
|||
|
[29] "FileListDescriptionColor"
|
|||
|
[30] "FileListOfflineColor"
|
|||
|
[31] "Personality"
|
|||
|
[32] "NoFossil"
|
|||
|
[33] "PortAddress"
|
|||
|
[34] "PortIRQ"
|
|||
|
[35] "ReceiveBuffer"
|
|||
|
[36] "TransmitBuffer"
|
|||
|
[37] "PagePromptColor"
|
|||
|
[38] "LocalMode"
|
|||
|
[39] "PopupMenuTitleColor"
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 194
|
|||
|
|
|||
|
[40] "PopupMenuBorderColor"
|
|||
|
[41] "PopupMenuTextColor"
|
|||
|
[42] "PopupMenuKeyColor"
|
|||
|
[43] "PopupMenuHighlightColor"
|
|||
|
[44] "PopupMenuHighKeyColor"
|
|||
|
[45] "NoFIFO"
|
|||
|
[46] "FIFOTriggerSize"
|
|||
|
[47] "DiableDTR"
|
|||
|
[48] "NoDTRDisable"
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_chat char od_control.od_chat_active;
|
|||
|
_active
|
|||
|
This variable is set to TRUE when sysop chat mode is active, and
|
|||
|
is set to FALSE when sysop chat mode is not active. This
|
|||
|
variable can be used to determine whether or not chat mode is
|
|||
|
active, and to force chat mode to end. When the sysop presses
|
|||
|
the chat mode key ([ALT]-[C] if the default personality is being
|
|||
|
used) while chat mode is active, this variable is set to FALSE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_clear char od_control.od_clear_on_exit;
|
|||
|
_on_exit
|
|||
|
This variable contains a Boolean value, which indicates whether
|
|||
|
or not you wish OpenDoors to clear the screen prior to exiting.
|
|||
|
This variable defaults to a value of TRUE, which causes the
|
|||
|
screen to be cleared when a door program exits. However, you may
|
|||
|
wish to set this variable to a value of FALSE, which will cause
|
|||
|
the contents of the screen to remain unchanged when the door
|
|||
|
exits. While setting this variable to FALSE will probably result
|
|||
|
in a messy display if the door is to return control to a batch
|
|||
|
file, if the door returns directly to the BBS, it will result in
|
|||
|
a smoother transition from the door back to the BBS (as the
|
|||
|
sysop is not left with a blank screen). If your door has a
|
|||
|
configuration file or configuration program, you may wish to
|
|||
|
have an option which will allow the individual sysop to
|
|||
|
determine whether or not the screen should be cleared when the
|
|||
|
door exits.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_color char od_control.od_color_delimiter;
|
|||
|
_delimiter
|
|||
|
This variable sets the character that is used to delimit color
|
|||
|
codes in the od_printf() function, and defaults to the back-
|
|||
|
quote (`) character. If you wish to be able to display the back-
|
|||
|
quote (`) character using the od_printf() function, and thus
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 195
|
|||
|
|
|||
|
wish to use a different character to delimit color codes in the
|
|||
|
od_printf() function, simply set this variable to the
|
|||
|
alternative character you wish to use. If you wish to disable
|
|||
|
the imbedded color codes feature of the od_printf() function,
|
|||
|
simply set this variable to a value of zero. For more
|
|||
|
information on od_printf() imbedded color codes, see the
|
|||
|
description of the od_printf() function, which begins on page
|
|||
|
110.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_color char od_control.od_color_names[12][33];
|
|||
|
_names
|
|||
|
This array sets the strings that OpenDoors will recognize as
|
|||
|
color description keywords. These are the keywords that can be
|
|||
|
imbedded in od_printf() format strings, and are also the
|
|||
|
keywords that can be used to change color settings in the
|
|||
|
OpenDoors configuration file. If you wish to change these
|
|||
|
keywords, you will normally do so before calling any OpenDoors
|
|||
|
functions. These keywords should always be supplied in upper-
|
|||
|
case characters. The defaults values for this array are as
|
|||
|
follows:
|
|||
|
|
|||
|
[0] "BLACK"
|
|||
|
[1] "BLUE"
|
|||
|
[2] "GREEN"
|
|||
|
[3] "CYAN"
|
|||
|
[4] "RED"
|
|||
|
[5] "MAGENTA"
|
|||
|
[6] "YELLOW"
|
|||
|
[7] "WHITE"
|
|||
|
[8] "BROWN"
|
|||
|
[9] "GREY"
|
|||
|
[10] "BRIGHT"
|
|||
|
[11] "FLASHING"
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_config void (*od_control.od_config_file)(void);
|
|||
|
_file
|
|||
|
Set this variable to INCLUDE_CONFIG_FILE to enable the OpenDoors
|
|||
|
configuration file system, or set it to NO_CONFIG_FILE to
|
|||
|
disable the configuration file system. This variable should only
|
|||
|
be set prior to your first call to an OpenDoors function. For
|
|||
|
more information on the OpenDoors configuration file system, see
|
|||
|
page 224.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 196
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_config char *od_control.od_config_filename;
|
|||
|
_filename
|
|||
|
If set, this variable should point to a string containing the
|
|||
|
filename that you wish the OpenDoors configuration file system
|
|||
|
to read. If this variable has its default value of NULL, the
|
|||
|
filename DOOR.CFG will be used by default.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_config void (*od_control.od_config_function)(char *keyword, char
|
|||
|
_function *options);
|
|||
|
|
|||
|
If set, this variable should point to the function that
|
|||
|
OpenDoors should call when lines with unrecognized keywords are
|
|||
|
encountered in the configuration file. This allows you to add
|
|||
|
your own configuration file keywords. The first parameter to
|
|||
|
this function will be a pointer to a string containing the
|
|||
|
unrecognized keywords, and the second parameter will be a
|
|||
|
pointer to a string containing any options that were specified
|
|||
|
after the keyword. If no options were specified after the
|
|||
|
keyword, this string will have a length of 0.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_default void (*od_control.od_default_personality)(unsigned char
|
|||
|
_personality operation);
|
|||
|
|
|||
|
This variable sets the default personality that OpenDoors will
|
|||
|
use if the multiple personality system is active. If the
|
|||
|
multiple personality system is not active, the personality set
|
|||
|
by this variable will be the only personality available. This
|
|||
|
variable should only be set prior to calling an OpenDoors
|
|||
|
function. This variable can be set to point to your own
|
|||
|
personality function, or it can be set to one of the manifest
|
|||
|
constants that represent one of the built-in personalities:
|
|||
|
|
|||
|
PER_OPENDOORS
|
|||
|
PER_PCBOARD
|
|||
|
PER_RA
|
|||
|
PER_WILDCAT
|
|||
|
|
|||
|
For more information on the OpenDoors Multiple Personality
|
|||
|
System, see page 230.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 197
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_default char od_control.od_default_rip_win;
|
|||
|
_rip_win
|
|||
|
This variable defaults to FALSE. When set to FALSE, OpenDoors
|
|||
|
resets the RIP text window to a 23-line window that is most
|
|||
|
appropriate for doors that support both RIP-graphics and non-RIP
|
|||
|
mode. When this variable is set to TRUE, OpenDoors will use the
|
|||
|
default sized text output window, 43 lines in size.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_disable unsigned int od_control.od_disable;
|
|||
|
|
|||
|
This variable is a bit-mapped flag which can be used to disable
|
|||
|
certain OpenDoors features which are normally active, in order
|
|||
|
to allow for maximum customization of OpenDoors. Each bit of
|
|||
|
this variable represents a different feature that can be
|
|||
|
disabled. To DISABLE a feature, you set the bit that corresponds
|
|||
|
to the particular feature. To ENABLE the feature, the bit is
|
|||
|
reset. Each bit is represented by a keyword, as follows:
|
|||
|
|
|||
|
DIS_INFOFILE - Setting the DIS_INFOFILE bit of the
|
|||
|
od_control.od_disable variable allows you to prevent
|
|||
|
OpenDoors from reading or re-writing a door information
|
|||
|
file. If you wish to disable OpenDoors' reading of the door
|
|||
|
information file, you must do so prior to calling
|
|||
|
od_init() or any other OpenDoors door-driver functions. At
|
|||
|
the same time, you must also manually set any required
|
|||
|
variables that are normally set by the information obtained
|
|||
|
from the door information file, such as the comm port
|
|||
|
number, baud rate, user name, and so on. You may wish to
|
|||
|
disable reading of the door information file in a number of
|
|||
|
cases. For example, you may wish to manually read another
|
|||
|
format of door information file not supported by OpenDoors,
|
|||
|
or to obtain the necessary door information from your
|
|||
|
program's command line. Also, if you are using OpenDoors to
|
|||
|
write a non-door communications program, such as a terminal
|
|||
|
program, you want to prevent OpenDoors from attempting to
|
|||
|
read a door information file on startup.
|
|||
|
|
|||
|
DIS_CARRIERDETECT - Setting this bit allows you to prevent
|
|||
|
OpenDoors from exiting when it the carrier detect signal
|
|||
|
from the modem disappears. This bit may be set or rest at
|
|||
|
any time. If you use this bit to disable OpenDoors' carrier
|
|||
|
detection, you will probably want to monitor the state of
|
|||
|
the carrier detect signal yourself, using the od_carrier()
|
|||
|
function, which is described on page 51.
|
|||
|
|
|||
|
DIS_TIMEOUT - This flag allows you to prevent OpenDoors from
|
|||
|
exiting when the user runs out of time. As with the
|
|||
|
DIS_CARRIERDETECT flag, you may set or reset this bit at
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 198
|
|||
|
|
|||
|
any time. You will most often want to use this setting when
|
|||
|
writing a non-door program, which you would not want to
|
|||
|
have exit after a particular amount of time has elapsed. Be
|
|||
|
sure that you do not confuse this flag with the user's
|
|||
|
inactivity timeout. To disable the inactivity timeout, set
|
|||
|
the do_control.od_inactivity variable to 0.
|
|||
|
|
|||
|
DIS_LOCAL_OVERRIDE - This setting affects OpenDoors' behavior
|
|||
|
when a locked BPS rate is specified in the configuration
|
|||
|
file, and another BPS rate is specified in the door
|
|||
|
information file. By default, OpenDoors will initialize the
|
|||
|
modem at the BPS rate specified in the configuration file,
|
|||
|
unless the BPS rate specified in the door information file
|
|||
|
is 0. In this case, the 0 BPS rate is used to indicate that
|
|||
|
the door is operating in local mode, and will override the
|
|||
|
BPS rate specified in the configuration file. Setting this
|
|||
|
flag disables the local mode override, causing the modem to
|
|||
|
always be initialized at the locked BPS rate, even when the
|
|||
|
door information file specifies that local mode should be
|
|||
|
used.
|
|||
|
|
|||
|
DIS_BPS_SETTING - When used with a FOSSIL driver, OpenDoors
|
|||
|
normally changes the BPS rate to that passed from the BBS
|
|||
|
(if the BBS passes a valid FOSSIL BPS rate). Setting the
|
|||
|
DIS_BPS_SETTING flag disables this BPS rate setting.
|
|||
|
|
|||
|
DIS_LOCAL_INPUT - The local keyboard may be disabled by setting
|
|||
|
this bit. This only affects the sysop's input in
|
|||
|
circumstances that input is also accepted from the remote
|
|||
|
user; this setting has no effect on the sysop function
|
|||
|
keys.
|
|||
|
|
|||
|
DIS_SYSOP_KEYS - This setting also disables the local keyboard.
|
|||
|
However, unlike the DIS_LOCAL_INPUT, this function disables
|
|||
|
both sysop function keys and door input from the local
|
|||
|
keyboard.
|
|||
|
|
|||
|
DIS_DTR_DISABLE - This setting prevents OpenDoors from
|
|||
|
disabiling DTR response from the modem. Even if not
|
|||
|
specified, OpenDoors only disables DTR response in the when
|
|||
|
exiting under the Win32 version if an open serial port
|
|||
|
handle was not provided to OpenDoors at startup.
|
|||
|
|
|||
|
DIS_NAME_PROMPT - Prevents OpenDoors from prompting for a user
|
|||
|
name when operating in automatic local mode (by setting
|
|||
|
od_force_local to TRUE or specifying -local on the command
|
|||
|
line).
|
|||
|
|
|||
|
Note that in order to disable the OpenDoors status line, the
|
|||
|
od_control.od_status_on variable is used, instead of the
|
|||
|
od_disable variable. You may also disable the user's inactivity
|
|||
|
timeout by setting the od_control.od_inactivity variable to 0.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 199
|
|||
|
|
|||
|
The od_control.od_status_on variable is described later in this
|
|||
|
section.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_disable_ char od_control.od_disable_dtr[40];
|
|||
|
dtr
|
|||
|
Unles the DIS_DTR_DISABLE od_disable flag is set, the Win32
|
|||
|
version of OpenDoors will attempt to disable DTR response by the
|
|||
|
modem when closing the serial port, if the serial port was
|
|||
|
opened by OpenDoors. This is done by sending a series of
|
|||
|
commands to the modem, and possibly waiting for responses to the
|
|||
|
command. The string format specifies each command, followed by
|
|||
|
the required response. The command and response is separated by
|
|||
|
a single space character. If no response is required between two
|
|||
|
commands, then those commands may be separated by two space
|
|||
|
characters. A '|' character is translated into a carriage
|
|||
|
return, and a '~' character is translated into a one second
|
|||
|
pause. The default value of this string is "~+++~ AT&D0 ATO".
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_emu_ BOOL od_control.od_emu_simulate_modem;
|
|||
|
simulate_modem
|
|||
|
When this flag is set to its default value of FALSE, the
|
|||
|
OpenDoors terminal emulator displays text at full speed. When
|
|||
|
this flag is set to TRUE, the emulation functions will display
|
|||
|
text at approximately the same speed as it would be displayed
|
|||
|
when sent over the modem, based on the current connect speed. In
|
|||
|
local mode, an average modem speed of 9600bps is assumed. This
|
|||
|
allows animations to be displayed locally at the same speed as
|
|||
|
they would appear on the remote system. This switch affects the
|
|||
|
following functions:
|
|||
|
od_disp_emu()
|
|||
|
od_send_file()
|
|||
|
od_hotkey_menu()
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od unsigned char od_control.od_errorlevel[8];
|
|||
|
_errorlevel
|
|||
|
Allows you to configure the errorlevel (program exit code) which
|
|||
|
OpenDoors exits with under various circumstances. The elements
|
|||
|
of this array are as follows:
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 200
|
|||
|
|
|||
|
[ERRORLEVEL_ENABLE] Enables or disables custom errorlevels
|
|||
|
[ERRORLEVEL_CRITICAL] Critical error errorlevel
|
|||
|
[ERRORLEVEL_NOCARRIER] Carrier lost errorlevel
|
|||
|
[ERRORLEVEL_HANGUP] Sysop manually terminated call
|
|||
|
[ERRORLEVEL_TIMEOUT] User time expired errorlevel
|
|||
|
[ERRORLEVEL_INACTIVITY] Keyboard inactivity timeout errorlevel
|
|||
|
[ERRORLEVEL_DROPTOBBS] Sysop returned user to BBS errorlevel
|
|||
|
[ERRORLEVEL_NORMAL] Door has exited normally
|
|||
|
|
|||
|
If you wish to override the default errorlevels used by
|
|||
|
OpenDoors, you should set element [ERRORLEVEL_ENABLE] of this
|
|||
|
array to TRUE, and set the remaining array elements to the
|
|||
|
appropriate errorlevels. Note that the settings in this array
|
|||
|
only affect the errorlevels which OpenDoors uses when it causes
|
|||
|
the door to exit for one of the reasons listed above. This
|
|||
|
setting has no effect on the errorlevel returned when your
|
|||
|
program explicitly exits by calling the od_exit() function, or
|
|||
|
your program returns by calling exit() or returning from the
|
|||
|
main() function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od char od_control.od_force_local;
|
|||
|
_force_local
|
|||
|
This variable defaults to FALSE, which causes OpenDoors to
|
|||
|
behave normally. When this variable is set to TRUE prior to
|
|||
|
calling od_init() or any other OpenDoors functions, OpenDoors
|
|||
|
will operate in local mode. In this case, no door information
|
|||
|
file will be read. Also, the user name will be used if
|
|||
|
od_control.user_name has not been set prior to calling od_init()
|
|||
|
or the first OpenDoors function.
|
|||
|
|
|||
|
The default OpenDoors settings when od_control.od_force_local is
|
|||
|
set are as follows:
|
|||
|
|
|||
|
- ANSI mode is on
|
|||
|
- Time limit is 60 minutes
|
|||
|
- User's location is the name of the BBS, or "Unknown Location"
|
|||
|
otherwise if BBS name is not known.
|
|||
|
- User name is set to sysop's name ("Sysop" if no sysop name is
|
|||
|
specified in the configuration file).
|
|||
|
|
|||
|
You may wish to add a "-local" type parameter to your program's
|
|||
|
command line, which will permit the sysop to easily operate the
|
|||
|
door in local mode, as an interface to the
|
|||
|
od_control.od_force_local setting.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_help void (*od_control.od_help_callback)(void);
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 201
|
|||
|
|
|||
|
_callback
|
|||
|
If this variable is set to a non-NULL value, the Win32 version
|
|||
|
of OpenDoors will provide a Contents item on the help menu, and
|
|||
|
call the function pointed to by this variable when the user
|
|||
|
chooses the Contents menu item.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_in_buf unsigned int od_control.od_in_buf_size;
|
|||
|
_size
|
|||
|
Specifies the size, in characters, of the OpenDoor's internal
|
|||
|
local/remote inbound buffer size. Two bytes of storage are
|
|||
|
required for each character in this buffer. This variable should
|
|||
|
only be changed prior to calling od_init() or the first
|
|||
|
OpenDoors function. If not set, this variable defaults to a
|
|||
|
value of 256.
|
|||
|
|
|||
|
The buffer corresponding to this variable should not be confused
|
|||
|
with the FOSSIL or internal communications receive buffer (which
|
|||
|
is set by od_control.od_com_rx_buf). Unlike the serial I/O
|
|||
|
receive buffer, which is used only for characters received from
|
|||
|
the remote system, this buffer serves as a queue for input from
|
|||
|
both the remote system and the local keyboard. If you find that
|
|||
|
characters are lost when information is being set to your door
|
|||
|
from the user, you may wish to increase the size of this buffer.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od unsigned int od_control.od_inactivity;
|
|||
|
_inactivity
|
|||
|
OpenDoors has a built in user-inactivity timeout facility, which
|
|||
|
will automatically disconnect a user who appears .to be sleeping
|
|||
|
at the keyboard. If the user has not pressed any keys on their
|
|||
|
keyboard for to great a length of time, they will be warned that
|
|||
|
they are about to be disconnected due to inactivity. If they
|
|||
|
still do not respond after another few seconds, OpenDoors will
|
|||
|
automatically disconnect the user and return control to the BBS
|
|||
|
software. The od_control.od_inactivity variable allows you to
|
|||
|
set the maximum length of time, in seconds, after which the user
|
|||
|
will be disconnected for inactivity. This variable defaults to a
|
|||
|
value of 200 seconds. You may disable OpenDoors' inactivity
|
|||
|
timeout altogether, by setting the od_control.od_inactivity
|
|||
|
variable to a value of 0.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 202
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_inactive int od_control.od_inactive_warning.
|
|||
|
_warning
|
|||
|
This variable sets the number of seconds prior to hanging up
|
|||
|
that OpenDoors displays the inactivity timeout warning. This
|
|||
|
variable should only be changed after your first call to an
|
|||
|
OpenDoors API function. If not explicitly set by your program,
|
|||
|
this setting defaults to 10 seconds.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_ker_exec void (*od_control.od_ker_exec)(void);
|
|||
|
|
|||
|
When od_control.od_ker_exec is set to point to a function,
|
|||
|
OpenDoors will call this function whenever od_kernel() executes.
|
|||
|
This provides any easy way for you to perform your own
|
|||
|
processing on a regular basis during door execution. The
|
|||
|
od_control.od_ker_exec variable defaults to NULL.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_last char od_control.od_last_input;
|
|||
|
_input
|
|||
|
Indicates whether the last key retrieved using the od_get_key()
|
|||
|
function originated from the remote user, or the local sysop. If
|
|||
|
the input originated from the remote, this variable is set to 0.
|
|||
|
If the input originated from the local keyboard, this variables
|
|||
|
is set to 1.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_list char od_control.od_list_pause;
|
|||
|
_pause
|
|||
|
This variable contains a Boolean value, which allows you to
|
|||
|
control whether or not the user may pause displaying within the
|
|||
|
od_list_files() and od_send_file() function. When this variable
|
|||
|
is set to its default value of TRUE, the user will be able to
|
|||
|
pause the display by pressing the [P] key, and resume display by
|
|||
|
pressing any other key. However, the pause feature may be
|
|||
|
disabled by setting this variable to FALSE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_list char od_control.od_list_stop;
|
|||
|
_stop
|
|||
|
This variable contains a Boolean value, which allows you to
|
|||
|
control whether or not the user may abort displaying within the
|
|||
|
od_list_files() and od_send_file() function. When this variable
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 203
|
|||
|
|
|||
|
is set to its default value of TRUE, the user will be able to
|
|||
|
pause the display by pressing the [S], [CTRL]-[K] or [CTRL]-[C]
|
|||
|
keys. However, the stop feature may be disabled by setting this
|
|||
|
variable to FALSE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_local void (*od_control.od_local_input)(int);
|
|||
|
_input
|
|||
|
If set, this function is called whenever the sysop presses a
|
|||
|
non-sysop-function key on the local keyboard. The key pressed is
|
|||
|
passed to the function in the single int parameter that it
|
|||
|
accepts.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_logfile void *(od_control.od_logfile)(void);
|
|||
|
|
|||
|
To make the OpenDoors log file system available in your program,
|
|||
|
set this variable to INCLUDE_LOGFILE, prior to calling any
|
|||
|
OpenDoors functions. If not set, or if set to NO_LOGFILE, the
|
|||
|
OpenDoors log file system will not automatically be enabled.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_logfile char od_control.od_logfile_disable;
|
|||
|
_disable
|
|||
|
This variable defaults to the value of FALSE, unless the
|
|||
|
"LogfileDisable" option is specified in the configuration file,
|
|||
|
in which case the variable will be set to TRUE. If this variable
|
|||
|
is set to TRUE, OpenDoors will not write to a logfile, even if
|
|||
|
the logfile system is enabled using od_control.od_logfile.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_logfile char *od_control.od_logfile_messages[14];
|
|||
|
_messages
|
|||
|
This array of pointers to strings contains the messages that
|
|||
|
OpenDoors will automatically write to the log file, if the log
|
|||
|
file system is enabled. If you wish to change the settings of
|
|||
|
this array, you should do so before calling any OpenDoors
|
|||
|
functions. The default strings for this array are as follows:
|
|||
|
|
|||
|
[0] "Carrier lost, exiting door"
|
|||
|
[1] "System operator terminating call, exiting door"
|
|||
|
[2] "User's time limit expired, exiting door"
|
|||
|
[3] "User keyboard inactivity time limit exceeded, exiting door"
|
|||
|
[4] "System operator returning user to BBS, exiting door"
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 204
|
|||
|
|
|||
|
[5] "Exiting door with errorlevel %d,
|
|||
|
[6] "Invoking operating system shell"
|
|||
|
[7] "Returning from operating system shell"
|
|||
|
[8] "User paging system operator"
|
|||
|
[9] "Entering sysop chat mode"
|
|||
|
[10] "Terminating sysop chat mode"
|
|||
|
[11] "%s entering door"
|
|||
|
[12] "Reason for chat: %s"
|
|||
|
[13] "Exiting door"
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_logfile char od_control.od_logfile_name[80];
|
|||
|
_name
|
|||
|
This variable specifies the filename, and optionally the full
|
|||
|
path of the logfile where OpenDoors should perform logging. This
|
|||
|
variable only has an effect when set prior to calling any
|
|||
|
OpenDoors functions. If the log file name is specified in the
|
|||
|
configuration file, that name will be stored in this variable.
|
|||
|
If you do not set this variable, and the log file name is not
|
|||
|
specified in the configuration file, the default name "DOOR.LOG"
|
|||
|
will be used. If you wish to set this variable, you should do so
|
|||
|
prior to calling od_init() or any OpenDoors function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_ unsigned int od_control.od_maxtime;
|
|||
|
maxtime
|
|||
|
This variable specifies the maximum length of time that any user
|
|||
|
is permitted to use the door, and is normally set from a
|
|||
|
configuration file option. If upon entering the door, the user's
|
|||
|
time remaining online is greater than the od_maxtime setting,
|
|||
|
their time remaining is temporarily decreased to the maximum
|
|||
|
value. Then upon exit of the door, the number of subtracted
|
|||
|
minutes is added back onto the user's remaining time. If the
|
|||
|
user's remaining time is less than this value, then the setting
|
|||
|
has no effect. A value of 0 disables the maximum time setting
|
|||
|
altogether.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_maxtime int od_control.od_maxtime_deduction;
|
|||
|
_deduction
|
|||
|
This variable store the amount of time that should be added to
|
|||
|
the user's time upon exit of the door, as a result of the
|
|||
|
maximum time deduction, described above. If the maximum time
|
|||
|
feature is not used, this variable will be given a value of 0.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 205
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_mps void (*od_control.od_mps)(void);
|
|||
|
|
|||
|
To make the OpenDoors Multiple Personality system available in
|
|||
|
your program, set this variable to INCLUDE_MPS before calling
|
|||
|
any OpenDoors functions. If this variable is not set, or is set
|
|||
|
to NO_MPS, the Multiple Personality System will be disabled. For
|
|||
|
more information on the OpenDoors Multiple Personality System,
|
|||
|
see page 233.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_no_ void (*od_control.od_no_file_func)();
|
|||
|
file_func
|
|||
|
If od_no_file_func is set to point to a function, that function
|
|||
|
will be called whenever a door information (drop) file cannot be
|
|||
|
located or read. This provides an easy mechanism to add your own
|
|||
|
door information file reader, or to provide a local login prompt
|
|||
|
when no drop file is present. If you wish the door to operate in
|
|||
|
local mode, you should set od_control.od_force_local to TRUE
|
|||
|
prior to returning from your function. If you have successfully
|
|||
|
read your own door information file format, you should set
|
|||
|
od_control.od_info_type to CUSTOM. If neither of these variables
|
|||
|
are set by the od_no_file_function, OpenDoors will report that
|
|||
|
it is unable to find or read a door information file and will
|
|||
|
exit immediately.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_no_ra char od_control.od_no_ra_codes;
|
|||
|
_codes
|
|||
|
This variable defaults to FALSE. When set to TRUE, the
|
|||
|
translation of the RemoteAccess/QuickBBS control codes by the
|
|||
|
functions od_send_file(), od_hotkey_menu() and od_disp_emu() is
|
|||
|
disabled.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_ char od_control.od_nocopyright;
|
|||
|
nocopyright
|
|||
|
This variable is a Boolean value that allows you to prevent
|
|||
|
OpenDoors from displaying its name, version number, copyright
|
|||
|
notice and registration information when the program begins
|
|||
|
execution. Set this variable to TRUE to disable the display of
|
|||
|
copyright and associated information. When this variable is set
|
|||
|
to TRUE, OpenDoors also does not change the initial display
|
|||
|
color on startup. For obvious reasons, this variable does not
|
|||
|
take effect when OpenDoors is operating in unregistered mode.
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 206
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_noexit char od_control.od_noexit;
|
|||
|
|
|||
|
This variable contains a Boolean value, which allows you to
|
|||
|
prevent OpenDoors from exiting when shutting down. This may be
|
|||
|
useful when you want to have your program to do more processing
|
|||
|
after you have called the od_exit() function, or if you do not
|
|||
|
wish to have your program exit automatically when the user drops
|
|||
|
carrier. Normally, this variable will default to a value of
|
|||
|
FALSE, indicating that OpenDoors will exit normally when the
|
|||
|
od_exit() function is called. However, you may optionally set
|
|||
|
this variable to TRUE after od_init() or some OpenDoors function
|
|||
|
has been called. In this case, when the od_exit() function is
|
|||
|
called, either by your program manually, or automatically by
|
|||
|
OpenDoors in response to the user dropping carrier, etc.,
|
|||
|
OpenDoors will not exit. However, the normal operations of
|
|||
|
closing the serial port and re-writing the door information file
|
|||
|
will be carried out. If you set the od_noexit variable to TRUE,
|
|||
|
you will probably have to provide some mechanism to allow your
|
|||
|
program to detect when OpenDoors shutdowns due to the loss of
|
|||
|
carrier, etc. The best way of doing this is to provide a
|
|||
|
function which is to be called at the beginning of the od_exit()
|
|||
|
function, by setting the od_control.od_before_exit pointer,
|
|||
|
described above.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_page char od_control.od_page_len;
|
|||
|
_len
|
|||
|
This variable allows you to control the length, in seconds, of
|
|||
|
the sysop page beep produced when the user pages the sysop via
|
|||
|
the od_page() function.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_page char od_control.od_page_pausing;
|
|||
|
_pausing
|
|||
|
This variable contains a Boolean value that indicates whether or
|
|||
|
not page pausing is enabled in the od_send_file(),
|
|||
|
od_hotkey_menu() and od_list_files() functions. The default
|
|||
|
value of TRUE indicates that page pausing is enabled. A value of
|
|||
|
FALSE indicates that page pausing is disabled.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 207
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_page int od_control.od_pagestartmin;
|
|||
|
startmin int od_control.od_pageendmin;
|
|||
|
|
|||
|
od_page These variables indicate the start and end times for sysop
|
|||
|
endmin paging, expressed as the number of minutes past midnight.
|
|||
|
Sysop paging will be available through the od_page() function
|
|||
|
from the start time, up to but not including the end time.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_page char od_control.od_page_statusline;
|
|||
|
_statusline
|
|||
|
This variable controls which status line, if any, is activated
|
|||
|
when the user pages the system operator (via the od_page()
|
|||
|
function). A value between 0 and 9 causes the corresponding
|
|||
|
status line to be activated. A value of -1 prevents any change
|
|||
|
from being made to the current status line setting. This
|
|||
|
variable will normally be set by personality functions (see page
|
|||
|
233).
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_prog_ char od_control.od_prog_copyright[40];
|
|||
|
copyright
|
|||
|
This variable should contain your program's copyright notice,
|
|||
|
such as "(C) Copyright 1996 by Your Name". This information is
|
|||
|
used in the Help|about dialog box under the Win32 version of
|
|||
|
OpenDoors, and may be used in other places in future versions of
|
|||
|
OpenDoors.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_prog_name char od_control.od_prog_name[40];
|
|||
|
|
|||
|
This variable should contain the full name of your program, up
|
|||
|
to 39 characters. If not set, OpenDoors will use the string
|
|||
|
"OpenDoors" in place of this variable. If used, this variable
|
|||
|
should be set prior to calling any OpenDoors functions, and
|
|||
|
should not include your program's version number. This
|
|||
|
information is used to write your program's name in the log file
|
|||
|
and to indicate your program's name on various windows, among
|
|||
|
other places.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 208
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_prog_version char od_control.od_prog_version[40];
|
|||
|
|
|||
|
This variable should contain the version information of your
|
|||
|
program. If used, this variable should be set prior to calling
|
|||
|
any OpenDoors functions. This information is used in the
|
|||
|
Help|About dialog box under the Win32 version of OpenDoors,
|
|||
|
among other places.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_reg_key unsigned log od_control.od_reg_key;
|
|||
|
|
|||
|
When you purchase an OpenDoors licence (registration), this
|
|||
|
variable should be set to your registration key, prior to
|
|||
|
calling any OpenDoors functions.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_reg_name char od_control.od_reg_name[36];
|
|||
|
|
|||
|
When you purchase an OpenDoors licence (registration), this
|
|||
|
variable should be set to your name, or your company's name, as
|
|||
|
is listed in your OpenDoors registration record.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_spawn char od_control.od_spawn_freeze_time;
|
|||
|
_freeze_time
|
|||
|
This variable is a Boolean value which indicates whether or not
|
|||
|
the user's time remaining is frozen during the execution of one
|
|||
|
of the od_spawn...() functions. If this variable is set to TRUE,
|
|||
|
the user's time remaining will not decrease during the time that
|
|||
|
the od_spawn...() function is executing. However, if this
|
|||
|
variable is set to FALSE, the user's time remaining will
|
|||
|
continue to be subtracted during the execution of the
|
|||
|
od_spawn...() function. The default value of this variable is
|
|||
|
FALSE.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_swapping char od_control.od_swapping_disable;
|
|||
|
_disable
|
|||
|
This variable is a Boolean value which specifies whether or not
|
|||
|
OpenDoors will attempt to swap itself and your entire door upon
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 209
|
|||
|
|
|||
|
DOS shell or a call to one of the od_spawn...() functions. This
|
|||
|
variable defaults to FALSE. If set to TRUE, OpenDoors will not
|
|||
|
attempt to perform swapping activities.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_swapping char od_control.od_swapping_noems;
|
|||
|
_noems
|
|||
|
This variable is a Boolean value which can be used to prevent
|
|||
|
OpenDoors from swapping to EMS memory. This variable defaults to
|
|||
|
the value FALSE. If set to TRUE, OpenDoors will not attempt to
|
|||
|
use EMS memory for swapping, and will only swap to disk.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_swapping char od_control.od_swapping_path;
|
|||
|
_path
|
|||
|
This variable specifies the drive and directory where OpenDoors
|
|||
|
should create its disk swapping file, if applicable. More than
|
|||
|
one path can be specified, by separating the paths with a semi-
|
|||
|
colon (;) character.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_status char od_control.od_status_on;
|
|||
|
_on
|
|||
|
This variable is a Boolean value which allows your program to
|
|||
|
completely disable the OpenDoors status line. The variable
|
|||
|
defaults to a value of TRUE, which causes the OpenDoors status
|
|||
|
line to be controllable by function keys, displayed and updated
|
|||
|
as it would normally be. However, if this variable is set to
|
|||
|
FALSE, then OpenDoors will not update the status line, nor will
|
|||
|
it allow the status line to be re-displayed as a result of one
|
|||
|
of the status line ([F1] through [F10]) keys being pressed. When
|
|||
|
you change the value of this variable from FALSE to TRUE,
|
|||
|
OpenDoors will automatically redisplay the status line. Note,
|
|||
|
however, that the status line isn't automatically removed when
|
|||
|
the value of this variable is changed from TRUE to FALSE. In
|
|||
|
order to erase the status line after resetting the value of this
|
|||
|
variable, you should reset the output window to the full screen,
|
|||
|
by calling the function window(1,1,25,80). Then manually erase
|
|||
|
the old status line either by clearing the bottom two lines of
|
|||
|
the screen, or by clearing the entire screen.
|
|||
|
|
|||
|
It is important that you do not confuse the use of this variable
|
|||
|
with the od_set_statusline() function, which is described on
|
|||
|
page 137. When the status line is enabled, the sysop can change
|
|||
|
which status line, if any, is being displayed, using the
|
|||
|
function keys [F1] through [F10]. The od_set_statusline()
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 210
|
|||
|
|
|||
|
function allows your program to make the same changes to the
|
|||
|
status line setting which the sysop can make by pressing one of
|
|||
|
the function keys. The status line can be removed from the
|
|||
|
screen, allowing a full 25 lines of text to be displayed, by
|
|||
|
pressing the [F10] key, or by making the appropriate call to the
|
|||
|
od_set_statusline() function. Note, however, than when this is
|
|||
|
done, the status line is still enabled, and can be turned on by
|
|||
|
pressing any of the other function keys. On the other hand, if
|
|||
|
the status line is turned off using this variable
|
|||
|
(od_control.od_status_on), the status line sub-system will be
|
|||
|
disabled, and pressing function keys will not "bring it back".
|
|||
|
So, if you were writing a program where a status line would be
|
|||
|
undesirable - such as a non-door communications program, you
|
|||
|
would use the od_control.od_status_on variable. On the other
|
|||
|
hand, if you only wanted to temporarily remove the status line -
|
|||
|
say in order that all 25 lines of a door program's output could
|
|||
|
be viewed - while still allowing the status line to be turned on
|
|||
|
with the sysop function keys, you would use the
|
|||
|
od_set_statusline() function. For more information on the
|
|||
|
od_set_statusline() function, see page 137.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
od_time void (*od_control.od_time_msg_func)(char *string)
|
|||
|
_msg_func
|
|||
|
This variable defaults to a value of NULL. If set to point to a
|
|||
|
function, OpenDoors will call this function INSTEAD OF
|
|||
|
displaying time limit warning messages to the user. The messages
|
|||
|
redirected to this function are:
|
|||
|
|
|||
|
- Inactivity timeout warning
|
|||
|
- Inactivity timeout expired
|
|||
|
- Less than 4 minutes left today
|
|||
|
- Daily time limit expired
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 211
|
|||
|
|
|||
|
CONTROL STRUCTURE - FUNCTION KEYS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
Within OpenDoors, as with most BBS software and doors, the sysop
|
|||
|
has access to a number of function keys, which permits the sysop
|
|||
|
to carry out various functions such as entering chat mode,
|
|||
|
hanging up on the user, shelling to DOS, and so on. The
|
|||
|
variables in this section allow you to customize which keys
|
|||
|
carry out the standard sysop functions, allowing you to
|
|||
|
customize your door's interface to mimic any BBS package. By
|
|||
|
default, OpenDoors emulates the function keys used by the Remote
|
|||
|
Access BBS package, but you may choose, for example, to have
|
|||
|
your door use the key combinations used by PC-Board. In
|
|||
|
addition, OpenDoors provides an interface which allows you to
|
|||
|
add your own function keys which will be accepted by the door.
|
|||
|
This could allow you to add additional features, such as giving
|
|||
|
the sysop access to a status screen which displays information
|
|||
|
about your door.
|
|||
|
|
|||
|
Many of the variables in this section are unsigned ints, which
|
|||
|
represent a sysop key combination such as [ALT]-[H], [F8], or
|
|||
|
[CTRL]-[P]. These values are in the same format as is returned
|
|||
|
by the Turbo C(++) / Borland C++ bioskey() function. The high-
|
|||
|
order byte represents the scan code of the key, and the low-
|
|||
|
order byte represents the ASCII value, if any, of the key
|
|||
|
combination. Note that a complete tutorial on these key codes is
|
|||
|
beyond the scope of this manual. For more information on these
|
|||
|
key codes, you should see the documentation on the bioskey()
|
|||
|
function, which accompanies your compiler. If you wish to
|
|||
|
determine the key code which corresponds to a particular
|
|||
|
keystroke, there is a simple program, listed below, which you
|
|||
|
can compile and use. This program will simply display the key
|
|||
|
code for any key pressed, until you press the [ESCape] key. So,
|
|||
|
in order to determine the code for [SHIFT]-[F8], you would
|
|||
|
simply run this program, press the [SHIFT]-[F8] key combination
|
|||
|
on your keyboard, and record the value displayed on your screen.
|
|||
|
|
|||
|
#include <stdio.h>
|
|||
|
#include <bios.h>
|
|||
|
main()
|
|||
|
{
|
|||
|
int nKey;
|
|||
|
|
|||
|
do
|
|||
|
{
|
|||
|
nKey = bioskey(0);
|
|||
|
printf("%d (from: %x, %x)\n",
|
|||
|
nKey, nKey>>8, nKey&0xff);
|
|||
|
} while((nKey & 0xff) != 27);
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 212
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
BUILT IN These variable allow you to customize the sysop function keys
|
|||
|
FUNCTION which control functions such as hanging up on the user, shelling
|
|||
|
KEYS to DOS, and so on. All of these variable will be assigned
|
|||
|
default values, which correspond to the same function keys used
|
|||
|
by the RemoteAccess BBS package. However, you may change the
|
|||
|
values of these variables in order to customize the key
|
|||
|
combinations which carry out these functions in your own door
|
|||
|
program. Remember that if you wish to change the value of any of
|
|||
|
these variables, you must do so after having called od_init() or
|
|||
|
some OpenDoors function. Each of these variables contain a scan-
|
|||
|
code / ASCII-code combination representing a keystroke, as is
|
|||
|
described above. These variables are as follows:
|
|||
|
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
| VARIABLE | CORRESPONDING FUNCTION |
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
| od_control. | Enter sysop chat mode |
|
|||
|
| key_chat | (Normally [ALT]-[C] |
|
|||
|
| | |
|
|||
|
| od_control. | Invoke sysop DOS shell |
|
|||
|
| key_dosshell | (Normally [ALT]-[J] |
|
|||
|
| | |
|
|||
|
| od_control. | Return to the BBS without hanging up |
|
|||
|
| key_drop2bbs | (Normally [ALT]-[D]) |
|
|||
|
| | |
|
|||
|
| od_control. | Hangup on the user |
|
|||
|
| key_hangup | (Normally [ALT]-[H]) |
|
|||
|
| | |
|
|||
|
| od_control. | Turn off the user's keyboard |
|
|||
|
| key_keyboardoff | (Normally [ALT]-[K]) |
|
|||
|
| | |
|
|||
|
| od_control. | Decreases the user's remaining time |
|
|||
|
| key_lesstime | (Normally [DOWN-ARROW]) |
|
|||
|
| | |
|
|||
|
| od_control. | Lock the user out of the BBS system |
|
|||
|
| key_lockout | (Normally [ALT]-[L]) |
|
|||
|
| | |
|
|||
|
| od_control. | Increases the user's remaining time |
|
|||
|
| key_moretime | (Normally [UP-ARROW]) |
|
|||
|
| | |
|
|||
|
| od_control. | Array of eight function keys to set the|
|
|||
|
| key_status[8] | current status line. |
|
|||
|
| | (Normally [F1], [F2], [F3], [F4], [F5],|
|
|||
|
| | [F6], [F9], [F10]) |
|
|||
|
| | |
|
|||
|
| od_control. | "Sysop next" toggle key |
|
|||
|
| key_sysopnext | (Normally [ALT]-[N]) |
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 213
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CUSTOM In addition to the sysop function keys built into OpenDoors, you
|
|||
|
FUNCTION may wish to add your own function keys to your door. For
|
|||
|
KEYS example, you might wish to have the [ALT]-[Z] combination
|
|||
|
display a window of information about your door, or you may wish
|
|||
|
to add your own user editor to your door, accessible through the
|
|||
|
[ALT]-[E] combination. The four variables:
|
|||
|
|
|||
|
unsigned char od_control.od_num_keys;
|
|||
|
unsigned int od_control.od_hot_key[16];
|
|||
|
unsigned int od_control.od_last_hot;
|
|||
|
void (*od_control.od_hot_function[16])(void);
|
|||
|
|
|||
|
provide your program with an interface to add your own sysop
|
|||
|
function keys (not accessible by the remote user) to the door
|
|||
|
you have written.
|
|||
|
|
|||
|
OpenDoors allows you to define up to sixteen custom sysop
|
|||
|
function keys. The key codes (as described at the beginning of
|
|||
|
this section) are stored in the od_control.od_hot_key[] array,
|
|||
|
and the od_control.od_num_keys variable records the number of
|
|||
|
keys which have been defined. The od_control.od_num_keys
|
|||
|
variable defaults to a value of 0. So, in order to add your own
|
|||
|
function keys, simply place the key codes for these keys in the
|
|||
|
first n elements of the od_control.od_hot_key[] array, and set
|
|||
|
the od_control.od_num_keys variable to the number of keys you
|
|||
|
have defined. OpenDoors will then watch the keyboard for any of
|
|||
|
your predefined sysop function keys being pressed. If one of
|
|||
|
these keys is pressed, OpenDoors will place the key code of the
|
|||
|
pressed key in the od_control.od_last_hot variable. Your program
|
|||
|
will then be able to respond to one of your custom function keys
|
|||
|
being pressed by checking the value of the
|
|||
|
od_control.od_last_hot variable. At any time this variable
|
|||
|
contains a non-zero value. If this is the case, you will then be
|
|||
|
able to determine which of your function keys has been pressed
|
|||
|
by checking the key code contained in this variable. After
|
|||
|
taking the appropriate action for the key pressed, you should be
|
|||
|
sure to reset the value of the od_control.od_last_hot variable
|
|||
|
back to zero, which will indicate to OpenDoors that your program
|
|||
|
has received and responded to the function key which was
|
|||
|
pressed.
|
|||
|
|
|||
|
As an alternative to testing the contents of the
|
|||
|
od_control.od_last_hot variable, you can also have your program
|
|||
|
respond to custom sysop function keys by providing a callback
|
|||
|
function in the array: void
|
|||
|
(*od_control.od_hot_function[16])(void);
|
|||
|
|
|||
|
The Nth element in this array corresponds to the Nth element in
|
|||
|
the od_control.od_hot_key array. To use this mechanism, simply
|
|||
|
set the appropriate element of this array to point to the
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 214
|
|||
|
|
|||
|
function that you wish to have OpenDoors call when the sysop
|
|||
|
presses the corresponding function key. For instance, assume
|
|||
|
that the following function is included in your program's source
|
|||
|
code:
|
|||
|
|
|||
|
void addPoints(void)
|
|||
|
{
|
|||
|
/* add ten points to the user's score */
|
|||
|
currentUser->points += 10;
|
|||
|
}
|
|||
|
|
|||
|
If you wanted to have this function called when the sysop
|
|||
|
presses the [Page Up] key, you could do the following:
|
|||
|
|
|||
|
/* get number of new sysop function key, and increment */
|
|||
|
/* total number of keys */
|
|||
|
int new_key = od_control.od_num_keys++;
|
|||
|
|
|||
|
/* Set next sysop hotkey to Page Up */
|
|||
|
od_control.od_hot_key[new_key] = 0x4900;
|
|||
|
|
|||
|
/* Set corresponding function to addPoints() */
|
|||
|
od_control.od_hot_function[new_key] = addPoints;
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 215
|
|||
|
|
|||
|
CONTROL STRUCTURE - COLOR CUSTOMIZATION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
These variables allow you to customize the color of text
|
|||
|
displayed by OpenDoors. Each of these variables are assigned
|
|||
|
color attributes, in the format used by od_set_attrib()
|
|||
|
(described on page 128). These variables are as follows:
|
|||
|
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
| VARIABLE | WHERE COLOR IS USED |
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
| od_control. | Text typed by the sysop and user in |
|
|||
|
| od_chat_color1 & 2 | chat mode. |
|
|||
|
| | |
|
|||
|
| od_control. | File description fields in FILES.BBS |
|
|||
|
| od_list_comment_col | listings |
|
|||
|
| | |
|
|||
|
| od_control. | Color of page pausing prompt that is |
|
|||
|
| od_continue_col | displayed at the end of each page |
|
|||
|
| | |
|
|||
|
| od_control. | Filename fields in FILES.BBS listings |
|
|||
|
| od_list_name_col | |
|
|||
|
| | |
|
|||
|
| od_control. | "Missing" string in FILES.BBS listings |
|
|||
|
| od_list_offline_col | |
|
|||
|
| | |
|
|||
|
| od_control. | File size fields in FILES.BBS listings |
|
|||
|
| od_list_size_col | |
|
|||
|
| | |
|
|||
|
| od_control. | Title fields in FILES.BBS listings |
|
|||
|
| od_list_title_col | |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the window title as displayed |
|
|||
|
| od_menu_title_col | by od_popup_menu() |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the window border as |
|
|||
|
| od_menu_border_col | displayed by od_popup_menu() |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the normal text displayed |
|
|||
|
| od_menu_text_col | by od_popup_menu() |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the shortcut keys displayed |
|
|||
|
| od_menu_key_col | by od_popup_menu() |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the selection bar as |
|
|||
|
| od_menu_highlight_ | displayed by od_popup_menu() |
|
|||
|
| col | |
|
|||
|
| | |
|
|||
|
| od_control. | Color of the shortcut keys displayed |
|
|||
|
| od_menu_highkey_col | on the selected line by od_popup_menu()|
|
|||
|
+---------------------+----------------------------------------+
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 216
|
|||
|
|
|||
|
CONTROL STRUCTURE - TEXT CUSTOMIZATION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
In addition to the other aspects of OpenDoors which may be
|
|||
|
customized by use of the OpenDoors control structure, all of the
|
|||
|
text displayed by OpenDoors may also be customized. This may be
|
|||
|
done either to create doors with OpenDoors that use languages
|
|||
|
other than English, or to simply give your doors a "personal
|
|||
|
touch". The variables described in this section allow you to
|
|||
|
define what text you want to have displayed by OpenDoors at any
|
|||
|
time. All of these variables are pointers to strings, and are
|
|||
|
set to default values in the od_init() function. Thus, if you
|
|||
|
wish to change the string pointed to by any of these variables,
|
|||
|
you must do so after od_init() or some OpenDoors API function
|
|||
|
has been called. To set any of these variables, you can simply
|
|||
|
set them to point to a string-constant in your program. For
|
|||
|
example, to set the text displayed by OpenDoors prior to a DOS
|
|||
|
shell, you could:
|
|||
|
|
|||
|
od_control.od_before_shell=(char *)"\n\rJust a moment...\n\r";
|
|||
|
|
|||
|
The chart below lists each of the text customization variables
|
|||
|
(without the "od_control." prefix, for the sake of brevity),
|
|||
|
along with their default strings.
|
|||
|
|
|||
|
Note that some of these strings MUST always be the same length
|
|||
|
as their default string. You may not display longer text within
|
|||
|
these strings, and if you wish to display shorter text, you must
|
|||
|
pad the remaining space in the string with spaces, in order to
|
|||
|
preserve its length. Those string which must be of fixed length
|
|||
|
also have their length listed in the chart below. Any strings
|
|||
|
which have an asterisk (*) in their length column may be any
|
|||
|
length.
|
|||
|
|
|||
|
Also keep in mind that any string with "printf-style" formatting
|
|||
|
sequences, such as "%s", must retain the same sequences in the
|
|||
|
same order.
|
|||
|
|
|||
|
In addition, four of these pointers - od_after_chat,
|
|||
|
od_after_shell, od_before_chat and od_before_shell - can be set
|
|||
|
to a value of NULL. In this case, OpenDoors will not display any
|
|||
|
string where this variable's string is normally displayed.
|
|||
|
|
|||
|
+-----------------------+-----+----------------------------------------------+
|
|||
|
| VARIABLE NAME | LEN | DEFAULT VALUE |
|
|||
|
+-----------------------+-----+----------------------------------------------+
|
|||
|
| od_after_chat | * | "\n\rChat mode ended...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_after_shell | * | "\n\r...Thanks for waiting\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_before_chat | * | "\n\rSysop breaking in for chat...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 217
|
|||
|
|
|||
|
| od_before_shell | * | "\n\rPlease wait a moment...\n\r" |
|
|||
|
| | | |
|
|||
|
| od_chat_reason | * | " Why would you " |
|
|||
|
| | | "like to chat?\n\r" |
|
|||
|
| | | |
|
|||
|
| od_continue | * | "Continue? [Y/n/=]" |
|
|||
|
| | | |
|
|||
|
| od_continue_no | char| 'N' |
|
|||
|
| | | |
|
|||
|
| od_continue_nonstop | char| '=' |
|
|||
|
| | | |
|
|||
|
| od_continue_yes | char| 'Y' |
|
|||
|
| | | |
|
|||
|
| od_day[0] | 3 | "Sun" |
|
|||
|
| | | |
|
|||
|
| od_day[1] | 3 | "Mon" |
|
|||
|
| | | |
|
|||
|
| od_day[2] | 3 | "Tue" |
|
|||
|
| | | |
|
|||
|
| od_day[3] | 3 | "Wed" |
|
|||
|
| | | |
|
|||
|
| od_day[4] | 3 | "Thu" |
|
|||
|
| | | |
|
|||
|
| od_day[5] | 3 | "Fri" |
|
|||
|
| | | |
|
|||
|
| od_day[6] | 3 | "Sat" |
|
|||
|
| | | |
|
|||
|
| od_hanging_up | * | "Terminating Call" |
|
|||
|
| | | |
|
|||
|
| od_help_text | 80 | " Alt: [C]hat [H]angup [L]ockout [J]Dos " |
|
|||
|
| | | "[K]eyboard-Off [D]rop to BBS " |
|
|||
|
| | | |
|
|||
|
| od_help_text2 | 79 | " OpenDoors 6.00 - (C)Copyright 1992, " |
|
|||
|
| | | "Brian Pirie - Registered Version " |
|
|||
|
| | | |
|
|||
|
| od_inactivity_timeout | * | "User sleeping at keyboard, inactivity " |
|
|||
|
| | | "timeout...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_inactivity_warning | * | "Warning, only %d minute(s) remaining " |
|
|||
|
| | | "today...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_month[0] | 3 | "Jan" |
|
|||
|
| | | |
|
|||
|
| od_month[1] | 3 | "Feb" |
|
|||
|
| | | |
|
|||
|
| od_month[2] | 3 | "Mar" |
|
|||
|
| | | |
|
|||
|
| od_month[3] | 3 | "Apr" |
|
|||
|
| | | |
|
|||
|
| od_month[4] | 3 | "May" |
|
|||
|
| | | |
|
|||
|
| od_month[5] | 3 | "Jun" |
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 218
|
|||
|
|
|||
|
| | | |
|
|||
|
| od_month[6] | 3 | "Jul" |
|
|||
|
| | | |
|
|||
|
| od_month[7] | 3 | "Aug" |
|
|||
|
| | | |
|
|||
|
| od_month[8] | 3 | "Sep" |
|
|||
|
| | | |
|
|||
|
| od_month[9] | 3 | "Oct" |
|
|||
|
| | | |
|
|||
|
| od_month[10] | 3 | "Nov" |
|
|||
|
| | | |
|
|||
|
| od_month[11] | 3 | "Dec" |
|
|||
|
| | | |
|
|||
|
| od_no_keyboard | 10 | "[Keyboard]" |
|
|||
|
| | | |
|
|||
|
| od_no_sysop | * | "\n\rI'm afraid the sysop is not available " |
|
|||
|
| | | "at this time.\n\r" |
|
|||
|
| | | |
|
|||
|
| od_no_response | * | " No response.\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_no_time | * | "Sorry, you have used up your time for " |
|
|||
|
| | | "today...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_offline | 10 | "[OFFLINE] " |
|
|||
|
| | | |
|
|||
|
| od_paging | * | "\n\rPaging Sysop for Chat" |
|
|||
|
| | | |
|
|||
|
| od_press_key | * | "Press [Enter] to continue..." |
|
|||
|
| | | |
|
|||
|
| od_sending_rip | * | "\xb4 Sending RIP File \xc3" |
|
|||
|
| | | |
|
|||
|
| od_status_line[0] | 80 | " " |
|
|||
|
| | | " [Node: " |
|
|||
|
| | | |
|
|||
|
| od_status_line[1] | * | "%s of %s at %u BPS" |
|
|||
|
| | | |
|
|||
|
| od_status_line[2] | 79 | "Security: Time: " |
|
|||
|
| | | " [F9]=Help " |
|
|||
|
| | | |
|
|||
|
| od_sysop_next | 5 | "[SN] " |
|
|||
|
| | | |
|
|||
|
| od_time_left | 10 | "%d mins " |
|
|||
|
| | | |
|
|||
|
| od_time_warning | * | "Warning, only %d minute(s) remaining tod" |
|
|||
|
| | | "ay...\n\r\n\r" |
|
|||
|
| | | |
|
|||
|
| od_want_chat | 11 | "[Want-Chat]" |
|
|||
|
+-----------------------+-----+----------------------------------------------+
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 219
|
|||
|
|
|||
|
66
|
|||
|
66
|
|||
|
66
|
|||
|
66666
|
|||
|
66 66
|
|||
|
66 66
|
|||
|
6666
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 6 - SPECIAL TOPICS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
ADDITIONAL INFORMATION ON THE WIN32 VERSION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This section provides additional information on the Win32
|
|||
|
version of OpenDoors that isn't found elsewhere in this manual.
|
|||
|
If you are working with the Win32 version of OpenDoors, you
|
|||
|
should take the time to read this entire section. You should
|
|||
|
also read the sections in chapter 3 that describe how to compile
|
|||
|
and run Win32 programs that use OpenDoors.
|
|||
|
|
|||
|
The Win32 version of OpenDoors has been designed to be as
|
|||
|
similar as possible to the DOS version of OpenDoors. This means
|
|||
|
that where possible, you can compile the same source code to
|
|||
|
produce both a DOS and a Windows program. However, if you are
|
|||
|
porting an existing DOS OpenDoors-based program to the Win32
|
|||
|
platform, there are some important things to keep in mind.
|
|||
|
|
|||
|
The first thing to note is that under DOS, the program's
|
|||
|
execution begins in the main() function, whereas under Windows,
|
|||
|
it begins in the WinMain() function. To allow the same source
|
|||
|
file to build both DOS and Windows versions you can use
|
|||
|
conditional compilation. OpenDoor.h defines a constant of the
|
|||
|
form ODPLAT_xxx, indicating which version of OpenDoors is being
|
|||
|
used. Currently, this will be either ODPLAT_DOS, or
|
|||
|
ODPLAT_WIN32. However, if a OS/2 or Unix version of OpenDoors
|
|||
|
were created, they would use definitions such as ODPLAT_OS2, or
|
|||
|
ODPLAT_UNIX. Under the Win32 version, you should pass the
|
|||
|
nCmdShow parameter that is passed to WinMain into OpenDoors,
|
|||
|
through od_control.od_cmd_show. If you do not do this, the
|
|||
|
program will always start with the main window maximized,
|
|||
|
regardless of what the user has requested. Also, you will
|
|||
|
probably want to use the new od_parse_cmd_line() function in
|
|||
|
both DOS and Windows programs, to allow standard command-line
|
|||
|
options to be processed. The od_parse_cmd_line() function
|
|||
|
accepts command line information in the same format as it is
|
|||
|
passed to the main or WinMain() function. So, the general
|
|||
|
structure of an OpenDoors program that can be compiled under
|
|||
|
either DOS or Win32 now becomes:
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 220
|
|||
|
|
|||
|
/* Add your own #includes here. */
|
|||
|
|
|||
|
#include "opendoor.h"
|
|||
|
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance,
|
|||
|
LPSTR lpszCmdLine, int nCmdShow)
|
|||
|
#else
|
|||
|
int main(int argc, char *argv[])
|
|||
|
#endif
|
|||
|
{
|
|||
|
/* Add local variables here. */
|
|||
|
|
|||
|
#ifdef ODPLAT_WIN32
|
|||
|
od_control.od_cmd_show = nCmdShow;
|
|||
|
|
|||
|
od_parse_cmd_line(lpszCmdLine);
|
|||
|
#else
|
|||
|
od_parse_cmd_line(argc, argv);
|
|||
|
#endif
|
|||
|
|
|||
|
/* Add the rest of your program after this point. */
|
|||
|
}
|
|||
|
|
|||
|
If you are porting existing OpenDoors programs over to the Win32
|
|||
|
version of OpenDoors, another issue that you will have to pay
|
|||
|
careful attention to is the fact that you are now working in the
|
|||
|
32-bit world. While 32-bit programming under a flat memory model
|
|||
|
has many advantages (no more 64K segments and related
|
|||
|
limitations, for example), you must be aware that the size of
|
|||
|
basic data types that you are used to using may have changed.
|
|||
|
For example, an int is now 32-bits wide instead of 16-bits wide.
|
|||
|
One of the places where this difference becomes very important
|
|||
|
is if you are performing file-I/O by directly dumping a
|
|||
|
structure to or from disk using functions such as fread() and
|
|||
|
fwrite(). In this case, you must declare your structures using
|
|||
|
types that are of the same size between the 16-bit and 32-bit
|
|||
|
worlds, in order for your file formats to be compatible between
|
|||
|
the DOS and Win32 versions of your program. For example, the
|
|||
|
EX_VOTE.C example program declares its structure using fixed-
|
|||
|
sized types that are always available to any program including
|
|||
|
"opendoor.h". These types are the following size, regardless of
|
|||
|
what platform you are compiling under:
|
|||
|
|
|||
|
INT8 - 8-bit signed integer.
|
|||
|
INT16 - 16-bit signed integer.
|
|||
|
INT32 - 32-bit signed integer.
|
|||
|
BYTE - 8-bit unsigned integer.
|
|||
|
WORD - 16-bit unsigned integer.
|
|||
|
DWORD - 32-bit unsigned integer.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 221
|
|||
|
|
|||
|
(NOTE: Obviously, the many details of 32-bit programming and
|
|||
|
Windows programming are beyond the scope of this document. For
|
|||
|
more information on the issues discussed here, you will probably
|
|||
|
wish to consult other sources of information on Win32
|
|||
|
programming.)
|
|||
|
|
|||
|
As you are probably aware, the Win32 edition of OpenDoors makes
|
|||
|
extensive use of multithreading. The number of threads will
|
|||
|
depend on what mode OpenDoors is operating in. In some
|
|||
|
situations, all of the following threads may exist:
|
|||
|
|
|||
|
- The client thread(s), which executes the code that you write
|
|||
|
in your program, along with the OpenDoors API functions.
|
|||
|
- The local screen thread, which is responsible for drawing
|
|||
|
your program's output on the screen, and receiving input from
|
|||
|
the local keyboard.
|
|||
|
- The frame window thread, which handles the OpenDoors menus,
|
|||
|
toolbar, status bar and sysop function keys.
|
|||
|
- The remote input thread, which receives input from the serial
|
|||
|
port and adds it to OpenDoors common local/remote input
|
|||
|
queue.
|
|||
|
- The carrier detection thread, which blocks and only executes
|
|||
|
if the carrier detect signal goes low.
|
|||
|
- The time update thread, which updates the user's time
|
|||
|
remaining online, and monitors user timeouts.
|
|||
|
|
|||
|
Since most of these threads only execute when the operating
|
|||
|
system determines that there is actually something for them to
|
|||
|
do, the Win32 version of OpenDoors provides very high
|
|||
|
performance and responsiveness.
|
|||
|
|
|||
|
You may also want to make use of multithreading directly within
|
|||
|
your program. If you do this, please note that while you may use
|
|||
|
threads to perform background processing, OpenDoors requires
|
|||
|
that you only call OpenDoors API functions from one thread.
|
|||
|
|
|||
|
If you wish to customize the information that is displayed in
|
|||
|
the Help|About dialog box (including your program's name and
|
|||
|
copyright information), provide your own application icon, or
|
|||
|
add online help to the help menu, refer to the sections in the
|
|||
|
manual on the following od_control variables:
|
|||
|
|
|||
|
od_control.od_app_icon
|
|||
|
od_control.od_help_callback
|
|||
|
od_control.od_prog_name
|
|||
|
od_control.od_prog_version
|
|||
|
od_control.od_prog_copyright
|
|||
|
|
|||
|
The section that describes how to run Windows based door
|
|||
|
programs under DOS-based BBS package indicates that
|
|||
|
COM<n>AutoAssign=0 should be set in the system.ini file. The
|
|||
|
explanation for this is as follows: The default value for this
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 222
|
|||
|
|
|||
|
setting in Windows 95 is -1, which prevents any Windows-based
|
|||
|
program from accessing a serial port which has previously been
|
|||
|
used by a non-Windows-based program, until the window that
|
|||
|
program was running in is closed. By setting this value to 0,
|
|||
|
you are allowing the Windows-based door program to immediately
|
|||
|
use the modem, even while the MS-DOS session (VM) is still
|
|||
|
active. A value of <x> greater than 0 will allow Windows-based
|
|||
|
programs to access the serial port, only if the DOS-based
|
|||
|
program has not accessed the serial port for at least <x>
|
|||
|
seconds. For example, the default setting in Windows 3.1 was
|
|||
|
COM1AutoAssign=2, which allowed Windows-based programs to access
|
|||
|
the serial port if no DOS program had used it for at least 2
|
|||
|
seconds.
|
|||
|
|
|||
|
The section that describes how to run Windows based door
|
|||
|
programs under DOS-based BBS package also indicates that the
|
|||
|
DTRON utility should be run after the start command returns. The
|
|||
|
reason for this is that when a Windows program exits and closes
|
|||
|
the serial port (by calling the CloseHandle() function), Windows
|
|||
|
95 lowers the DTR line on the serial port. Most modems are
|
|||
|
configured to respond to this by hanging up on the remote user.
|
|||
|
From talking to other people, it seems that this "feature" (or
|
|||
|
fundamental design flaw, depending on how you want to look at
|
|||
|
it) is unique to Windows 95, and won't effect OpenDoors when
|
|||
|
running under Windows NT. However, the majority of people will
|
|||
|
undoubtedly be using the Win32 version of OpenDoors under
|
|||
|
Windows 95. This is unfortunate, since the Win32 communications
|
|||
|
facilities are otherwise _very_ well designed. There is a rumor
|
|||
|
that Microsoft's next upgrade to Windows 95 will fix this
|
|||
|
problem. However, I must stress that this is only a rumor, and
|
|||
|
that I haven't received any confirmation about this from
|
|||
|
Microsoft.
|
|||
|
|
|||
|
OpenDoors currently provides two solutions to this problem.
|
|||
|
|
|||
|
First of all, OpenDoors has the ability to use an already open
|
|||
|
serial port handle, if that information is supplied to it.
|
|||
|
Hopefully, all Windows 95-based BBS software will provide the
|
|||
|
option of running a door program with the serial port still
|
|||
|
open, and allow you to pass that serial port handle on the door
|
|||
|
program's command line. OpenDoors allows the serial port handle
|
|||
|
to be passed on the command line, or set directly in the
|
|||
|
od_control structure, as is described later in this manual. On
|
|||
|
BBS systems where this form of hot sharing of the serial port is
|
|||
|
supported, the serial port can remain open at all times, and so
|
|||
|
the CloseHandle() problem is avoided.
|
|||
|
|
|||
|
This means that the only situation where the CloseHandle()
|
|||
|
problem still has to be dealt with is when OpenDoors is running
|
|||
|
on a Windows 95 system and OpenDoors has to open the serial port
|
|||
|
itself (and so must close the serial port before exiting). This
|
|||
|
would be the case for most MS-DOS based BBS systems running
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 223
|
|||
|
|
|||
|
under Windows 95, unless some intermediate layer is provided. By
|
|||
|
default, in this situation OpenDoors will disable DTR response
|
|||
|
by the modem just before it closes the serial port, by sending
|
|||
|
the AT&D0 command to the modem. The exact sequence of commands
|
|||
|
used by OpenDoors to do this is specified by the
|
|||
|
od_control.od_disable_dtr string. This DTR response disabling
|
|||
|
may be turned off by setting the DIS_DTR_DISABLE
|
|||
|
od_control.od_disable flag. Since many programs (OpenDoors
|
|||
|
included) assume that they can hangup the modem by lowering the
|
|||
|
DTR signal, a small utility will usually be run after the door,
|
|||
|
which first raises the DTR signal again, and then re-enables DTR
|
|||
|
response by the modem. Such a utility is included in this
|
|||
|
package, named DTRON.EXE. I wrote the DTRON utility so that you
|
|||
|
can freely redistributed it with your programs.
|
|||
|
|
|||
|
So, to summarize, the DTR disabling by OpenDoors and subsequent
|
|||
|
reenabling by DTRON is only required for the Win32 version of
|
|||
|
OpenDoors running under Windows 95 when the modem is configured
|
|||
|
to hangup if the DTR signal is lowered, and the BBS software
|
|||
|
does not have the ability to pass a live serial port handle to a
|
|||
|
door program. Setting COM<n>AutoAssign in system.ini is only
|
|||
|
required for the Win32 version of OpenDoors when it is being
|
|||
|
called from an MS-DOS session that has previously accessed the
|
|||
|
serial port.
|
|||
|
|
|||
|
Note that the Win32 version of OpenDoors requires Windows 95 or
|
|||
|
Windows NT. It will not run under Windows 3.x, even with Win32s.
|
|||
|
This is because OpenDoors makes use of the Windows 95/NT
|
|||
|
multitasking and multithreading services that are not available
|
|||
|
under Win32s.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 224
|
|||
|
|
|||
|
CONFIGURATION FILE SYSTEM
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
One of the most useful OpenDoors features that you can
|
|||
|
optionally choose to include in your programs is the OpenDoors
|
|||
|
configuration file system. All that is required to enable the
|
|||
|
configuration file system is to include the following line
|
|||
|
before your first call to any OpenDoors function:
|
|||
|
|
|||
|
od_control.od_config_file = INCLUDE_CONFIG_FILE;
|
|||
|
|
|||
|
OpenDoors will now search for and read an OpenDoors
|
|||
|
configuration file. If you do not specify the name of this file,
|
|||
|
the default name of DOOR.CFG will be used. Using this
|
|||
|
configuration file, the sysop can set a wide variety of options,
|
|||
|
such as modem and system configuration information, maximum time
|
|||
|
limits for the door, and even define custom door information
|
|||
|
(drop) file formats. The example DOOR.CFG file included in your
|
|||
|
OpenDoors package shows the format and all options that are
|
|||
|
automatically supported by the configuration file system. This
|
|||
|
configuration file format is designed to be easy to use, and the
|
|||
|
example configuration file contains comments which provide a
|
|||
|
complete description of each option. Feel free to redistribute
|
|||
|
DOOR.CFG or a modified version of this file with your door
|
|||
|
programs. In addition to the many configuration file settings
|
|||
|
already supported, you can add your own settings that are
|
|||
|
specific to your particular program.
|
|||
|
|
|||
|
To specify your own filename for the configuration file, use the
|
|||
|
od_config_filename control structure variable. For example, the
|
|||
|
following line:
|
|||
|
|
|||
|
od_control.od_config_filename = "MYDOOR.CFG"
|
|||
|
|
|||
|
causes OpenDoors to look for the configuration file MYDOOR.CFG
|
|||
|
instead of the default DOOR.CFG.
|
|||
|
|
|||
|
OpenDoors fill first search for the configuration file in the
|
|||
|
directory specified in the od_config_filename variable, if a
|
|||
|
specific directory name was supplied. If not found, it will then
|
|||
|
search the current directory. If the configuration file system
|
|||
|
is unable to locate a configuration file, or if any settings are
|
|||
|
omitted from the file, the default values for these settings
|
|||
|
will be used automatically. This means that the configuration
|
|||
|
file is always optional, unless your program has custom settings
|
|||
|
that it requires in order to run.
|
|||
|
|
|||
|
The format for the configuration file is as follows. Blank lines
|
|||
|
and any text following the semi-colon (;) character are ignored.
|
|||
|
Configuration options are specified using a keyword, possibly
|
|||
|
followed by one or more options. The keywords are not case
|
|||
|
sensitive, but some of the options are. The order of options in
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 225
|
|||
|
|
|||
|
the configuration file is not significant, with the exception of
|
|||
|
the "CustomFileLine" option. For more information on the
|
|||
|
"CustomFileLine" setting, see the section that begins on page
|
|||
|
230. The built-in configuration options are as follow:
|
|||
|
|
|||
|
BBSDir - BBS System directory. Indicates where the door
|
|||
|
information file (drop file) can be found.
|
|||
|
|
|||
|
DoorDir - The door's working directory. This is where the door's
|
|||
|
system files are located. OpenDoors will automatically
|
|||
|
perform a chdir into this directory at initialization, and
|
|||
|
will return to the original directory on exit.
|
|||
|
|
|||
|
LogFileName - Specifies the filename (path optional) where the
|
|||
|
door should record log information.
|
|||
|
|
|||
|
DisableLogging - Prevents door from writing to a log file.
|
|||
|
|
|||
|
Node - BBS node number that the door is running on. Only used if
|
|||
|
OpenDoors is unable to determine the node number by some
|
|||
|
other means.
|
|||
|
|
|||
|
???dayPagingHours - Specifies sysop paging hours. Sysop paging
|
|||
|
will be permitted beginning at the start time, up until,
|
|||
|
but not including, the end time. Times should be in the 24-
|
|||
|
hour format. To disable paging on a particular day, set the
|
|||
|
paging start and end times to the same time. ???day can be
|
|||
|
one of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday
|
|||
|
or Saturday.
|
|||
|
|
|||
|
PageDuration - Duration of sysop page. Value indicates the
|
|||
|
number of beeps that compose the sysop page alarm.
|
|||
|
|
|||
|
MaximumDoorTime - Maximum length of time a user is permitted to
|
|||
|
access the door. If the user's total remaining time on the
|
|||
|
BBS is less than this value, the user will only be
|
|||
|
permitted to access the door for this shorter length of
|
|||
|
time. This option is disabled by commenting out the line.
|
|||
|
|
|||
|
InactivityTimeout - Specifies the maximum number of seconds that
|
|||
|
may elapse without the user pressing a key, before the user
|
|||
|
will automatically be disconnected. A value of 0 disables
|
|||
|
inactivity timeouts.
|
|||
|
|
|||
|
SysopName - Name of the sysop. OpenDoors can usually determine
|
|||
|
the sysop's name from the door information (drop) file.
|
|||
|
How3ever, some BBS packages do not supply this information.
|
|||
|
In such cases, if the sysop's name is required by the door,
|
|||
|
it may be supplied here.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 226
|
|||
|
|
|||
|
SystemName - Like the sysop's name, this option can usually be
|
|||
|
determined from the door information file. If it is not
|
|||
|
available, the sysop my supply the information here.
|
|||
|
|
|||
|
ChatUserColor - Specifies the color of text typed by the user in
|
|||
|
sysop chat mode. The format of the color name is included
|
|||
|
in the description of the od_color_config() function.
|
|||
|
|
|||
|
ChatSysopColor - Specifies the color of test typed by the sysop
|
|||
|
in chat mode.
|
|||
|
|
|||
|
FileListTitleColor - Files.BBS listing colors.
|
|||
|
FileListNameColor
|
|||
|
FileListSizeColor
|
|||
|
FileListDescriptionColor
|
|||
|
FileListOfflineColor
|
|||
|
|
|||
|
SwappingDir - Directory where disk swapping will be done.
|
|||
|
|
|||
|
SwappingNoEMS - Disables swapping to EMS memory.
|
|||
|
|
|||
|
SwappingDisable - Disables swapping entirely.
|
|||
|
|
|||
|
LockedBPS - BPS rate at which door should communicate with the
|
|||
|
modem. Valid rates are 300, 600, 1200, 2400, 4800, 9600,
|
|||
|
19200 and 38400. A value of 0 forces the door to always
|
|||
|
operate in local mode. This option is not normally needed,
|
|||
|
as the information is usually available from the door
|
|||
|
information file.
|
|||
|
|
|||
|
FossilPort - Specifies the FOSSIL driver port number that the
|
|||
|
modem is connected to. FOSSIL port 0 usually corresponds to
|
|||
|
COM1, port 1 to COM2, and so on. This option is not
|
|||
|
normally needed, as the information is usually available
|
|||
|
from the door information file.
|
|||
|
|
|||
|
CustomFileName - Specifies the filename used by the custom door
|
|||
|
information file format. Described in more detail below.
|
|||
|
|
|||
|
CustomFileLine - Specifies the contents of a particular line in
|
|||
|
the custom door information file format.
|
|||
|
|
|||
|
The last two configuration file options, "CustomFileName" and
|
|||
|
"CustomFileLine" allow you or the system operator using your
|
|||
|
program to define your own door information (drop) file formats.
|
|||
|
For more information on this topic, see the section which begins
|
|||
|
on page 230.
|
|||
|
|
|||
|
You can also extend OpenDoor's configuration file format to add
|
|||
|
your own options, by supplying a callback function that will be
|
|||
|
called whenever OpenDoors encounters an unrecognized
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 227
|
|||
|
|
|||
|
configuration file keyword. The prototype of this function
|
|||
|
should be as follows:
|
|||
|
|
|||
|
custom_line_function(char *keyword, char *options)
|
|||
|
|
|||
|
To cause OpenDoors to use your function, you would include the
|
|||
|
following line before your first call to any OpenDoors function:
|
|||
|
|
|||
|
od_control.od_config_function = custom_line_function;
|
|||
|
|
|||
|
(You can use a different function name if you wish.) When
|
|||
|
OpenDoors encounters unrecognized keyword, it will now call your
|
|||
|
function, passing a pointer to an upper case version the keyword
|
|||
|
string in the first parameter, and a pointer to any options that
|
|||
|
follow the keyword in the second parameter. For instance, if the
|
|||
|
following line were encountered in the configuration file:
|
|||
|
|
|||
|
RegisteredTo John Smith ; Sysop's name
|
|||
|
|
|||
|
The parameters passed to your function would be:
|
|||
|
|
|||
|
char *keyword = "REGISTEREDTO"
|
|||
|
char *options = "John Smith"
|
|||
|
|
|||
|
Your custom line function should be written in such a way that
|
|||
|
if OpenDoors passes a configuration option to your function that
|
|||
|
your function does not recognize, that option would simply be
|
|||
|
ignored.
|
|||
|
|
|||
|
The example program below demonstrates how to use the custom
|
|||
|
line function to add your own configuration file options. This
|
|||
|
program looks for three custom configuration file options,
|
|||
|
"RegistrationKey", "DefaultColor" and "DisplayWinners". If the
|
|||
|
"RegistrationKey" option is present, the numerical value
|
|||
|
following this option is stored in the global variable "key". If
|
|||
|
the "DefaultColor" option is present, the color description
|
|||
|
(such as "Bright Red on Black") is translated to an
|
|||
|
od_set_attr() color code using od_color_config(). This color
|
|||
|
setting is stored in the global variable default_color. Since
|
|||
|
this variable is initialized to 0x07 (the value for dark white
|
|||
|
on black), if this option is omitted, that color is used by
|
|||
|
default. If the "DisplayWinners" option is included in the
|
|||
|
configuration file, the global variable display_winners is set
|
|||
|
to TRUE, regardless of any options that may follow this keyword.
|
|||
|
|
|||
|
|
|||
|
#include "opendoor.h" /* Include opendooor.h */
|
|||
|
/* Prototype for custom line function */
|
|||
|
void custom_line_function(char *keyword, char *options);
|
|||
|
|
|||
|
unsigned long key=0L; /* Variables for our own config option */
|
|||
|
unsigned char default_color=0x07;
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 228
|
|||
|
|
|||
|
char display_winners=FALSE;
|
|||
|
|
|||
|
main() /* Program's execution begins here */
|
|||
|
{ /* Begin door operations, reading config file */
|
|||
|
od_control.od_config_file = INCLUDE_CONFIG_FILE;
|
|||
|
/* Tell OpenDoors to use custom line function */
|
|||
|
od_control.od_config_function = custom_line_function;
|
|||
|
od_init();
|
|||
|
/* Main program's operations go here */
|
|||
|
od_exit(10, FALSE); /* Exit program */
|
|||
|
}
|
|||
|
/* Code for custom line function */
|
|||
|
void custom_line_function(char *keyword, char *options)
|
|||
|
{ /* If option is registration key */
|
|||
|
if(stricmp(keyword,"REGISTRATIONKEY")==0)
|
|||
|
{
|
|||
|
key=atol(options); /* Store key in variable */
|
|||
|
} /* If option is text color */
|
|||
|
else if(stricmp(keyword,"DEFAULTCOLOR")==0)
|
|||
|
{ /* Get color value using od_color_config() */
|
|||
|
default_color=od_color_config(options);
|
|||
|
} /* Example of option enabled by just the keyword */
|
|||
|
else if(stricmp(keyword,"DISPLAYWINNERS")==0)
|
|||
|
{ /* If keyword is present, turn on option */
|
|||
|
display_winners=TRUE;
|
|||
|
}
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 229
|
|||
|
|
|||
|
DEFINING CUSTOM DOOR INFORMATION FILE FORMATS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
As is mentioned in the previous section, the OpenDoors
|
|||
|
configuration file system provides two settings which allow the
|
|||
|
sysop to define a custom door information file format. This
|
|||
|
permits OpenDoors doors to operate directly on any BBS system
|
|||
|
that produces a door information file format not directly
|
|||
|
supported by OpenDoors. A custom door information file format is
|
|||
|
defined using the "CustomFileName" option, followed by one or
|
|||
|
more lines beginning with the "CustomFileLine" option.
|
|||
|
|
|||
|
The "CustomFileName" option specifies the filename used to
|
|||
|
distinguish this file format from other file formats. This
|
|||
|
filename should not include a path. To specify the path where
|
|||
|
the door information file is located, the sysop should use the
|
|||
|
BBSDir configuration file setting. If the filename of the custom
|
|||
|
format is the same as that of one of the built-in formats, the
|
|||
|
custom format will override the built-in format.
|
|||
|
|
|||
|
The actual format of the custom file is specified using a number
|
|||
|
of lines that begin with the keyword "CustomFileLine". Each of
|
|||
|
these lines will correspond to a single line in the door
|
|||
|
information file, with the option following the "CustomFileLine"
|
|||
|
keyword specifying the information that can be found on that
|
|||
|
line. This can be one of the following keywords:
|
|||
|
|
|||
|
Ignore - Causes the next line in the door information file
|
|||
|
to be ignored. Use on lines for which none of the
|
|||
|
options below apply.
|
|||
|
|
|||
|
COMPORT - COM? port the modem is connected to (0 indicates
|
|||
|
local mode)
|
|||
|
|
|||
|
FOSSILPORT - Fossil port number the modem is connected to
|
|||
|
|
|||
|
MODEMBPS - BPS rate at which to communicate with modem (0
|
|||
|
or non-numerical value indicates local mode)
|
|||
|
|
|||
|
LOCALMODE - 1, T or Y if door is operating in local mode
|
|||
|
|
|||
|
USERNAME - Full name of the user
|
|||
|
|
|||
|
USERFIRSTNAME - First name(s) of the user
|
|||
|
|
|||
|
USERLASTNAME - Last name of the user
|
|||
|
|
|||
|
ALIAS - The user's pseudonym / handle
|
|||
|
|
|||
|
HOURSLEFT - Hours user has left online
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 230
|
|||
|
|
|||
|
MINUTESLEFT - Minutes user has left online, or time left
|
|||
|
online in format hh:mm
|
|||
|
|
|||
|
SECONDSLEFT - Seconds user has left online, or time left
|
|||
|
online in format hh:mm:ss or format mm:ss (If more
|
|||
|
than one of the above time options are used, the user
|
|||
|
time left is taken to be the total of all of these
|
|||
|
values.)
|
|||
|
|
|||
|
ANSI - 1, T, Y or G for ANSI graphics mode
|
|||
|
|
|||
|
AVATAR - 1, T or Y for AVATAR graphics mode
|
|||
|
|
|||
|
PAGEPAUSING - 1, T or Y if user wishes a pause at end of
|
|||
|
screen
|
|||
|
|
|||
|
SCREENLENGTH - Number of lines on user's screen
|
|||
|
|
|||
|
SCREENCLEARING - 1, T or Y if screen clearing mode is on
|
|||
|
|
|||
|
SECURITY - The user's security level / access level
|
|||
|
|
|||
|
CITY - City the user is calling from
|
|||
|
|
|||
|
NODE - Node number user is connected to
|
|||
|
|
|||
|
SYSOPNAME - Full name of the sysop
|
|||
|
|
|||
|
SYSOPFIRSTNAME - The sysop's first name(s)
|
|||
|
|
|||
|
SYSOPLASTNAME - The sysop's last name
|
|||
|
|
|||
|
SYSTEMNAME - Name of the BBS
|
|||
|
|
|||
|
As an example of how to define custom door information file
|
|||
|
formats, consider the following imaginary file format, which we
|
|||
|
will name DROPINFO.TXT:
|
|||
|
|
|||
|
Brian Pirie <-- User name
|
|||
|
0 <-- Local mode
|
|||
|
COM1: <-- Serial port to use
|
|||
|
9600 <-- BPS rate
|
|||
|
22:30:15 05-08-95 <-- File creation time
|
|||
|
35 <-- Time remaining (in minutes)
|
|||
|
1 <-- ANSI mode
|
|||
|
Ottawa, Canada <-- Location
|
|||
|
|
|||
|
This format would be defined in an OpenDoors configuration file
|
|||
|
as follows:
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 231
|
|||
|
|
|||
|
CustomFileName DROPINFO.TXT
|
|||
|
CustomFileLine USERNAME
|
|||
|
CustomFileLine LOCALMODE
|
|||
|
CustomFileLine COMPORT
|
|||
|
CustomFileLine MODEMBPS
|
|||
|
CustomFileLine IGNORE
|
|||
|
CustomFileLine MINUTESLEFT
|
|||
|
CustomFileLine ANSI
|
|||
|
CustomFileLine CITY
|
|||
|
|
|||
|
Notice that the first "CustomFileLine" keyword in the
|
|||
|
configuration file corresponds to the first line in our
|
|||
|
DROPINFO.TXT file, the second "CustomFileLine" to the second
|
|||
|
line, and so on. Also notice that the keyword "IGNORE" is used
|
|||
|
for the line that contains the file creation time, since there
|
|||
|
is no CustomFileLine keyword that allows you to read this
|
|||
|
information.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 232
|
|||
|
|
|||
|
MULTIPLE PERSONALITY SYSTEM
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors Multiple Personality System allows the DOS
|
|||
|
version of OpenDoors to support multiple sysop function key /
|
|||
|
status line "personalities". Most commonly, you will use this
|
|||
|
feature in conjunction with the "Personality" setting in the
|
|||
|
OpenDoors configuration file, to allow the sysop to choose one
|
|||
|
of the built-in personalities that most closely mimics the BBS
|
|||
|
software they are using. OpenDoors includes the following
|
|||
|
personalities:
|
|||
|
|
|||
|
Configuration Keyword Manifest constant
|
|||
|
-----------------------------------------------------------
|
|||
|
Standard PER_OPENDOORS
|
|||
|
PCBoard PER_PCBOARD
|
|||
|
RemoteAccess PER_RA
|
|||
|
Wildcat PER_WILDCAT
|
|||
|
|
|||
|
The PCBoard, RemoteAccess and Wildcat personalities mimic the
|
|||
|
status lines and function keys used by the BBS packages with
|
|||
|
those names. The Standard personality, which is the personality
|
|||
|
used by default, is a trimmed down version of the status lines
|
|||
|
provided by OpenDoors 4.10 and earlier.
|
|||
|
|
|||
|
In addition to using the personalities supplied with OpenDoors,
|
|||
|
you can create your own personalities. This simply involves
|
|||
|
writing a function which OpenDoors will call to setup the sysop
|
|||
|
function keys and to display the status line.
|
|||
|
|
|||
|
Include the following line before your first call to any
|
|||
|
OpenDoors function:
|
|||
|
|
|||
|
od_control.od_mps = INCLUDE_MPS;
|
|||
|
|
|||
|
to include the multiple personality system in your program. This
|
|||
|
also enables the Personality setting in the configuration file,
|
|||
|
if you are using the configuration file system.
|
|||
|
|
|||
|
You can set the default personality to be used by OpenDoors by
|
|||
|
setting od_control.od_default_personality to one of the manifest
|
|||
|
constants listed in the table above. If you have included the
|
|||
|
multiple personality system in your program, this setting will
|
|||
|
determine the personality to use if the "Personality" option is
|
|||
|
not set in the configuration file, and your program does not
|
|||
|
later change the personality using the od_set_personality()
|
|||
|
function. If you do not include the multiple personality system
|
|||
|
in your program, this setting will determine the personality
|
|||
|
that will always be used.
|
|||
|
|
|||
|
Creating your own personality involves writing a single
|
|||
|
function.. Whenever OpenDoors needs to perform an operation that
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 233
|
|||
|
|
|||
|
involves the personality, it will call this function, passing
|
|||
|
one of the following message values:
|
|||
|
|
|||
|
PEROP_INITIALIZE Initialize the personality, installing any
|
|||
|
custom function keys.
|
|||
|
PEROP_DEINITIALIZE Deinitialize the personality, returning any
|
|||
|
changed settings to their original values.
|
|||
|
PEROP_CUSTOMKEY Indicates that a custom function key has
|
|||
|
been pressed.
|
|||
|
PEROP_DISPLAYx Where x is a number from 1 to 10. Indicates
|
|||
|
that the specified status line should be
|
|||
|
drawn from scratch.
|
|||
|
PEROP_UPDATEx Where x is a number from 1 to 10. Indicates
|
|||
|
that the specified status line should be
|
|||
|
updated to reflect any changes.
|
|||
|
|
|||
|
If you have enabled the multiple personality system by setting
|
|||
|
od_control.od_mps to INCLUDE_MPS, you can install your
|
|||
|
personality function into OpenDoors by calling
|
|||
|
od_add_personality(). When you call od_add_personality(), you
|
|||
|
supply a string containing the name of the personality, along
|
|||
|
with the top and bottom output line numbers to use. These line
|
|||
|
numbers specify the portion of the screen to use for door
|
|||
|
output, leaving the remainder of the screen available for
|
|||
|
displaying the personality's status line. Once the personality
|
|||
|
has been installed into OpenDoors, it can be selected by the
|
|||
|
sysop using the "Personality" configuration file option, or
|
|||
|
manually activated using the od_set_personality() function. For
|
|||
|
more information on the od_add_personality() function, see page
|
|||
|
47.
|
|||
|
|
|||
|
You can make your personality function the default personality
|
|||
|
by setting od_control.od_default_personality to point to your
|
|||
|
personality function. As is the case with the built-in
|
|||
|
personalities, this setting will be used as the default
|
|||
|
personality if you have enabled the multiple personality system
|
|||
|
by setting od_control.od_mps to INCLUDE_MPS. If you have not
|
|||
|
enabled the multiple personality system in this manner, your
|
|||
|
personality function will become the one and only personality
|
|||
|
used within your program. When creating your own personality,
|
|||
|
you can use the od_control.od_page_statusline variable to set
|
|||
|
which status line (if any) will be activated when the user pages
|
|||
|
the system operator.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 234
|
|||
|
|
|||
|
LOG FILE SYSTEM
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
In order for the system operator to monitor system activity and
|
|||
|
diagnose problems that have occurred while the system was
|
|||
|
unattended, it is common for BBS software and door programs to
|
|||
|
record major events in a log file. This log file typically
|
|||
|
records the date and time of evens such as a user logging on or
|
|||
|
off, transferring files, sending messages, paging the system
|
|||
|
operator, and similar activities. Sometimes the system operator
|
|||
|
will configure all of the pieces of software running on a
|
|||
|
particular node to write to a single log file. In other cases,
|
|||
|
the system operator will prefer to have each program write to
|
|||
|
its own log file. However, software serving one line of a multi-
|
|||
|
node BBS system should never attempt to write to the same log
|
|||
|
file that is used by another node.
|
|||
|
|
|||
|
OpenDoors uses the "FrontDoor format" log file standard. This
|
|||
|
was chosen as it is a clearly documented format that is quickly
|
|||
|
becoming the standard for bulletin board software log files. A
|
|||
|
segment from a log file produced by OpenDoors is listed below.
|
|||
|
|
|||
|
---------- Thu 25 Feb 93, Vote 6.00
|
|||
|
> 19:42:23 Brian Pirie entering door
|
|||
|
> 19:50:55 User paging system operator
|
|||
|
> 19:51:02 Entering sysop chat mode
|
|||
|
> 20:05:41 Terminating sysop chat mode
|
|||
|
> 20:18:32 User time expired, exiting door
|
|||
|
|
|||
|
To enable the OpenDoors log file system, simply include the
|
|||
|
following line before your first call to any OpenDoors function:
|
|||
|
|
|||
|
od_control.od_logfile = INCLUDE_LOGFILE;
|
|||
|
|
|||
|
When OpenDoors is initialized, it will open the log file and
|
|||
|
begin logging activities, unless logging has been disabled with
|
|||
|
the od_control.od_logfile_disable variable. The log file name
|
|||
|
will be taken from the od_control.od_logfile_name variable,
|
|||
|
which is usually set by the configuration file. If no logfile
|
|||
|
name has been set, OpenDoors will use the logfile named
|
|||
|
DOOR.LOG. Upon opening the log file, OpenDoors will write an
|
|||
|
entry indicating the time at which the use entered the door.
|
|||
|
|
|||
|
The od_control.od_prog_name variable sets the program name that
|
|||
|
is written to the log file immediately after the current date
|
|||
|
information. If this variable is not set, OpenDoors will write
|
|||
|
its own name and version information in this place.
|
|||
|
|
|||
|
When the OpenDoors log file system is enabled, OpenDoors will
|
|||
|
automatically produce logfile entries for the following events:
|
|||
|
|
|||
|
- User paging sysop, beginning of chat, end of chat
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 235
|
|||
|
|
|||
|
- Sysop entering or returning from DOS shell
|
|||
|
- User inactivity timeout or user time expired
|
|||
|
- Sysop dropping user back to BBS
|
|||
|
- Sysop hanging up on user, sysop locking out user
|
|||
|
- User hanging up on BBS
|
|||
|
- Your program calling the od_exit() function
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 236
|
|||
|
|
|||
|
MAKING DOORS MULTI-NODE-AWARE
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
While the majority of BBS systems have only a single phone line,
|
|||
|
allowing only one user to access the system at a time, there are
|
|||
|
also many multi-node BBS systems. On such systems, it is quite
|
|||
|
possible that more than one user may be using your door program
|
|||
|
simultaneously. OpenDoors itself is designed for both single-
|
|||
|
node and multi-node operation. However, if you want your program
|
|||
|
to operate correctly on multi-node systems, there are a number
|
|||
|
of concurrency issues that you must keep in mind when writing
|
|||
|
your own code.
|
|||
|
|
|||
|
Some door programs are designed to behave on multi-node systems
|
|||
|
just as they would on single-line BBSes. Others add special
|
|||
|
features only possible in multi-node environments. For instance,
|
|||
|
you may want to permit users to interact or chat with one
|
|||
|
another in "real time". Many simple doors may not require any
|
|||
|
special attention to multi-node capabilities. However, if your
|
|||
|
door must access any data files or other resources that are to
|
|||
|
be shared among nodes, it is necessary to carefully coordinate
|
|||
|
access to these resources.
|
|||
|
|
|||
|
There are two primary issues that are often of concern when
|
|||
|
creating door programs for multi-node systems. The first issue
|
|||
|
discussed below is how to coordinate concurrent file access
|
|||
|
between multiple node. The second topic we will deal with is the
|
|||
|
installation of door programs on multi-node systems.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
CONCURRENT FILE ACCESS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
One of the most important issues that arises when writing door
|
|||
|
programs for multi-node systems is how to coordinate
|
|||
|
simultaneous access to a single data file by multiple instances
|
|||
|
of your program. While it is generally safe to have multiple
|
|||
|
nodes reading simultaneously from a single file, having multiple
|
|||
|
nodes updating a file without any coordination can lead to lost
|
|||
|
updates and other problems. Consider, for example, the EX_VOTE.C
|
|||
|
example program that is included in your OpenDoors package. When
|
|||
|
the user votes on a poll, EX_VOTE.C must update the total number
|
|||
|
of votes for the user's answer. Such a program that is only
|
|||
|
intended for single node operation could do this by simply
|
|||
|
reading the current number of votes for the appropriate option,
|
|||
|
adding one to this total, and writing the updated total back to
|
|||
|
the file. However, if this approach where to be used on a multi-
|
|||
|
node system, it is quite possible that two users would vote on
|
|||
|
the same poll after both nodes have read the poll record into
|
|||
|
memory. In this situation, one node would add one to the total
|
|||
|
number of votes for the poll record that it has in memory, and
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 237
|
|||
|
|
|||
|
write the updated information to the file. The second node would
|
|||
|
then add one to its total, without reading the updated
|
|||
|
information written by the first node. When the second node then
|
|||
|
writes this information to the file, it overwrites the first
|
|||
|
node's total with its own. The final effect is that the second
|
|||
|
user's vote overwrites the first, and so the first user's vote
|
|||
|
is lost.
|
|||
|
|
|||
|
The solution to this problem is to lock a file unit for the
|
|||
|
entire update operation, to prevent other nodes from accessing
|
|||
|
the unit at the same time. This unit could be the entire file,
|
|||
|
or only a single record in the file. EX_VOTE.C locks its entire
|
|||
|
file when performing an update operation, but in other cases it
|
|||
|
may be more appropriate to only lock a single record in the
|
|||
|
file. The important thing to understand is that when one node
|
|||
|
locks a file unit, other nodes much wait until the first node is
|
|||
|
finished the update operation. This means that if one node is
|
|||
|
updating information that other nodes could possibly need access
|
|||
|
to, it should always perform the lock, read, write and unlock
|
|||
|
cycle as quickly as possible.
|
|||
|
|
|||
|
Let's look again at the approach taken by EX_VOTE.C. After the
|
|||
|
user has indicated which option he/she wishes to vote on, Vote
|
|||
|
attempts to open the file for exclusive access. By doing this,
|
|||
|
EX_VOTE.C in effect locks the entire file for the duration that
|
|||
|
it has the file open. If another node attempts to open the file
|
|||
|
while one node has it locked, the open operation will fail, and
|
|||
|
the C runtime library will set the errno variable to EACCES.
|
|||
|
This, in effect, tells you that another node is currently
|
|||
|
working on the file, and that you must wait your turn. In this
|
|||
|
case, EX_VOTE.C continues to retry the open operation until the
|
|||
|
other node is finished its update, at which time the open
|
|||
|
operation will succeed. This approach will even work when there
|
|||
|
are many nodes that are attempting to update the file at the
|
|||
|
same time. Whichever node first attempts to open the file will
|
|||
|
gain exclusive access to the file, and any additional nodes are
|
|||
|
forced to wait for access to the file. When one node finishes
|
|||
|
with the file, another node will gain access to the file
|
|||
|
(whichever happens to be the next node to re-attempt the open
|
|||
|
operation). This process continues until all waiting nodes have
|
|||
|
had a chance to perform their update. EX_VOTE.C will repeatedly
|
|||
|
try to open the file for up to 20 seconds, after which time it
|
|||
|
will give up, reporting an error which indicate that it is
|
|||
|
unable to access the file. During this waiting process,
|
|||
|
EX_VOTE.C repeatedly calls od_kernel(), so that sysop function
|
|||
|
keys, carrier detection and other essential door operations can
|
|||
|
continue to be performed.
|
|||
|
|
|||
|
After EX_VOTE.C has successfully secured exclusive access to the
|
|||
|
file, it first reads the record that it is going to update. It
|
|||
|
is important that this be done after the file unit is locked, in
|
|||
|
order to ensure that the copy of the record in memory matches
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 238
|
|||
|
|
|||
|
what is stored in the file. EX_VOTE.C then updates the record
|
|||
|
based on the question on which the user has voted, writes this
|
|||
|
information back to the file. EX_VOTE.C then immediately closes
|
|||
|
the file, allowing other nodes to also access the file.
|
|||
|
EX_VOTE.C is very carefully designed so that the file update
|
|||
|
operation can never be interrupted (for instance, no OpenDoors
|
|||
|
functions are called, which could detect a time-out and
|
|||
|
terminate the program while a file update operation is in
|
|||
|
progress), or delayed until the user makes a response. As such,
|
|||
|
the file unit is always unlocked (in this case, closed) within a
|
|||
|
fraction of a second after it was locked, or order that other
|
|||
|
nodes will never have to wait long for access to the file.
|
|||
|
|
|||
|
Here I have presented a detailed account of how EX_VOTE.C
|
|||
|
handles multi-node file access. While all of the details
|
|||
|
involved in coordinating multiple file access can be
|
|||
|
overwhelming at first, they will begin to come naturally to you,
|
|||
|
as you begin to always think in terms of multi-node scenarios.
|
|||
|
To summarize, the important elements that are typically involved
|
|||
|
in multi-node file access are:
|
|||
|
|
|||
|
A. Decide on an appropriate file unit to lock for your
|
|||
|
application. In simple cases, this can be the entire file.
|
|||
|
In other cases, you may wish to lock individual file
|
|||
|
records, using the appropriate runtime library functions.
|
|||
|
|
|||
|
B. Always perform update operations in lock, read, update,
|
|||
|
write, unlock cycles on individual file units. If there is a
|
|||
|
chance that other nodes will also need to access the file
|
|||
|
unit, ensure that the update operation cannot be interrupted
|
|||
|
or delayed until a user makes a response.
|
|||
|
|
|||
|
After you have designed your program for concurrent file access,
|
|||
|
how can you test it? If you don't have a multi-node BBS system
|
|||
|
that you have access to, you can perform most of your testing
|
|||
|
under a multitasking environment, with multiple copies of your
|
|||
|
program running in different windows.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 239
|
|||
|
|
|||
|
MULTI-NODE CONFIGURATION
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
A second issue that you may want to bear in mind is how door
|
|||
|
programs are typically setup on multi-node systems.
|
|||
|
Unfortunately, this may differ considerable depending upon which
|
|||
|
BBS software is being used. However, some of the issues that you
|
|||
|
may have to consider discussed below:
|
|||
|
|
|||
|
A. Your program must be able to locate the correct door
|
|||
|
information file for the appropriate node. Most BBS systems
|
|||
|
make separate door information files available to each node
|
|||
|
by one of the following means:
|
|||
|
|
|||
|
- By naming each node's door information file
|
|||
|
uniquely. (e.g. DORINFO1.DEF, DORINFO2.DEF.)
|
|||
|
|
|||
|
- By having a separate directory for each node's door
|
|||
|
information file. (e.g. \NODE1\DOOR.SYS,
|
|||
|
\NODE2\DOOR.SYS, etc.)
|
|||
|
|
|||
|
In the first case, OpenDoors can automatically select the
|
|||
|
correct door information file, assuming that it knows which
|
|||
|
node it is running on (see item C, below). In the later
|
|||
|
case, you must tell OpenDoors which directory it must look
|
|||
|
in to find the appropriate door information file. You may do
|
|||
|
this by any of the following means:
|
|||
|
|
|||
|
- By specifying the location of the file on the
|
|||
|
command line, if od_parse_cmd_line() is used.
|
|||
|
|
|||
|
- By providing a configuration file keyword to set
|
|||
|
the door information file location for each node.
|
|||
|
|
|||
|
- By providing a different configuration file for
|
|||
|
each node (See item B, below).
|
|||
|
|
|||
|
B. If you are using the OpenDoors configuration file system,
|
|||
|
node-specific options should not be used if each node is
|
|||
|
accessing the same configuration file. While it is possible
|
|||
|
to have a different configuration file for each node (the
|
|||
|
filename can be specified on the command line if
|
|||
|
od_parse_cmd_line() is used), in most cases the same
|
|||
|
configuration file will be used for all nodes. In this case,
|
|||
|
the node number, serial port information, and possible door
|
|||
|
information file location operations should not be used. If
|
|||
|
you are basing your configuration file on the example
|
|||
|
DOOR.CFG file that is included in the OpenDoors package, you
|
|||
|
may want to remove these options from the file.
|
|||
|
|
|||
|
C. In many cases, your program must also be able to determine
|
|||
|
which node it is running under. If this information is
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 240
|
|||
|
|
|||
|
available in the door information file, or is stored in a
|
|||
|
TASK environment variable, OpenDoors will automatically set
|
|||
|
the appropriate node number in od_control.od_node.
|
|||
|
Otherwise, if your program requires this information, it
|
|||
|
should be specified on the program's command line. The
|
|||
|
od_parse_cmd_line() function supports this option. Reasons
|
|||
|
that your program might need to know the current node number
|
|||
|
include:
|
|||
|
|
|||
|
- In order for OpenDoors to display this information
|
|||
|
correctly on the status line.
|
|||
|
|
|||
|
- In order to determine which configuration file to
|
|||
|
read or which node directory in which to look for
|
|||
|
the door information file.
|
|||
|
|
|||
|
- In order for OpenDoors to know which door
|
|||
|
information file to read (e.g. DORINFO1.DEF,
|
|||
|
DORINFO2.DEF. etc.)
|
|||
|
|
|||
|
- In order to provide any form of real-time
|
|||
|
interaction between nodes, such as inter-node chat.
|
|||
|
|
|||
|
D. If your program is running under MS-DOS, and multi-node file
|
|||
|
access is being coordinated by locking part or all of a
|
|||
|
file, the SHARE.EXE utility must be installed.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 241
|
|||
|
|
|||
|
7777777
|
|||
|
77
|
|||
|
77
|
|||
|
77
|
|||
|
77
|
|||
|
77
|
|||
|
77
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
CHAPTER 7 - TROUBLESHOOTING AND GETTING ASSISTANCE WITH OPENDOORS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
ABOUT THIS CHAPTER
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
This chapter is perhaps the most important section of this
|
|||
|
entire manual. Here, we provide detailed instructions to help
|
|||
|
you in tracing the source of problems in programs written with
|
|||
|
OpenDoors. Included in this chapter is a step-by-step OpenDoors
|
|||
|
troubleshooting guide and a chart listing common problems and
|
|||
|
their solutions. Also included in this chapter is information on
|
|||
|
the many means available to you for getting more help with
|
|||
|
OpenDoors, including the OpenDoors support BBS, the OpenDoors
|
|||
|
EchoMail conference, and how to get in touch with me. It is
|
|||
|
strongly encouraged that you take the time to read through this
|
|||
|
chapter.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
TROUBLESHOOTING PROBLEMS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
If you are experiencing difficulty with a program that you are
|
|||
|
writing using OpenDoors, it is suggested that you follow the
|
|||
|
steps listed below in order to quickly solve your problem. Also,
|
|||
|
be sure to check to "solutions to common problems" section of
|
|||
|
this manual. There are many common difficulties which people
|
|||
|
have with OpenDoors, that can easily be fixed using the
|
|||
|
instructions in the "common solutions" section. Also, if you are
|
|||
|
having difficulty solving a problem yourself, do not hesitate to
|
|||
|
get in touch with me, as I am always happy to help with any
|
|||
|
problems. In addition, you may find the other means of OpenDoors
|
|||
|
support (described latter in this chapter), invaluable in
|
|||
|
solving difficulties with OpenDoors.
|
|||
|
|
|||
|
Keep in mind that most programs you write will have some "bugs"
|
|||
|
to begin with, and you should expect to spend at least 50% of
|
|||
|
any programming project tracing down and solving errors and
|
|||
|
bugs. While it would be nice if every program written worked
|
|||
|
correctly the first time, it is a fact of life that debugging is
|
|||
|
and always has been an important part of the software life-
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 242
|
|||
|
|
|||
|
cycle. In fact, what most often separates the good programs from
|
|||
|
the bad is the amount of time their programmer's spend debugging
|
|||
|
and improving them. Unfortunately, it is difficult, if not
|
|||
|
impossible, to come up with a "magic formula" for debugging
|
|||
|
software. Debugging software is really more of an art than a
|
|||
|
science. However, there are some basic guidelines, which if
|
|||
|
followed, can greatly ease the task of software debugging.
|
|||
|
|
|||
|
As with all problem solving, the secret to software debugging
|
|||
|
lies in obtaining as much information about the problem as
|
|||
|
possible. While it is sometimes possible to solve a bug by
|
|||
|
making intuitive changes in your program, or in re-writing a
|
|||
|
piece of code to solve the problem by a different means,
|
|||
|
debugging most often requires more of a "planned attack". This
|
|||
|
planned attack generally involves little more than learning as
|
|||
|
much about what is going wrong as possible. The first step in
|
|||
|
solving a bug usually lies in locating the source of the
|
|||
|
problem. Once you have located the problem, solving it is often
|
|||
|
a relatively simple procedure. In locating the source of your
|
|||
|
bug, the use of a software debugger, such as the one built into
|
|||
|
the Turbo C(++) / Borland C++ integrated development
|
|||
|
environment, can be invaluable.
|
|||
|
|
|||
|
When debugging programs written with OpenDoors, you should also
|
|||
|
follow the steps listed below, in order to obtain more
|
|||
|
information related to the problem you are trying to solve:
|
|||
|
|
|||
|
1.) Re-read the section(s) of this manual, your Turbo C(++) /
|
|||
|
Borland C++ manuals and your program's source code, which
|
|||
|
apply to the problem you are experiencing.
|
|||
|
|
|||
|
2.) Check the solutions to common problems section below. The
|
|||
|
most common problems with OpenDoors can be solved using
|
|||
|
this simple chart.
|
|||
|
|
|||
|
3.) Check the value in the od_errno variable, which will often
|
|||
|
provide vital clues as to the source of the problem. Use of
|
|||
|
the od_errno variable is described in the section below.
|
|||
|
|
|||
|
4.) If you are still stuck, please feel more than free to get
|
|||
|
in touch with me! (see the end of this chapter for
|
|||
|
information on reaching me) I am always more than happy to
|
|||
|
help with any OpenDoors or general programming problems!
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 243
|
|||
|
|
|||
|
SOLUTIONS TO COMMON PROBLEMS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
Below, several common difficulties with OpenDoors are listed,
|
|||
|
along with suggested solutions to these problems. If you are
|
|||
|
experiencing any difficulty with a program that you have written
|
|||
|
with OpenDoors, we would suggest that you read this section
|
|||
|
thoroughly. Here, the common problem is listed in the left
|
|||
|
margin, and the solutions listed on the right portion of the
|
|||
|
page.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
PROGRAM 1.) Check that the compiler is able to locate the OpenDoors
|
|||
|
WON'T header file, "OPENDOOR.H". This can be accomplished either by
|
|||
|
COMPILE placing this header file in the same directory as your other
|
|||
|
header files (such as STDIO.H, etc.), or by placing the header
|
|||
|
file in the current directory.
|
|||
|
|
|||
|
2.) Be sure that you are linking your program with the correct
|
|||
|
library for the memory model you are using. (See the section on
|
|||
|
compiling with OpenDoors). Also be sure that both the source
|
|||
|
code file for your program (such as EX_VOTE.C) and the library
|
|||
|
file are listed in your project file, and that the project file
|
|||
|
is loaded. For more information on compiling programs written
|
|||
|
with OpenDoors, see page 22.
|
|||
|
|
|||
|
3.) If you have tried the above solutions, and your program
|
|||
|
still won't compile, then the problem is most likely an error in
|
|||
|
your source code file. If you are unable to resolve your
|
|||
|
problem, feel free to get in touch with me.
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
SCREEN If you are using the od_clr_scr() function to clear the screen,
|
|||
|
WILL NOT but are not getting any results, this is likely because the user
|
|||
|
CLEAR online has screen clearing turned off. If you wish to force
|
|||
|
screen clearing regardless of the user's screen clearing
|
|||
|
settings (this is probably not a good idea), use the function
|
|||
|
call od_disp_emu("\xc", TRUE);
|
|||
|
|
|||
|
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
FIXUP This problem was probably caused by a mismatch between your
|
|||
|
OVERFLOW memory model selection in your compiler, and the memory model
|
|||
|
ERROR library you are using. See the section on compiling programs
|
|||
|
with OpenDoors for more information on the correct library you
|
|||
|
should be using for your memory model selection.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 244
|
|||
|
|
|||
|
OPENDOORS SUPPORT
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The powerful and easy to use door toolkit and this comprehensive
|
|||
|
manual are only two portions of how OpenDoors helps you to write
|
|||
|
BBS door and similar programs. The third element of OpenDoors is
|
|||
|
the extensive OpenDoors support mechanisms. The OpenDoors email
|
|||
|
conference and support BBS each give you a chance to share ideas
|
|||
|
and source code with other OpenDoors programmers. A lot of
|
|||
|
information concerning OpenDoors, along with the newest version
|
|||
|
and online registration, is available through the OpenDoors
|
|||
|
World Wide Web site. In addition to these sources, I am also
|
|||
|
more than happy to answer any of your questions, or hear any
|
|||
|
suggestions for future versions of OpenDoors. The remainder of
|
|||
|
this chapter provides more information on the various sources of
|
|||
|
OpenDoors support. Also keep your eyes open for the "OpenDoors
|
|||
|
Tech Journal", that is produced on a regular basis by the users
|
|||
|
of OpenDoors. Included in this newsletter is information on
|
|||
|
OpenDoors and future versions, questions and answers about
|
|||
|
OpenDoors and BBS door / utility programming in general, sample
|
|||
|
source code, and much more.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
THE OPENDOORS SUPPORT BBS
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
One means of receiving OpenDoors support is via the OpenDoors
|
|||
|
BBS. Below is an outline of some of what is available from the
|
|||
|
OpenDoors BBS:
|
|||
|
|
|||
|
- The newest version of this package is always available
|
|||
|
for download.
|
|||
|
|
|||
|
- Also available for download is example source code and
|
|||
|
other files which you may find helpful when writing
|
|||
|
programs with OpenDoors.
|
|||
|
|
|||
|
- Access to the OpenDoors conference where OpenDoors
|
|||
|
programmers can share ideas, source code, and receive
|
|||
|
help with difficulties or with learning OpenDoors.
|
|||
|
|
|||
|
- Get in touch with me with any questions, comments,
|
|||
|
suggestions or bug reports.
|
|||
|
|
|||
|
- Other files by yours truly, which may be of use in you
|
|||
|
programming, such as a registration key system, and so
|
|||
|
on.
|
|||
|
|
|||
|
All users receive full access upon their first call to the
|
|||
|
OpenDoors BBS. The North American phone number for the support
|
|||
|
BBS is:
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 245
|
|||
|
|
|||
|
|
|||
|
+1 (613) 599-5554
|
|||
|
|
|||
|
The OpenDoors support BBS also has a FidoNet address, 1:243/8.
|
|||
|
If you are interested in a list of files available from the
|
|||
|
support BBS, simply file-request "FILES". To receive the newest
|
|||
|
version of OpenDoors, you can file-request "ODOORS".
|
|||
|
|
|||
|
|
|||
|
|
|||
|
THE OPENDOORS WORD WIDE WEB SITE
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors World Wide Web site has been setup to provide up-
|
|||
|
to-date information on OpenDoors. This includes news concerning
|
|||
|
OpenDoors, OpenDoors tips and techniques, pointers to other
|
|||
|
sources of OpenDoors support, online registration and access to
|
|||
|
the newest version of OpenDoors.
|
|||
|
|
|||
|
The current URL (address) of the OpenDoors Web site is:
|
|||
|
|
|||
|
http://omega.scs.carleton.ca/~ug930227/opendoor.html
|
|||
|
|
|||
|
However, I plan on moving this to a new location some time this
|
|||
|
year. If you are unable to reach the OpenDoors Web site through
|
|||
|
the above URL, please get in touch with me, and I will be able
|
|||
|
to tell you where it has moved to.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
THE OPENDOORS CONFERENCE
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
The OpenDoors conference is devoted to OpenDoors and BBS / door
|
|||
|
/ BBS utility programming in general. The OpenDoors conference
|
|||
|
serves as a place where people working with OpenDoors can share
|
|||
|
ideas, source code examples, and other tricks and techniques.
|
|||
|
Through the OpenDoors conference you can receive help with
|
|||
|
OpenDoors and programming in general. Also available through the
|
|||
|
OpenDoors conference is information on future versions of
|
|||
|
OpenDoors and recent developments of concern to BBS door and
|
|||
|
utility programmers. The OpenDoors conference is also a place
|
|||
|
for suggestions for future versions of OpenDoors, OpenDoors bug
|
|||
|
reports, a place to announce the availability of your programs,
|
|||
|
and much more information of interest to programmers working
|
|||
|
with OpenDoors.
|
|||
|
|
|||
|
You can become involved in the OpenDoors Conference by the
|
|||
|
following means:
|
|||
|
|
|||
|
- The OpenDoors conference is available as an Internet mailing
|
|||
|
list. to subscribe, send email to listserv@hms.com and put
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 246
|
|||
|
|
|||
|
SUBSCRIBE OPENDOOR in the message body. For help on using the
|
|||
|
listserver you can send email to listserv@hms.com and put
|
|||
|
HELP in the message body.
|
|||
|
|
|||
|
- The OpenDoors conference is available on the FidoNet North
|
|||
|
America echo backbone, and so is available to a large number
|
|||
|
of BBS systems. FidoNet capable systems may also obtain an
|
|||
|
OpenDoors feed directly from the moderator, Brian Pirie.
|
|||
|
|
|||
|
|
|||
|
GETTING IN TOUCH WITH ME
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
|
|||
|
If you have any questions about OpenDoors, would like help with
|
|||
|
any programs that your are writing, or have any suggestions for
|
|||
|
future versions of OpenDoors, please feel free to get in touch
|
|||
|
with me. You can get in touch with me by any of the following
|
|||
|
means:
|
|||
|
|
|||
|
- The best way to contact me is by Internet email. My primary
|
|||
|
email address is:
|
|||
|
|
|||
|
pirie@msn.com
|
|||
|
|
|||
|
If you have difficulty contacting me through this address, I
|
|||
|
may also be reached through the address:
|
|||
|
|
|||
|
aa522@freenet.carleton.ca
|
|||
|
|
|||
|
- By writing a message to me in the OpenDoors support
|
|||
|
conference. For more information on the OpenDoors conference,
|
|||
|
see the previous section of this chapter.
|
|||
|
|
|||
|
- By calling the OpenDoors support BBS. Information on the
|
|||
|
support BBS is provided earlier on in this chapter.
|
|||
|
|
|||
|
- By sending your question or comment by Fax. My fax number is:
|
|||
|
|
|||
|
+1 (613) 599-5554
|
|||
|
|
|||
|
- By FidoNet NetMail. My address is:
|
|||
|
|
|||
|
1:243/8
|
|||
|
|
|||
|
While I would like to be able to reply to all NetMail
|
|||
|
messages by CrashMail, I am afraid I simply can not afford to
|
|||
|
do this. So, if you choose to send NetMail, please indicate
|
|||
|
whether you would like me to reply by routed NetMail (this
|
|||
|
may not work, if routed NetMail is not available in your
|
|||
|
area), or to place the message on hold for you to poll and
|
|||
|
pick up.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 247
|
|||
|
|
|||
|
- By conventional mail. My postal address is:
|
|||
|
|
|||
|
Brian Pirie
|
|||
|
117 Cedarock Drive
|
|||
|
Kanata ON K2M 2H5
|
|||
|
Canada
|
|||
|
|
|||
|
|
|||
|
I try to respond to all correspondences as soon as possible.
|
|||
|
|
|||
|
If you are having some sort of difficulty with OpenDoors, the
|
|||
|
more detailed information you supply (such as source code to the
|
|||
|
program that is causing the problem, how to duplicate the
|
|||
|
problem, and so on), the more quickly I will be able to
|
|||
|
determine the source of your problem. Also, before you write
|
|||
|
about a problem with OpenDoors, you may wish to be sure that you
|
|||
|
have read and followed the instructions in the section on
|
|||
|
troubleshooting, found on page 242. While I do not mind taking
|
|||
|
the time to answer any questions related to OpenDoors, you may
|
|||
|
be able to save yourself the time of writing and waiting for a
|
|||
|
response - simply by following the instructions in the
|
|||
|
troubleshooting section. More often than not, the answer to
|
|||
|
questions I receive is already in this manual.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 248
|
|||
|
|
|||
|
A
|
|||
|
AAA
|
|||
|
AA AA
|
|||
|
AAAAAAA
|
|||
|
AA AA
|
|||
|
AA AA
|
|||
|
AA AA
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
APPENDIX A - CONTENTS OF PACKAGE
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
The main OpenDoors package is distributed in the form of a
|
|||
|
single, compressed archive file. Thus, you should have received
|
|||
|
this version of OpenDoors in a file whose name began with
|
|||
|
ODOORS60. The files listed below should be included in your
|
|||
|
OpenDoors package. If any of these files are missing, you will
|
|||
|
probably want to look for the most recent version of OpenDoors
|
|||
|
from another source. Note that the medium and compact memory
|
|||
|
model libraries are now distributed separately from the main
|
|||
|
OpenDoors package.
|
|||
|
|
|||
|
MISCALENEOUS FILES
|
|||
|
FILE_ID.DIZ Description of the OpenDoors package
|
|||
|
DORINFO1.DEF Sample door info file for testing programs
|
|||
|
DOOR.CFG Sample OpenDoors configuration file
|
|||
|
|
|||
|
EXAMPLE PROGRAMS
|
|||
|
EX_HELLO.C A simple program using OpenDoors
|
|||
|
EX_CHAT.C Split-screen sysop chat program
|
|||
|
EX_MUSIC.C Example of ANSI music in OpenDoors
|
|||
|
EX_SKI.C Simple slalom skiing action game
|
|||
|
EX_VOTE.C Example of an online voting program
|
|||
|
VOTEDOS.EXE Compiled version of EX_VOTE.C - DOS version
|
|||
|
VOTEWIN.EXE EX_VOTE.C compiled - Windows version
|
|||
|
DTRON.EXE Free utility for running Win 95 doors
|
|||
|
|
|||
|
THE LIBRARY FILES
|
|||
|
ODOORS.LIB DOS, Small memory model library
|
|||
|
ODOORL.LIB DOS, Large memory model library
|
|||
|
ODOORH.LIB DOS, Huge memory model library
|
|||
|
ODOORW.LIB Win32 import library (Microsoft version)
|
|||
|
ODOORS60.DLL The OpenDoors Win32 DLL
|
|||
|
|
|||
|
THE HEADER FILE
|
|||
|
OPENDOOR.H OpenDoors header file
|
|||
|
|
|||
|
OPENDOORS DOCUMENATION
|
|||
|
ORDER.TXT Easy-to-print order form
|
|||
|
OPENDOOR.TXT OpenDoors programmer's manual (this file)
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 249
|
|||
|
|
|||
|
BBBBBB
|
|||
|
BB BB
|
|||
|
BB BB
|
|||
|
BBBBBB
|
|||
|
BB BB
|
|||
|
BB BB
|
|||
|
BBBBBB
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
APPENDIX B - CHANGES FOR THIS VERSION
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
Since version 5.00, a lot of work has gone into OpenDoors. Many
|
|||
|
months were spent cleaning up and restructuring the OpenDoors
|
|||
|
code in a process that has touched nearly every line of the
|
|||
|
OpenDoors code. As well as making the OpenDoors source code
|
|||
|
easier to maintain, this has also involved making OpenDoors more
|
|||
|
easily portable to 32-bit multithreaded platforms.
|
|||
|
|
|||
|
After this effort was completed, I began work on a Win32 port of
|
|||
|
OpenDoors. The OpenDoors package now includes both DOS and Win32
|
|||
|
versions of the library, giving you the option of developing for
|
|||
|
one, the other, or both platforms. The Win32 version of
|
|||
|
OpenDoors is highly multithreaded to give you the best possible
|
|||
|
performance. With some exciting new BBS packages that are
|
|||
|
designed specifically for Windows 95/NT in the works, the Win32
|
|||
|
version of OpenDoors gives you a head start on developing
|
|||
|
applications that will integrate smoothly with these new BBS
|
|||
|
packages. Even if your programs will only be used with DOS-based
|
|||
|
BBS packages, the Win32 version of OpenDoors allows you to take
|
|||
|
advantage of the Windows 95 GUI, multithreading capabilities and
|
|||
|
flat 32-bit memory model (no more DOS 64K limitations and
|
|||
|
different memory models to worry about!). It also allows you to
|
|||
|
access services that are only available to Windows based
|
|||
|
programs, such as ODBC for easy database access, and MAPI for
|
|||
|
email, fax and other messaging.
|
|||
|
|
|||
|
While this internal restructuring of OpenDoors and the Win32
|
|||
|
port of the package would be enough alone to count as a major
|
|||
|
new version, version 6.00 also includes many exciting new
|
|||
|
features, enhancements and bug fixes:
|
|||
|
|
|||
|
- A new option, "silent mode", has been added. When operating
|
|||
|
in silent mode, OpenDoor's local sysop interface is disabled,
|
|||
|
so that no output is displayed on the local screen, and no
|
|||
|
input is accepted from the local keyboard. Silent mode can be
|
|||
|
activated by setting od_control.od_silent_mode = TRUE prior
|
|||
|
to the first call to any OpenDoors function, or by specifying
|
|||
|
-SILENT on the command-line (if od_parse_cmd_line() is used).
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 250
|
|||
|
|
|||
|
- OpenDoors now fully supports RTS/CTS flow control, which is
|
|||
|
enabled by default. To disable the use of the RTS/CTS lines
|
|||
|
for flow control, use od_control.od_com_flow_control.
|
|||
|
|
|||
|
- In version 5.00, the built-in serial I/O module would be
|
|||
|
unable to initialize the serial port if the "Uses Serial
|
|||
|
Ports" option was turned off in DesqView or other
|
|||
|
multitasking environments. When this option is turned off,
|
|||
|
multitasking environments typically remove the serial port
|
|||
|
information from the BIOS data segment. However, it seems
|
|||
|
that other serial I/O software commonly uses the default
|
|||
|
address for each port if this information is not available
|
|||
|
from the BIOS data area. OpenDoors 6.00 has been changed to
|
|||
|
do the same thing.
|
|||
|
|
|||
|
- OpenDoors now provides a standard command-line processing
|
|||
|
function, od_parse_cmd_line(). This function provides a one-
|
|||
|
step method of adding support for many common command-line
|
|||
|
options to your program. This function handles options such
|
|||
|
as serial port information (including non-standard serial
|
|||
|
port configurations), node number information, user
|
|||
|
information, drop file and configuration file locations,
|
|||
|
silent mode (turns off the local interface for efficiency and
|
|||
|
privacy), one step local login without a drop file, and more.
|
|||
|
For details, run the included example program (votedos.exe or
|
|||
|
votewin.exe) with the -help command line option. The
|
|||
|
od_parse_cmd_line() function is particularly helpful in
|
|||
|
several situations:
|
|||
|
|
|||
|
- When your program is being used on a multi-node
|
|||
|
system.
|
|||
|
- Allows potential users to try your program in local
|
|||
|
mode by just specifying -local on the command line.
|
|||
|
- Allows door information to be specified on the
|
|||
|
command line, rather than through a drop file, as
|
|||
|
supported by some BBS systems
|
|||
|
- Allows serial port handle to be directly passed to
|
|||
|
the program under Windows-based BBS systems that
|
|||
|
support this.
|
|||
|
- Provides customizable command-line help (in a
|
|||
|
window in the Win32 version of OpenDoors).
|
|||
|
|
|||
|
- A new function, od_sleep(), allows you to suspend program
|
|||
|
execution for the specified number of milliseconds, releasing
|
|||
|
time to other processes in a multitasking environment. A call
|
|||
|
of od_sleep(0) will yield control to any other processes
|
|||
|
without forcing program execution to be suspended if no other
|
|||
|
processes are waiting.
|
|||
|
|
|||
|
- The sysop page timing mechanism has been reworked. By
|
|||
|
default, od_control.od_okaytopage is set to PAGE_USE_HOURS,
|
|||
|
only allowing the sysop to be paged during the paging hours
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 251
|
|||
|
|
|||
|
set by od_pagestartmin and od_pageendmin. Rather than
|
|||
|
allowing the sysop to be paged at any time of the day or
|
|||
|
night, the default now only permits sysop paging from 8:00am
|
|||
|
to 10:00pm. Setting paging start and end time to the same
|
|||
|
value now correctly permits paging 24 hours a day.
|
|||
|
|
|||
|
- OpenDoors now provides a multi-line editor function,
|
|||
|
od_multiline_edit(). This editor allows the user to enter or
|
|||
|
edit any information that spans multiple lines, such as email
|
|||
|
messages or text files. The editor can be configured to
|
|||
|
operate in full screen mode, or in any smaller area of the
|
|||
|
screen that you specify. The editor is designed to be both
|
|||
|
easy to use, and highly customizable.
|
|||
|
|
|||
|
- One new feature of OpenDoors 5.00 was somehow omitted from
|
|||
|
the manual. Since version 5.00, it has been possible to set
|
|||
|
the name of the drop file to use by including both a path and
|
|||
|
filename in the od_control.info_path variable.
|
|||
|
|
|||
|
- All known inaccuracies and missing information from the
|
|||
|
version 5.00 manual have been corrected.
|
|||
|
|
|||
|
- The example program, ex_chat.c, has been expanded to
|
|||
|
demonstrate how OpenDoor's standard chat mode can be replaced
|
|||
|
with the split-screen chat mode within your own programs.
|
|||
|
|
|||
|
- The multiple ex_vote?.c example files have been combined and
|
|||
|
simplified into a single example program, as it was prior to
|
|||
|
version 5.00.
|
|||
|
|
|||
|
- A memory leak in the od_popup_menu() function has been fixed.
|
|||
|
|
|||
|
- od_control.od_open_handle can be used to provide OpenDoors
|
|||
|
with an already open serial port handle on platforms that
|
|||
|
support it. Currently, this only applies to the Win32 version
|
|||
|
of OpenDoors. If this variable is not set to a non-zero value
|
|||
|
prior to calling the first OpenDoors function (other than
|
|||
|
od_parse_cmd_line()), then OpenDoors proceeds normally,
|
|||
|
opening the serial port itself, and closing the serial port
|
|||
|
before exiting.
|
|||
|
|
|||
|
- A new switch, od_emu_simulate_modem, has been added to
|
|||
|
od_control. When this is set to its default value of FALSE,
|
|||
|
the OpenDoors terminal emulator displays at full speed, as it
|
|||
|
has always done. However, when this flag is set to TRUE, the
|
|||
|
emulation functions will display text at approximately the
|
|||
|
same speed as it would be displayed when sent over the modem,
|
|||
|
based on the current connect speed. This allows animations to
|
|||
|
be displayed locally at the same speed as they would appear
|
|||
|
on the remote system. This switch affects the following
|
|||
|
functions:
|
|||
|
od_disp_emu()
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 252
|
|||
|
|
|||
|
od_send_file()
|
|||
|
od_hotkey_menu()
|
|||
|
|
|||
|
- OpenDoors now distinguishes between the serial port BPS rate
|
|||
|
(od_control.baud) and the connection BPS (a new variable,
|
|||
|
od_control.od_connect_speed). In situations where a separate
|
|||
|
value is available for the connect speed (e.g., this caller
|
|||
|
has connected at 14400 bps), OpenDoors will now display that
|
|||
|
value on the status line. Currently, a separate connect speed
|
|||
|
is only obtained from the DOOR.SYS drop file format.
|
|||
|
|
|||
|
- The latest versions of the QBBS EXITINFO.BBS drop file is now
|
|||
|
supported.
|
|||
|
|
|||
|
- A new od_edit_str() flag, EDIT_FLAG_SHOW_SIZE, has been
|
|||
|
added. By default, the fields shown by od_edit_str() are one
|
|||
|
character larger than the number of characters that may be
|
|||
|
entered. This is for esthetic reasons, so that the cursor
|
|||
|
remains within the highlighted field, even after a full
|
|||
|
string has been entered. However, you may prefer that the
|
|||
|
highlighted area reflect the exact number of characters that
|
|||
|
are permitted. This can be accomplished by setting
|
|||
|
EDIT_FLAG_SHOW_SIZE.
|
|||
|
|
|||
|
- Tab characters ('\t') are now expanded on the local display.
|
|||
|
|
|||
|
- The new RemoteAccess 2.50 EXITINFO.BBS fields are now
|
|||
|
supported. This has included the addition of the following
|
|||
|
new od_control members: user_rip_ver, user_attrib3 and
|
|||
|
system_last_handle.
|
|||
|
|
|||
|
- When operating in "forced automatic local" mode (where no
|
|||
|
door information file used), OpenDoors now displays a window
|
|||
|
in which in prompts for the user's name at startup time. This
|
|||
|
new feature can be disabled by specifying the DIS_NAME_PROMPT
|
|||
|
od_control.od_disable flag.
|
|||
|
|
|||
|
- The latest version of the SFDOORS.DAT drop file is now
|
|||
|
supported. SFMAIN.DAT, SFSYSOP.DAT, SFFILE.DAT and
|
|||
|
SFMESS.DAT, which are in the same format as SFDOORS.DAT, are
|
|||
|
also now recognized.
|
|||
|
|
|||
|
- A new function, od_get_input(), allows you to easily handle
|
|||
|
extended keys in your program, such as arrow keys, insert and
|
|||
|
function keys.
|
|||
|
|
|||
|
- The OpenDoors configuration file system will now display an
|
|||
|
error and exit the program if a particular configuration file
|
|||
|
name has been specified, and that configuration file cannot
|
|||
|
be found.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 253
|
|||
|
|
|||
|
CCCC
|
|||
|
CC CC
|
|||
|
CC
|
|||
|
CC
|
|||
|
CC
|
|||
|
CC CC
|
|||
|
CCCC
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
APPENDIX C - FUTURE VERSIONS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
While I cannot make any promises about what features and changes
|
|||
|
will be seen in future versions of OpenDoors, I would like to
|
|||
|
take a moment to tell you a bit about some of the features you
|
|||
|
can expect to see in future versions of OpenDoors
|
|||
|
|
|||
|
As you are probably already aware, OpenDoors is a constantly
|
|||
|
evolving package. To help meet the needs of programmers working
|
|||
|
with OpenDoors, nearly every idea and change that is made to the
|
|||
|
package results from the suggestions and comments I receive from
|
|||
|
the people using OpenDoors. For this reason, I will most likely
|
|||
|
continue to produce new versions of OpenDoors for as long as
|
|||
|
there is a demand and ideas for upgrades. There certainly is no
|
|||
|
shortage of either of this right now.
|
|||
|
|
|||
|
Some of the features that I am considering for upcoming versions
|
|||
|
of OpenDoors include:
|
|||
|
|
|||
|
-Telnet support.
|
|||
|
|
|||
|
- HTML support.
|
|||
|
|
|||
|
- Direct interfacing with new Windows 95/NT BBS packages.
|
|||
|
|
|||
|
- Further features to help writing multi-node door
|
|||
|
programs.
|
|||
|
|
|||
|
-Direct interfacing with more BBS systems.
|
|||
|
|
|||
|
-Additional RIP graphics support, including possible
|
|||
|
display of RIP images on local screen.
|
|||
|
|
|||
|
-Possible support for additional programming languages and
|
|||
|
operating systems.
|
|||
|
|
|||
|
- Improvements to existing OpenDoors features, such as more
|
|||
|
configuration file options, multiple log file formats,
|
|||
|
and many smaller changes.
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 254
|
|||
|
|
|||
|
DDDDD
|
|||
|
DD DD
|
|||
|
DD DD
|
|||
|
DD DD
|
|||
|
DD DD
|
|||
|
DD DD
|
|||
|
DDDDD
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
APPENDIX D - SPECIAL THANKS
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
There are many people who I would like to thank, for their
|
|||
|
suggestions, ideas and assistance in making OpenDoors what it is
|
|||
|
today. Among those I would like to thank are:
|
|||
|
|
|||
|
- Everyone who has registered OpenDoors.
|
|||
|
|
|||
|
- All those who participate in the OpenDoors conference,
|
|||
|
who provide many suggestions, bug reports and words of
|
|||
|
encouragement.
|
|||
|
|
|||
|
- Those who on the OpenDoors beta team. Thank-you for
|
|||
|
putting up with the problems along the way. You have
|
|||
|
certainly helped to make OpenDoors a better package. The
|
|||
|
people who have helped to beta test OpenDoors 6.00 are:
|
|||
|
|
|||
|
Robert Bouman
|
|||
|
Doug Crone
|
|||
|
Greg Diener
|
|||
|
Patrick Dixon
|
|||
|
Joel Downer
|
|||
|
Mike Fenton
|
|||
|
Les Howie
|
|||
|
Vince Jacobs
|
|||
|
Scott Jibben
|
|||
|
Dean Mills
|
|||
|
Jimmy Rose
|
|||
|
Jim Woodward
|
|||
|
Timothy Ward
|
|||
|
Mark Williams
|
|||
|
|
|||
|
- Last but not least, I would like to thank my wife, Pearl,
|
|||
|
for her support during the long hours that it has taken
|
|||
|
to put OpenDoors together.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 255
|
|||
|
|
|||
|
GGGG
|
|||
|
GG GG
|
|||
|
GG
|
|||
|
GG GGGG
|
|||
|
GG GG
|
|||
|
GG GG
|
|||
|
GGGG
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
GLOSSARY
|
|||
|
|
|||
|
ANSI ANSI is an acronym for "American National Standards Institute".
|
|||
|
One of the standards approved by ANSI is a terminal display
|
|||
|
protocol which allows (in this case), BBS software to perform
|
|||
|
certain display functions such as changing the color of
|
|||
|
displayed text, or moving the location of the cursor on the
|
|||
|
screen. The majority, though not all, BBS users use terminal
|
|||
|
software with ANSI capabilities. Any users that do not have
|
|||
|
graphics display capabilities, will be using ASCII mode,
|
|||
|
instead. The ANSI terminal protocol is sometimes referred to as
|
|||
|
"ANSI graphics". It is graphic in the sense that it provides
|
|||
|
more visual control than an ASCII TTY terminal does, but does
|
|||
|
not imply any support for bit-mapped nor vector graphics.
|
|||
|
Compare ASCII and AVATAR.
|
|||
|
|
|||
|
|
|||
|
API API is an acronym for "Application Program(er) Interface". An
|
|||
|
API is a set of well documented functions, variables and data
|
|||
|
types that you can use to access certain services from your
|
|||
|
program. When you write any C program that uses standard C
|
|||
|
library functions such as fopen() or strcpy(), you are using a
|
|||
|
sort of API. When you use OpenDoors functions such as
|
|||
|
od_printf() or od_get_key(), you are using functions that are
|
|||
|
part of the OpenDoors API. Operating systems provide their own
|
|||
|
APIs that allow programs to gain access to operating system
|
|||
|
features such as screen display, file I/O and communications.
|
|||
|
The API provided by Microsoft Windows 95 and Windows NT is
|
|||
|
called the Win32 API.
|
|||
|
|
|||
|
|
|||
|
ASCII ASCII (pronounced "ass-key") is an acronym for "American
|
|||
|
Standard Code for Information Interchange", and is a definition
|
|||
|
of a set of 128 letters, number and symbols, which can be
|
|||
|
displayed by computer systems. Also, when used within the domain
|
|||
|
of BBS software, ASCII mode is often used to refer to the lack
|
|||
|
of any more advanced display capabilities, such as ANSI or
|
|||
|
AVATAR. When ASCII mode is used, characters can only be
|
|||
|
displayed in standard Teletype (TTY) fashion, one after another.
|
|||
|
Also, color and cursor positioning functions are not available
|
|||
|
in ASCII mode. Compare ANSI and AVATAR.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 256
|
|||
|
|
|||
|
AVATAR AVATAR is an acronym for "Advanced Video Attribute Terminal
|
|||
|
Assembler and Recreator". AVATAR is a graphics display protocol,
|
|||
|
similar to ANSI. Like ANSI-graphics, AVATAR graphics allow
|
|||
|
functions such as cursor positioning, and color changing.
|
|||
|
However, AVATAR also offers many capabilities not available from
|
|||
|
ANSI, and performs the same functions as ANSI much more quickly.
|
|||
|
AVATAR graphics is less common than both ANSI or ASCII, but is
|
|||
|
becoming more popular as time goes by. Compare ASCII and ANSI.
|
|||
|
|
|||
|
|
|||
|
BAUD "baud" or "baud rate" are generally used as a synonym for "BPS".
|
|||
|
|
|||
|
|
|||
|
BPS BPS is an acronym for "Bits Per Second", and refers to the rate
|
|||
|
at which data is being sent over a communications medium. There
|
|||
|
are two important BPS rates which are relevant to OpenDoors. The
|
|||
|
serial port BPS rate (also called the DCE rate) is the speed at
|
|||
|
which the computer is communicating with the local modem. The
|
|||
|
connect speed, on the other hand, is the speed at which the
|
|||
|
local modem is communicating with the remote modem. The serial
|
|||
|
port speed must be at least as fast as the connection speed.
|
|||
|
Often the serial port speed will be locked at a fixed speed that
|
|||
|
is higher than the fastest possible connection speed of the
|
|||
|
modem. For example, the serial port might be locked at a speed
|
|||
|
of 38400 BPS, while the modem could be connected at 28,800,
|
|||
|
14,400 or slower speeds. OpenDoors usually needs to know the
|
|||
|
serial port BPS rate in order to function correctly (as stored
|
|||
|
in od_control.baud). Under certain situations, OpenDoors will
|
|||
|
also be able to report the connection speed to you (as stored in
|
|||
|
od_control.od_connect_speed), although OpenDoors does never
|
|||
|
requires this information to operate.
|
|||
|
|
|||
|
|
|||
|
BIT-MAPPED As with Boolean values, described below, bit mapped flags
|
|||
|
FLAGS are used to indicate whether or not various conditions exist.
|
|||
|
(For example, whether or not a certain setting is enabled, or
|
|||
|
whether or not a particular event has occurred.) However, unlike
|
|||
|
Boolean variables, a single bit-mapped flag represents more than
|
|||
|
one of these TRUE/FALSE values. In fact, each bit (BInary
|
|||
|
Digit), which makes of the variable can be used to represent a
|
|||
|
separate TRUE/FALSE state. (ie, each bit maps to a particular
|
|||
|
piece of information, and hence the term "Bit Map").
|
|||
|
|
|||
|
For an example of using bit-mapped flags, let us take a case of
|
|||
|
a single "unsigned char" which contains three independent
|
|||
|
TRUE/FALSE values. We will call this variable user_info, and it
|
|||
|
will indicate whether or not a user has ANSI graphics, whether
|
|||
|
or not the user has screen clearing turned on, and whether or
|
|||
|
not the user has end-of-page "more" prompts enabled. Internally,
|
|||
|
the bits of the user_info variable will be as follows:
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 257
|
|||
|
|
|||
|
Bit: 7 6 5 4 3 2 1 0
|
|||
|
| | |
|
|||
|
| | +--- ANSI Graphics
|
|||
|
| +----- Screen Clearing
|
|||
|
+------- More prompts
|
|||
|
|
|||
|
In this case, we will have three constants which we define in
|
|||
|
order to simplify access to these bit-mapped flags, as follows:
|
|||
|
|
|||
|
#define ANSI_GRAPHICS 0x01
|
|||
|
#define SCREEN_CLEARING 0x02
|
|||
|
#define MORE_PROMPTS 0x04
|
|||
|
|
|||
|
Note that normally within OpenDoors, these constants will be
|
|||
|
defined for you, and you will have no need to know what their
|
|||
|
values are, nor in which bit which piece of information is
|
|||
|
stored.
|
|||
|
|
|||
|
Using bit-mapped flags, you are able to set or clear any of the
|
|||
|
individual flags, and check whether any of the flags are set,
|
|||
|
using these simple methods: (Not that a set flag is the
|
|||
|
equivalent of a Boolean value of "True", and a cleared flag is
|
|||
|
the equivalent of a Boolean value of "False".)
|
|||
|
|
|||
|
Set Flag: variable |= FLAG_CONSTANT;
|
|||
|
Clear Flag: variable &=~ FLAG_CONSTANT;
|
|||
|
Test Flag: variable & FLAG_CONSTANT
|
|||
|
|
|||
|
Where "variable" is the name of the bit-mapped flag variable,
|
|||
|
and "FLAG_CONSTANT" is the pre-defined constant for the
|
|||
|
individual setting. To return to our example, you could turn on
|
|||
|
the user's ANSI graphics setting by using the line:
|
|||
|
|
|||
|
user_info |= ANSI_GRAPHICS;
|
|||
|
|
|||
|
and to turn off screen clearing you would:
|
|||
|
|
|||
|
user_info &=~ ANSI_GRAPHICS;
|
|||
|
|
|||
|
To perform an action (such as waiting for the user to press
|
|||
|
[Return]/[Enter]) only if "More" prompts are enabled, you would:
|
|||
|
|
|||
|
if(user_info & MORE_PROMPTS)
|
|||
|
{
|
|||
|
... /* Whatever you want */
|
|||
|
}
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 258
|
|||
|
|
|||
|
BOOLEAN Many of the variables used within OpenDoors contain a
|
|||
|
VALUES "Boolean Value". A Boolean value is a two-state variable, who's
|
|||
|
states are referred to as "True" and "False'. If the variable
|
|||
|
contains a value of "True", it indicates that a certain
|
|||
|
condition is so, and if it contains a value of "False", it
|
|||
|
indicates that the condition is not so. For example, a Boolean
|
|||
|
variable "wait" might be used to indicate whether or not
|
|||
|
OpenDoors should wait for the user to press a key, or continue
|
|||
|
without waiting. In this case, a value of "True" would indicate
|
|||
|
that OpenDoors should wait, and a value of "False" would
|
|||
|
indicate that it should not wait.
|
|||
|
|
|||
|
Note that in the C programming language, there is no actual
|
|||
|
Boolean variable type - usually a char or an int are used to
|
|||
|
store Boolean values.
|
|||
|
|
|||
|
The constants TRUE and FALSE, as defined in the OPENDOOR.H file,
|
|||
|
are used to represent the two states of a Boolean value. Thus,
|
|||
|
to set a Boolean variable "wait" to the value of "True", you
|
|||
|
would use this line:
|
|||
|
|
|||
|
wait=TRUE;
|
|||
|
|
|||
|
and to set the variable "wait" to "False", you would:
|
|||
|
|
|||
|
wait=FALSE;
|
|||
|
|
|||
|
However, you SHOULD NOT test whether a Boolean variable is
|
|||
|
"True" or "False" by using the C compare (==) operator, as the
|
|||
|
value "True" will not always be the same numerical value.
|
|||
|
(Actually, the TRUE constant represents just one of many
|
|||
|
possible numerical values for "True"). Instead, to perform an
|
|||
|
action of the "wait" Boolean variable is "True", you would:
|
|||
|
|
|||
|
if(wait)
|
|||
|
{
|
|||
|
... /* Whatever you want */
|
|||
|
}
|
|||
|
|
|||
|
and to perform an action if the "wait" Boolean variable is
|
|||
|
"False', you would:
|
|||
|
|
|||
|
if(!wait)
|
|||
|
{
|
|||
|
... /* Whatever you want */
|
|||
|
}
|
|||
|
|
|||
|
For interest sake, Boolean values are named after the 19th
|
|||
|
century English mathematician, who studied formal logic, and
|
|||
|
created Boolean algebra - an algebra which deals with TRUE and
|
|||
|
FALSE values.
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 259
|
|||
|
|
|||
|
|
|||
|
BPS BPS is an acronym for "Bits Per Second". For our purposes here,
|
|||
|
the terms BPS and BAUD refer to the same thing.
|
|||
|
|
|||
|
|
|||
|
CARRIER The term "Carrier" or "Carrier Detect" refers to a signal which
|
|||
|
DETECT most modems send to the computer, which indicates whether or not
|
|||
|
the modem is currently connected to (communicating with) another
|
|||
|
modem. The door driver module of OpenDoors, as with most other
|
|||
|
BBS software, uses the status of this carrier detect signal in
|
|||
|
order to know whether the user is still connected to the BBS
|
|||
|
computer. Thus, if the user hangs up, or if something goes wrong
|
|||
|
and the connection is lost, OpenDoors is able to detect this
|
|||
|
state, and exit to the BBS. The BBS will then also detect that
|
|||
|
the carrier signal has been "lost", and will reset itself, and
|
|||
|
then again be ready to accept calls.
|
|||
|
|
|||
|
|
|||
|
CHAT MODE The term "chat mode" refers to a means by which the sysop can
|
|||
|
communicate with a user of the BBS / door. During sysop chat,
|
|||
|
anything typed by the sysop will appear on the user's screen,
|
|||
|
and likewise, anything typed by the user will appear on the
|
|||
|
sysop's screen. Sysop chatting is available on both single and
|
|||
|
multi-line systems. Sysop chatting is initiated by the sysop,
|
|||
|
either at any time a user is online, or specifically in response
|
|||
|
to a sysop page.
|
|||
|
|
|||
|
|
|||
|
COMPILE "Compiling" refers to the process of converting the source code
|
|||
|
that you write for your program, into an executable file (such
|
|||
|
as a .EXE file) that an end user can use. The process of
|
|||
|
building an executable file is generally divided into two
|
|||
|
stages. In the first stage, called compiling, source files are
|
|||
|
converted to object files, often named .OBJ. In the second
|
|||
|
stage, called linking, one or more object files are combined,
|
|||
|
along with any library files, to produce the final executable
|
|||
|
file.
|
|||
|
|
|||
|
|
|||
|
DLL DLL is an acronym for "Dynamic Link Library". A dynamic link
|
|||
|
library is similar to a static library, in that it contains one
|
|||
|
or more functions that an application program can use. Unlike a
|
|||
|
static library, the code from a dynamic link library is not
|
|||
|
added to the program's executable file at link time. Instead,
|
|||
|
the dynamic link library exists as a separate file which must be
|
|||
|
loaded when the program is run. The Win32 version of OpenDoors
|
|||
|
resides in a DLL.
|
|||
|
|
|||
|
See also "Library".
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 260
|
|||
|
|
|||
|
DOOR A "door" is a program that runs as part of a BBS system, but
|
|||
|
which is separate from the central BBS software (RemoteAccess,
|
|||
|
Maximus, QuickBBS, PC-Board, etc.) itself. A door provides
|
|||
|
additional features not built into the BBS software, such as on-
|
|||
|
line games, on-line shopping services, voting booths, match
|
|||
|
making systems, access to special files or messages, and much
|
|||
|
much more. Since the user also communicates with the door
|
|||
|
online, as they do with the BBS, it may not necessarily be
|
|||
|
obvious to the user that the door is even a separate entity from
|
|||
|
the central BBS software itself.
|
|||
|
|
|||
|
|
|||
|
DOOR Also referred to as a "drop file", "exit file", or "chain
|
|||
|
INFORMATION file". The door information file is a file passed from the
|
|||
|
FILE central BBS software to a door program, providing it with
|
|||
|
information about the user who is online, the BBS the door is
|
|||
|
running under, and the current modem connection. The door
|
|||
|
information file may also be used to pass changed information
|
|||
|
back to the BBS, such as the amount of time that the user has
|
|||
|
used in the door. OpenDoors takes care of all of the work
|
|||
|
involved in reading and writing the door information file for
|
|||
|
you, as described in the "Basics of Door Programming" section,
|
|||
|
in chapter 4. Examples of door information files supported by
|
|||
|
OpenDoors include: DOOR.SYS, EXITINFO.BBS, DORINFO?.DAT,
|
|||
|
SFDOORS.DAT, CALLINFO.BBS and CHAIN.TXT.
|
|||
|
|
|||
|
DTR DTR is an acronym for "Data Terminal Ready". This is a signal
|
|||
|
that the computer sends to the modem, indicating that the
|
|||
|
computer is ready to send or receive information. Most modems
|
|||
|
are configured to hangup if the DTR signal is lowered. This is a
|
|||
|
convenient means of hanging up the modem, but cases problems
|
|||
|
under Windows 95, where the DTR signal is always lowered when a
|
|||
|
program closes the serial port.
|
|||
|
|
|||
|
|
|||
|
ECHO See "Local Echo".
|
|||
|
|
|||
|
|
|||
|
FOSSIL The FOSSIL driver, or simply FOSSIL, is a TSR program or
|
|||
|
DRIVER device driver which OpenDoors can optionally make use of in
|
|||
|
order to communicate with the modem. The FOSSIL driver is loaded
|
|||
|
prior to starting up the BBS or your door, usually from the
|
|||
|
AUTOEXEC.BAT or CONFIG.SYS files. The two most commonly used
|
|||
|
FOSSIL drivers are X00 and BNU. (FOSSIL is an acronym for
|
|||
|
"Fido/Opus/SEAdog Standard Interface Layer", although it has now
|
|||
|
become the standard for nearly all BBS software.) FOSSIL drivers
|
|||
|
are also available for other specialized serial port hardware,
|
|||
|
such as the popular "DigiBoard" multi-port serial card.
|
|||
|
|
|||
|
|
|||
|
IMPORT LIBRARY See "Library".
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 261
|
|||
|
|
|||
|
|
|||
|
LIBRARY A "library" or "library file" is a collection of precompiled
|
|||
|
functions and variables that can be used by other programs. All
|
|||
|
of the features, capabilities and functions of OpenDoors that
|
|||
|
you can make use of are contained within the OpenDoors library
|
|||
|
files. (Likewise, the C runtime library, consisting of the
|
|||
|
familiar functions such as fopen(), printf() and atoi(), is also
|
|||
|
contained within a library file.) For more information on the
|
|||
|
different OpenDoors library files, see the section that begins
|
|||
|
on page 22.
|
|||
|
|
|||
|
There are several different kinds of library files. A static
|
|||
|
library file is actually a collection of individual object
|
|||
|
files. When you compile a program that makes use of a static
|
|||
|
library file, only those portions of the library file that your
|
|||
|
program actually uses are linked into your program's executable
|
|||
|
(.EXE) file. Static library files can be identified by a .LIB
|
|||
|
extension. The DOS version of OpenDoors resides in a static
|
|||
|
library.
|
|||
|
|
|||
|
A dynamic link library, on the other hand, is not combined with
|
|||
|
the program's executable file. Instead dynamic link libraries
|
|||
|
exist in separate .DLL files that must also be present when the
|
|||
|
program is executed. The Win32 version of OpenDoors resides in a
|
|||
|
dynamic link library.
|
|||
|
|
|||
|
An import library is a small file that describes a dynamic link
|
|||
|
library. The most common way for a program to call functions in
|
|||
|
a dynamic link library requires that an import library be used a
|
|||
|
program link time.
|
|||
|
|
|||
|
See also "DLL".
|
|||
|
|
|||
|
|
|||
|
LINK "Linking" generally refers to the process of combining several
|
|||
|
object files into a final executable file, during which
|
|||
|
references to symbol names (such as od_printf()) are resolved to
|
|||
|
the address of the corresponding object. See also "Compiling".
|
|||
|
|
|||
|
|
|||
|
LOCAL MODE The term "local mode" refers to a mode in which a BBS system or
|
|||
|
door program may operate. In local mode, the BBS/door behave as
|
|||
|
they would if a user were connected via modem to the BBS, except
|
|||
|
that all display and input is done simply on the BBS software,
|
|||
|
but not through the modem. Local mode allows the sysop or
|
|||
|
another person with direct access to the BBS computer to use the
|
|||
|
BBS/door software, either for their own user, or for testing
|
|||
|
that the software is running correctly. When programming door
|
|||
|
software, local mode can be very useful in testing and debugging
|
|||
|
the door, without requiring the door to be connected to a remote
|
|||
|
system. All doors written with OpenDoors automatically support
|
|||
|
local mode operation. Compare "Remote".
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 262
|
|||
|
|
|||
|
|
|||
|
|
|||
|
LOCAL ECHO The term "Local Echo" refers to a door displaying the same
|
|||
|
characters which are sent to the modem on the local screen
|
|||
|
("Output Window"). This allows the sysop to view the same
|
|||
|
information that is sent to the user's system, in the same
|
|||
|
manner that it will appear on the user's screen.
|
|||
|
|
|||
|
|
|||
|
LOCKED (eg. "Locked Baud Rate", "Locked BPS Rate", "Locked Commport
|
|||
|
Speed", etc.) Usually, the communication port to which a modem
|
|||
|
is connected is set to transfer data at the same BPS rate as the
|
|||
|
rate at which the modem is communicating. However, many high
|
|||
|
speed modems allow very high speed data transfer by using built-
|
|||
|
in data compression methods. In this case, the actual rate of
|
|||
|
data transfer can easily exceed the true BPS rate of the
|
|||
|
connection. As a result, the BPS rate of the port is kept a
|
|||
|
single speed, faster than any of the true modem connections, in
|
|||
|
order to increase modem speed performance. This is referred to
|
|||
|
as locking the commport BPS rate. OpenDoors has full support for
|
|||
|
the use of locked BPS rates.
|
|||
|
|
|||
|
|
|||
|
LOG FILE A log file is a normal text file in which BBS software records
|
|||
|
all major activities that have taken place. As such, the log
|
|||
|
file permits the sysop, to review what activities have taken
|
|||
|
place on the BBS during the time which they have been away from
|
|||
|
the computer. A log file can be helpful in identifying system
|
|||
|
errors or crashes that have occurred, in alerting the sysop in
|
|||
|
the case that any users have been causing problems on the BBS,
|
|||
|
or in simply letting the sysop know who has called recently, and
|
|||
|
what when they did when they called.
|
|||
|
|
|||
|
|
|||
|
MEMORY MODEL C and C++ programs can be compiled under a variety of different
|
|||
|
memory models. Each memory model describes how data and program
|
|||
|
code are addressed in memory. When writing MS-DOS programs, you
|
|||
|
generally have the choice of six different memory models (named
|
|||
|
tiny, small, compact, medium, large and huge), each of which
|
|||
|
provides a different combination of the maximum sizes of data
|
|||
|
and code that your program may have. When writing Win32
|
|||
|
programs, there is a single, flat 32-bit memory model that all
|
|||
|
programs use. This memory model allows a program to address (in
|
|||
|
theory) up to 4 gigabytes of data and code.
|
|||
|
|
|||
|
|
|||
|
MODEM A device connected to a computer which permits it to communicate
|
|||
|
with other computers, usually over standard telephone lines.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 263
|
|||
|
|
|||
|
OBJECT FILE An object file contains the compiled version of a source code
|
|||
|
file of a program. The source code file may be a .C file, .CPP
|
|||
|
file, .ASM file, .PAS file, .BAS file, or any number of other
|
|||
|
extensions associated with other programming languages. When any
|
|||
|
of these language's source code files are compiled, a .OBJ file
|
|||
|
is created containing information such as the executable code,
|
|||
|
and names of symbols (variables and functions) that are to be
|
|||
|
shared with other .OBJ files. In order to produce a .EXE file
|
|||
|
that may be executed, a process known as linking must be
|
|||
|
performed. During the link process, one or more object files
|
|||
|
composing your program are combined, along with the necessary
|
|||
|
code from any library files being used, in order to produce the
|
|||
|
final .EXE file.
|
|||
|
|
|||
|
|
|||
|
ONLINE In the case of BBS software and BBS door programs, the term
|
|||
|
online refers to the state of a user using the BBS. Usually, the
|
|||
|
user will be connected to the BBS from a remote location, using
|
|||
|
a modem. However, it is also possible that the user will be
|
|||
|
using the actual BBS computer, with the software operating in
|
|||
|
"local mode".
|
|||
|
|
|||
|
|
|||
|
OUTPUT WINDOW The local screen of the BBS on which BBS software is running is
|
|||
|
usually divided into two sections. At the bottom of the screen,
|
|||
|
there is often a one or two line status line, which displays
|
|||
|
information to the sysop about the BBS and the user who is
|
|||
|
currently online. The rest of the screen is usually an "output
|
|||
|
window", in which the information which is being displayed to
|
|||
|
the user, is also displayed on the local screen. In some cases,
|
|||
|
there will be no status line, in which case the entire screen
|
|||
|
will be the output window. Usually, the upper 23 lines of the
|
|||
|
screen in an OpenDoors door will be the output window, with the
|
|||
|
bottom two lines being the status line. However, it is possible
|
|||
|
to disable the OpenDoors status line, in which case the entire
|
|||
|
screen will be the output window. See also "Status Line"
|
|||
|
|
|||
|
|
|||
|
PAGE See "SYSOP PAGE"
|
|||
|
|
|||
|
|
|||
|
PARAMETER In the C programming language, many tasks are accomplished by
|
|||
|
calling functions. When a function is called, one or more pieces
|
|||
|
of information may be passed to a function, in the form of
|
|||
|
parameters. For example, a function used to set the foreground
|
|||
|
and background color of displayed text might accept two
|
|||
|
parameters, one for each of the two color settings. In this
|
|||
|
example, a function such as od_set_color(), would be called as
|
|||
|
follows:
|
|||
|
|
|||
|
od_set_color(D_GREEN,D_RED);
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 264
|
|||
|
|
|||
|
In this case, D_GREEN, the foreground color, is the first
|
|||
|
parameter, and D_RED, the background color, is the second
|
|||
|
parameter.
|
|||
|
|
|||
|
In C, parameters are enclosed in parentheses, ( and ), which are
|
|||
|
located after the name of the function to be called. Each
|
|||
|
parameter is then separated by a comma character. If a function
|
|||
|
does not accept any parameters, the parentheses will have
|
|||
|
nothing between them. (ie. od_clr_scr() ).
|
|||
|
|
|||
|
|
|||
|
REGISTRATION This is a demonstration version of OpenDoors, which may only be
|
|||
|
used under limited circumstances, for a limited period of time.
|
|||
|
If you wish to continue using OpenDoors after this "evaluation
|
|||
|
period", you must "register" it. For more information on
|
|||
|
registering OpenDoors, please see chapter 2 of this manual.
|
|||
|
|
|||
|
|
|||
|
REMOTE When used in reference to BBS software or door programs, the
|
|||
|
term remote is used to refer to a user or computer that is
|
|||
|
communicating with the BBS, for a distant location, by use of a
|
|||
|
modem. Compare "Local Mode"
|
|||
|
|
|||
|
|
|||
|
RIP "RIP", "RIPScrip" or "Remote Imaging Protocol" is a popular
|
|||
|
graphical terminal standard that is used with BBS systems.
|
|||
|
Unlike other terminal emulation standards, such as the ANSI and
|
|||
|
AVATAR modes supported by OpenDoors, RIP operates in bit mapped
|
|||
|
graphics mode, allowing features such as lines, circles and
|
|||
|
icons to be drawn on the remote screen. OpenDoors provides
|
|||
|
support for RIP graphics, although OpenDoors operates in text
|
|||
|
mode itself.
|
|||
|
|
|||
|
|
|||
|
STATUS LINE Usually, the bottom two lines of the screen, as displayed by an
|
|||
|
OpenDoors door, is devoted to a status line (although this
|
|||
|
status line may be turned off). This status line will display
|
|||
|
information about the user who is online, along with information
|
|||
|
about the current state of the BBS system, and a reference to
|
|||
|
the sysop function keys. See also "Local Window".
|
|||
|
|
|||
|
|
|||
|
SYSOP The term sysop is a short-form for "SYStem OPerator", and refers
|
|||
|
to the individual who is responsible for running and maintaining
|
|||
|
the BBS system. The sysop is usually the only person who has
|
|||
|
direct access to the local keyboard and computer on which the
|
|||
|
BBS, BBS utilities and BBS doors are running.
|
|||
|
|
|||
|
|
|||
|
SYSOP CHAT See "CHAT MODE".
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 265
|
|||
|
|
|||
|
SOURCE CODE The term "source code" refers to the original file or files that
|
|||
|
where used to produce a library or executable program. The
|
|||
|
source code files contain the language statements or commands
|
|||
|
that are directly written by the programmer. These source code
|
|||
|
files are then compiled to produce an executable file that may
|
|||
|
be "run".
|
|||
|
|
|||
|
|
|||
|
SYSOP PAGE Sysop paging refers to the process whereby a user of the BBS
|
|||
|
system may call or page for the sysop's attention, when they
|
|||
|
wish to "chat" with the sysop, and can be thought of as being
|
|||
|
similar to the ringing of a telephone. When a user pages the
|
|||
|
sysop, the BBS system will produce some sort of sound, which the
|
|||
|
sysop may elect to respond to if they are within hearing range
|
|||
|
of the computer. The most common reasons for a user to page a
|
|||
|
sysop include the case that they are having difficulty with some
|
|||
|
aspect of the BBS, that they have a question, or if they are
|
|||
|
simply interested in having a friendly conversation with the
|
|||
|
sysop. Obviously, since the sysop may not wish to be disturbed
|
|||
|
by users paging at certain times (such as when they are in bed),
|
|||
|
most BBS software provides controls to allow you to control
|
|||
|
paging. These features might include the ability to set hours
|
|||
|
for each day of the week during which paging will be permitted,
|
|||
|
and the ability to temporarily override the ability of some or
|
|||
|
all callers to page the sysop.
|
|||
|
|
|||
|
|
|||
|
USER When applied to computers in general, the term user simply
|
|||
|
refers to any person using the computer hardware and software.
|
|||
|
However, when applied particularly to BBSes, the term user
|
|||
|
refers specifically to a person who calls the BBS, to carry out
|
|||
|
activities such as communicating via messages or chatting,
|
|||
|
uploading and downloading files, or using doors. Often, the term
|
|||
|
user is used in contrast with the term sysop. In this case,
|
|||
|
users are all of the people who call and user the BBS, other
|
|||
|
than the sysop themselves.
|
|||
|
|
|||
|
|
|||
|
WIN32 Win32 is the name of the API that programs written to run under
|
|||
|
Microsoft Windows 95 and Microsoft Windows NT use to access
|
|||
|
operating system services. Win32 programs use a flat, 32-bit
|
|||
|
memory model and have access to advanced operating system
|
|||
|
services such as multithreading. Win32 programs cannot run under
|
|||
|
DOS nor OS/2. While some Win32 programs can run under Windows
|
|||
|
3.x using the Win32s system, OpenDoors cannot since it requires
|
|||
|
multithreading services that are not provided by Win32s.
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 266
|
|||
|
|
|||
|
IIIIII
|
|||
|
II
|
|||
|
II
|
|||
|
II
|
|||
|
II
|
|||
|
II
|
|||
|
IIIIII
|
|||
|
-------------------------------------------------------------------------------
|
|||
|
INDEX
|
|||
|
|
|||
|
|
|||
|
|
|||
|
A D
|
|||
|
|
|||
|
About This Manual ..................21 Debugging 21, 241
|
|||
|
Access Level ......................178 Demo Version........................9
|
|||
|
Alias .............................170 Display Functions..............42, 63
|
|||
|
ANSI Graphics Displaying Text....30, 41, 42, 60, 62
|
|||
|
Archive Contents ..................248 Door Driver Functions..............40
|
|||
|
ASCII Chart ........................86 Door Driver Module..............6, 40
|
|||
|
ASCII Mode ........................255 Door Functions.....................45
|
|||
|
AVATAR Graphics ....118, 134, 167, 256 Door Information File30, 33, 150, 158
|
|||
|
Door Settings.....................182
|
|||
|
B DORINFOx.DEF File..................33
|
|||
|
DOS Shell.........................192
|
|||
|
Baud Rate .........................154 Download Limit....................169
|
|||
|
BBS Information ...................158
|
|||
|
BBS Name ..........................164 E
|
|||
|
BBS Systems ........................30
|
|||
|
Before Exit Function ..............191 Error Free Connection.............170
|
|||
|
Box Characters ...............185, 191 Example Program - Changing Only
|
|||
|
BPS Rate ..........................154 Foreground/Background Colour ....132
|
|||
|
Built-In Function Keys ............212 Example Program - Choosing Text
|
|||
|
Colour ..........................129
|
|||
|
C Example Program - Clearing A Line..56
|
|||
|
Example Program - Dialog Box.......66
|
|||
|
Caller Information ................158 Example Program - Door And Utility In
|
|||
|
Carrier Detect .................51, 97 One Program ......................92
|
|||
|
Chat ..........................38, 104 Example Program - Drawing A Window118
|
|||
|
Chat Mode ....................104, 259 Example Program - Exiting A Door...79
|
|||
|
Colour Attribute Codes ............128 Example Program - First Door.......29
|
|||
|
Colour Constants ..................132 Example Program - Hanging Up In CBV
|
|||
|
Colour Customization215, 229, 232, 236 Door .............................51
|
|||
|
Colour Functions ...................42 Example Program - Hotkeyed Menu....91
|
|||
|
Colours .................110, 128, 131 Example Program - Input Key.......115
|
|||
|
Common Problems ...................243 Example Program - Setting Door Info
|
|||
|
Compiler Errors ...................243 File Location ...................150
|
|||
|
Compiling With OpenDoors ...........22 Example Program - Shelling To DOS.141
|
|||
|
Custom Function Keys ..............213 Example Program - Terminal Emu.....62
|
|||
|
Example Program - Testing Available
|
|||
|
Door Information ................158
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 267
|
|||
|
|
|||
|
|
|||
|
|
|||
|
Example Program - Testing Screen M
|
|||
|
Clearing Capabilities 57
|
|||
|
Example Program - Transferring A File Memory Models..................23, 24
|
|||
|
Using DSZ........................142 Memory Swapping...................209
|
|||
|
Example Program - User Statistics Modem Port........................157
|
|||
|
Door.............................113 Modem Settings....................153
|
|||
|
Example Program - Vote .............33
|
|||
|
Example Program - Waiting For CR ...54 N
|
|||
|
Exiting A Door Program .............79
|
|||
|
New Version.......................249
|
|||
|
F Node Number.......................152
|
|||
|
|
|||
|
Features ............................6 O
|
|||
|
Feedback Form ......................19
|
|||
|
File Display Functions .............44 Object File.......................263
|
|||
|
FILES.BBS File .....................98 od_autodetect() Function...........48
|
|||
|
Fossil Driver .....................260 od_carrier() Function..............51
|
|||
|
FOSSIL port .......................157 od_chat() Function.................50
|
|||
|
Function Keys .................97, 211 od_clear_keybuffer() Function......53
|
|||
|
Future Versions ...................253 od_clr_line() Function.............55
|
|||
|
od_clr_scr() Function.........57, 243
|
|||
|
G od_colour_config() Function........59
|
|||
|
od_control Structure..........31, 148
|
|||
|
Getting In Touch With Us ..........246 od_disable Variable...............198
|
|||
|
Graphics Mode ...........165, 167, 255 od_disp() Function.................60
|
|||
|
od_disp_emu() Function.............62
|
|||
|
H od_disp_str() Function.............63
|
|||
|
od_draw_box() Function.............65
|
|||
|
History ...........................249 od_edit_str() Function.............68
|
|||
|
Hotkeys ............................90 od_exit() Function...31, 79, 191, 195
|
|||
|
od_get_answer() Function...........81
|
|||
|
I od_get_input() Function............82
|
|||
|
od_get_key() Function......30, 53, 85
|
|||
|
IBM Colour Attribute Codes ........128 od_gettext() Function..............89
|
|||
|
IEMSI Session Information .........161 od_hotkey_menu() Function..........90
|
|||
|
Inactivity Timeout ......199, 200, 202 od_init() Function.............31, 92
|
|||
|
Input Functions ............44, 81, 85 od_input_str() Function........53, 95
|
|||
|
od_kernal() Function...............31
|
|||
|
K od_kernel() Function...............97
|
|||
|
od_list_files() Function...........98
|
|||
|
Keyboard Buffer ...........53, 97, 115 od_log_write() Function...........100
|
|||
|
Keys ...............................97 od_multiline_edit() Function......101
|
|||
|
od_page() Function...........104, 207
|
|||
|
L od_parse_cmd_line() Function......105
|
|||
|
od_popup_menu() Function..........107
|
|||
|
Language Customization ............216 od_printf() Function.....29, 110, 195
|
|||
|
Learning OpenDoors .................29 od_putch() Function...............115
|
|||
|
Library ...........................261 od_puttext() Function.............116
|
|||
|
LIBrary Files ......................24 od_repeat() Function..............118
|
|||
|
Line Number .......................152 od_restore_screen() Function......120
|
|||
|
Linking ............................23 od_save_screen() Function.........121
|
|||
|
Local Mode ...............33, 200, 261 od_scroll() Function..............123
|
|||
|
Locked ............................262 od_send_file() Function...........124
|
|||
|
od_set_attrib() Function..........128
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 268
|
|||
|
|
|||
|
|
|||
|
|
|||
|
od_set_color() Function ...........131 Solutions To Problems.............243
|
|||
|
od_set_cursor() Function ..........134 Source Code................10, 17, 20
|
|||
|
od_set_dtr() Function .............135 Special Thanks....................254
|
|||
|
od_set_personality() Function .....136 Status Line...104, 137, 209, 210, 264
|
|||
|
od_set_statusline() Function ......137 Stop Key..........................203
|
|||
|
od_sleep() Function ...............139 Support...........................244
|
|||
|
od_spawn Function .................208 Support BBS.............244, 245, 246
|
|||
|
od_spawn() Function ...............141 Swapping..........................209
|
|||
|
od_spawnvpe() Function ............143 Sysop Chat...............38, 104, 192
|
|||
|
od_window_create() Function .......145 Sysop Function Keys...............211
|
|||
|
od_window_remove() Function ..147, 148 Sysop Keys.........................97
|
|||
|
OPENDOOR.H File ............22, 29, 34 Sysop Name........................164
|
|||
|
OpenDoors BBS ................244, 245 Sysop Next Setting................184
|
|||
|
OpenDoors Customization ...........187 Sysop Page........................207
|
|||
|
OPENDOORS Echo ....................245 Sysop Paging.................104, 265
|
|||
|
OpenDoors History .................249 System Event......................162
|
|||
|
Our Address .......................246 System Name.......................164
|
|||
|
Output Functions ...................42
|
|||
|
Output Window .................34, 263 T
|
|||
|
|
|||
|
P Terminal Emulator........62, 124, 125
|
|||
|
Terminal Emulator Control Codes...126
|
|||
|
Paging Hours .................182, 183 Text Customization................216
|
|||
|
Paging The Sysop ..................104 Thank-yous........................254
|
|||
|
Pause Key .........................203 Time Left.........................179
|
|||
|
Phone Number ......................171 Timeout............................97
|
|||
|
Printing ..30, 41, 60-63, 90, 110, 115 Troubleshooting....................21
|
|||
|
Printing Manual ....................22
|
|||
|
Problems ...........................21 U
|
|||
|
Product Support ...................244
|
|||
|
Project Files ......................23 User Handle (Alias)...............170
|
|||
|
User Information..................158
|
|||
|
R User Keyboard Off Key..............53
|
|||
|
User Keyboard Setting.............184
|
|||
|
Registration ..9, 10, 12, 18, 246, 264 User Name.........................174
|
|||
|
Registration Form ..............15, 18 User Password.....................176
|
|||
|
RIP ...............................264 User Timeout.......................97
|
|||
|
RIPScrip ..........................264
|
|||
|
V
|
|||
|
S
|
|||
|
Version History...................249
|
|||
|
Screen Functions ...................42
|
|||
|
Screen Length .....................177 W
|
|||
|
Screen Width ......................178
|
|||
|
Security Level ....................178 Want-Chat Setting.................180
|
|||
|
Setting Colours .........110, 128, 131
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
===============================================================================
|
|||
|
OpenDoors 6.00 Manual End of Page 269
|
|||
|
|