Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / dos / communic / odoors34 / opendoor.doc < prev next >

Wrap

Text File | 1992-05-07 | 349.8 KB | 6,197 lines

┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 1 │ └─────────────────────────────────────────────────────────────────────────────┘ ╔════════════════════════════════════════════════════╗ ║ ┌─────┐ ║ ║ │ │┌────┐┌───┐┌──┐ ║ ║ │ ││ │├───┘│ │ ║ ║ └─────┘├────┘└─── │ ├────┐ ║ ║ │ │ │┌───┐┌───┐┌─── ┌── ║ ║ │ ││ ││ ││ └──┐ ║ ║ └────┘└───┘└───┘│ ──┘ ║ ║ ──────────── ║ ║ Version 3.40 ║ ╚════════════════════════════════════════════════════╝ (C) Copyright 1992, Brian Pirie. All Rights Reserved. NOTE: Since this manual is likely something that you will want to refer to at the same time you're actually working with OpenDoors, looking at the sample source code, or writing your own doors, it is highly recommended that you take a moment to print it out. Simply type COPY OPENDOOR.DOC PRN from your DOS prompt! If Your printer does not support the extended ascii characters used in this document, simply type CONVERT command, followed by COPY OPENDOOR.TXT PRN. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 2 │ └─────────────────────────────────────────────────────────────────────────────┘ TABLE OF CONTENTS 1.) Table of Contents ......................................... 2 2.) Introduction to OpenDoors ................................. 5 i.) Door-Driver Portion ............................. 5 ii.) System File Engine .............................. 8 3.) Demo Version and Ordering Information ..................... 9 i.) About the Demo Version .......................... 9 ii.) Ordering Information ........................... 10 iii.) Order Form ..................................... 11 4.) About the Manual ......................................... 14 5.) Compiling Programs with OpenDoors ........................ 15 6.) Door Programming With OpenDoors .......................... 16 i.) Basics Of Door Programming ..................... 16 ii.) RAVote Demo Door ............................... 18 DORINFO1.DEF File Format .................... 18 Door Function Keys .......................... 19 iii.) "Door-Driver" related functions ................ 22 od_clear_keybuffer() ........................ 22 od_clr_line() ............................... 23 od_clr_scr() ................................ 24 od_disp() ................................... 25 od_disp_str() ............................... 26 od_emulate() ................................ 27 od_exit() ................................... 28 od_get_key() ................................ 29 od_init() ................................... 30 od_input_str() .............................. 31 od_kernal() ................................. 32 od_list_files() ............................. 33 od_page() ................................... 34 od_printf() ................................. 35 od_repeat() ................................. 36 od_send_file() .............................. 37 od_set_attrib() ............................. 40 od_set_cursor() ............................. 41 iv.) OpenDoors Control Structure .................... 42 BBS door information files table ............ 43 Control Structure Variables table ........... 44 7.) Accessing BBS system and configuration files ............. 56 i.) Main Configuration file(s) ..................... 57 Configruation structure ..................... 58 od_read_config() ............................ 68 od_write_config() ........................... 68 ii.) File Areas Configuration ....................... 69 File Areas structure ........................ 70 od_read_files() ............................. 71 od_write_files() ............................ 71 ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 3 │ └─────────────────────────────────────────────────────────────────────────────┘ iii.) Message Areas Configuration .................... 72 File Areas structure ........................ 73 od_read_msgs() .............................. 76 od_write_msgs() ............................. 76 iv.) System Events Configuration .................... 77 Events file structure ....................... 77 od_read_events() ............................ 79 od_write_events() ........................... 79 v.) External Protocols Configuration ............... 80 External Protocols structure ................ 80 od_read_protocols() ......................... 82 od_write_protocols() ........................ 82 vi.) Accessing the Node Activity File ............... 83 Node activity structure ..................... 83 od_useron_open() ............................ 85 od_useron_read() ............................ 86 od_useron_write() ........................... 87 od_useron_close() ........................... 88 vii.) Accessing the BBS Call history ................. 89 Call History structure ...................... 89 od_calls_open() ............................. 91 od_calls_read_next() ........................ 92 od_calls_add() .............................. 93 od_calls_close() ............................ 94 viii.) BBS Timelog .................................... 95 The Timelog structure ....................... 95 od_read_timelog() ........................... 96 ix.) Accessing BBS menu files ....................... 97 The Menu File structure ..................... 98 od_read_menu() .............................. 99 od_write_menu() ............................. 99 8.) Accessing BBS user base file(s) ......................... 100 i.) The user record ............................... 100 ii.) od_open_users() ............................... 104 iii.) od_read_user() ................................ 105 iv.) od_write_user() ............................... 106 v.) od_add_user() ................................. 107 vi.) od_close_users() .............................. 108 ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 4 │ └─────────────────────────────────────────────────────────────────────────────┘ 9.) Using the Message Base Manipulation Routines ............ 109 i.) The message base information structure ........ 110 ii.) The message header structure .................. 110 iii.) od_msg_open() ................................. 114 iv.) od_msg_post() ................................. 115 v.) od_msg_read_hdr() ............................. 117 vi.) od_msg_read_text() ............................ 118 vii.) od_msg_change_hdr() ........................... 119 viii.) od_msg_close() ................................ 120 10.) Troubleshooting Common Problems ......................... 121 i.) Steps to solving any OpenDoors Problem ........ 121 ii.) Using the od_errno variable ................... 122 iii.) Handy troubleshooting chart ................... 123 11.) OpenDoors History ....................................... 125 12.) Closing words and information on future versions ........ 130 ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 5 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ INTRODUCTION TO OPENDOORS ─┐ └─────────────────────────────┘ Welcome to OpenDoors, a powerful new product that allows Turbo C programmers to easily write utilities and doors for Bulletin Board Systems. There are two distinct, though closely integrated portions to OpenDoors. The "door driver" section provides a complete system to allow you to EASILY and QUICKLY write very high-quality BBS doors that will run on all popular BBS systems. The second portion of OpenDoors provides you with a complete set of functions for easily accessing and manipulating Apex and RemoteAccess system files such as configuration, system information files, and even a complete set of routines for accessing the message base. You can easily write programs that take advantage of one, the other, or both portions of OpenDoors. Here is a quick overview of both parts of the OpenDoors package, that will give you a good idea of what you can accomplish when using OpenDoors: ─────────────────────── THE DOOR DRIVER PORTION ─────────────────────── OpenDoors supplies you with a complete "door driver" library that allows you to write doors that DIRECTLY support one of the largest variety of BBS systems, including Apex, RemoteAccess, QuickBBS, PC-Board, Maximus, Opus, WildCat, WWIV, Spitfire, SuperBBS, RBBS-PC, TriTel and GAP. Interested in writing your own utility doors? Perhaps on-line games? Would you you even like to get into the market of selling your doors for others to use? Or do you just want to make your own BBS unique by running "custom" doors? Well, now you can, easier than ever before! Unlike other such "door drivers", OpenDoors provides all of the following features: ■ OpenDoors handles all the "dirty" work involved in writing door programs. Interested in writing doors for BBSes, either your own, or to distribute (even sell!) to other people? OpenDoors will allow you to easily create door programs in the same manner as you would any other program, by calling it's simple functions to input, output and control door operation. ■ As you would expect, OpenDoors flawlessly monitors carrier detect functions, to automatically recover when a user drops carrier - without you 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 Programmer's Manual ────────────────────────────────────── Page 6 │ └─────────────────────────────────────────────────────────────────────────────┘ ■ OpenDoors takes care of all the work involved in reading and writing BBS door caller information files, such as DORINFO1.DEF files, for full communication with the BBS under which the door is running. If extended 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. ■ OpenDoors also does all the work involved in displaying and automatically updating the RemoteAccess style status line, with information available to the sysop such as user name, location, baud rate, time left, function keys, ANSI and AVATAR settings, and so on. OpenDoors even keeps track of a user "wants-chat" indicator, just like the one in Apex, RemoteAccess, QuickBBS and other BBS systems. ■ 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, the door driver has full support for sysop shell to dos, activated by the Alt-J key. ■ OpenDoors has full support for locked baud-rates of up to 38,000 baud, using the FOSSIL driver for maximum compatibility with any system. To output text in your door, you simply call one print function. This function looks after all communication with the modem, and also echos the output to the local screen (referred to as twining the output). OpenDoors also automatically detects if the user is on in local mode, and will function as expected. ■ Other OpenDoors functions include a built in sysop-page function that will ask the user why he wishes 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 control functions (which again detect if the user has ANSI mode turned on). ■ And as if that weren't enough OpenDoors is now DesqView aware. When OpenDoors starts up, it will automatically check for the presence of DesqView, and if available, will perform all of it's screen output through DesqView. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 7 │ └─────────────────────────────────────────────────────────────────────────────┘ ■ What's more, OpenDoors is designed to be very easy to use. Even the most novice `C' programmers have been 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 fully control and customize every detail of your door's performance. ■ OpenDoors also comes with the source code for a user-voting door, RAVOTE, that you can modify, or simply use bits and pieces from for your own doors. ■ You may also elect to purchase the source code for OpenDoors, which will permit you to make modifications to any portion of OpenDoors, or to use any poritions of the OpenDoors source code in other programs you write. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 8 │ └─────────────────────────────────────────────────────────────────────────────┘ ────────────────────── THE SYSTEM FILE ENGINE ────────────────────── This second portion of the OpenDoors gives you complete access to BBS system, user and configuration files, along with a complete set of routines for manipulating the message base. Below some of the key features of this section of the OpenDoors package are listed for you. Keep in mind that all these features are VERY EASY to use (even though they may sound rather complicated)! ■ Automatic detection and conversion from various BBS system file formats. Although the current version of OpenDoors only supports Apex and RemoteAccess compatible system files, and the Hudson format message base, future versions will automatically detect and support many other BBS file formats as well. For example, you will be able to use the same "read user record" function for Apex/RemoteAccess/QBBS style and PC-Board style user files. ■ OpenDoors will automatically convert the system and configuration variables to and from C format for you. Thus, even though the configuration file may store filenames in Pascal format strings - they will be converted to C format for your use. ■ This portion of OpenDoors can be used to access all of the main configuration, file area and message area configuration files. It also gives you full access to the user base, along with other key system files. ■ The Hudson message base routines (which will TRANSPARENTLY support other message base formats in future versions) include functions for posting new messages, deleting existing messages, reading message text and reading message headers. (Message headers include information such as the subject of the message, who it is addressed to, and the like). The message base routines will optionally support the RA 1.01 Hudson Message Base Locking scheme. This locking method, which is already supported by many programs such as Apex, RemoteAccess, FrontDoor, Imail, allows for fast and efficent access to the message base by multiple programs concurrently. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ────────────────────────────────────── Page 9 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ ABOUT THIS DEMO VERSION & HOW TO ORDER ─┐ └──────────────────────────────────────────┘ What you have here is the demo version of OpenDoors. This version has all the features of the registered version, but can only be used under limited circumstances: 1.) The demo (unregistered) version may only be used for a reasonable evaluation period. 2.) programs written in this version may not be distributed. Also, any programs written in the demo version will display a message to the user indicating that they are not registered. This is, of course, removed in the registered version. If you decided to purchase OpenDoors, you will become the owner of a powerful tool for creating many BBS door and utility programs. Registered owners of OpenDoors are entitled to: 1.) Unlimited use of OpenDoors. You may write as many programs as you wish using OpenDoors, and do what you please with the programs. They may be freely distributed, or even sold. And what's more, there are no additional royalty fees. Your one time purchase of OpenDoors entitles you to use it (almost) as you please. 2.) You will be entitled to free upgrades to newer versions of OpenDoors. If you think this version of OpenDoors is great, wait for the next version! We are, as you read this, working on adding a large number of new features. (See the end of this document for an outline of features currently "in the works") Any programs you write in this version will automatically take on these new features when you get the new version as well. The best news of all is how cheap OpenDoors is! Other "door-drivers" sell for $50, $75, or even more! But the door-driver features are only a small portion of what OpenDoors can do for you! However, this version of OpenDoors will only cost you $28! (I can also guarantee that the price will go up in later versions, so if you order today, you'll save by getting ALL future upgrades for free.) ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 10 │ └─────────────────────────────────────────────────────────────────────────────┘ Also, the source code for OpenDoors is now available to registered users for an additional $28! 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 opprotunity to see how OpenDoors works, and to use any portions of the OpenDoors code in any other programs you wish to write. You may order OpenDoors by any of the following manners: 1.) RECEIVING YOUR REGISTRATION KEY / SOURCE CODE BY MAIL: ■ Fill out the order form and mail it along with your payment as described below ■ Enclose a self-addressed, stamped envelop, to receive your registration key. 2.) RECEIVING YOUR REGISTRATION / SOURCE CODE BY BBS MESSAGE: ■ Fill out the order form and mail it along with your payment as described below ■ Include phone #, baud rate, and my login and password for the BBS to which you wish me to leave a message containing your registration key. I will cover any long distance costs. 3.) RECEIVING YOUR REGISTRATION KEY / SOURCE CODE BY FIDONET CRASHMAIL: ■ Fill out the order form and mail it along with your payment as described below ■ Include the FidoNet node address to which you wish me to send your registration key to. (via CrashMail) Again I will cover any long distance costs. ■ Be sure that your system is configured to allow calls from UNLISTED POINTS. ------------------------------------------------------------------------------- OPENDOORS 3.40 Order Form: (If you do not have a printer, send a hand-drawn version of this order form.) ------------------------------------------------------------------------------- Your Full Name: _____________________ Your Address: ______________________________ Your City & State/Province: ______________________________ Your Postal Zip Code & Country: ____________________________________ Your Voice Phone Number: (____) ____ - ________ Your Data Phone Number (if any): (____) ____ - ________ Your FidoNet Address (if any): ________________________ I would like to receive my registration key and/or source code by: ___ | | - Conventional mail, I have enclosed a self addressed |___| stamped envolope. (Also include diskette if you are ordering the source code). ___ | | - Message on my BBS: |___| Name of BBS: ______________________ Phone number of BBS: (____) ____ - _______ Brian Pirie's logon: ______________________ Brian Pirie's password: ___________________ Best time to call: ___________________ ___ | | - FidoNet Crashmail to (node address): _____________ |___| Continued on next page... ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Where did you get your copy of OpenDoors? ____________________________________________________________ Which compiler and version are you using? (eg. Turbo C++ 1.00) ____________________________________________________________ What do you like most about OpenDoors? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ What would you like to see in future versions of OpenDoors? ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ ____________________________________________________________ I WOULD LIKE TO ORDER: ___ ^^^^^^^^^^^^^^^^^^^^^ | | - Just my registration key, for $28 |___| ___ | | - Just the source code (ONLY IF ALREADY |___| REGISTERED), for $28 ___ | | - Both registration key and source code, |___| for $56 * I have enclosed a cheque or money order ($28 for the registration, or $56 for both registration and source code) in Canadian or U.S. currency, payable to Brian Pirie. ____________________________ Signature ------------------------------------------------------------------------------- ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 13 │ └─────────────────────────────────────────────────────────────────────────────┘ After you have filled out this order form, enclose your cheque or money order in Canadian or U.S. currency, PAYABLE TO BRIAN PIRIE, and mail it (along with your self stamped, self-addressed envolope & diskette, if you wish to receive your copy by conventional mail), to: Brian Pirie Apt. 1416 - 2201 Riverside Dr. Ottawa, Ontario Canada K1H 8K9 If you have any questions, comments, or suggestions about OpenDoors, please feel more than free to contact me by FidoNet NetMail to 1:243/1.8 ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 14 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ ABOUT THIS MANUAL ─┐ └─────────────────────┘ Just as OpenDoors is divided into two main portions, the "door-driver" and the utility file manipulation functions, this manual also deals with these two seperate (though closely integrated) sections one at a time. First, the manual deals with the "door-driver" portion of OpenDoors, instructing you in the methods of door programming with OpenDoors. Following this portion of the manual is the reference section for the "door-driver" portion of OpenDoors, documenting the door related functions, and the "OpenDoors Control Structure". The manual then deals with the various system file portions (such as configuration, user base and message base toolkits) one at a time, first describing the use of each portion, and then providing references for the data and functions related to this portion. At the end of the manual, you will find several usefull appendicies, such as a trouble-shooting guide, a brief history of OpenDoors, and information about new OpenDoors features currently in the works. For a general overview of OpenDoors' features, see pages 4-7 of the manual, and for registration information, see pages 8-12. To locate other items in this manual, simply refer to the table of contents on pages 2 and 3. It is suggested that if you wish to get the most out of OpenDoors, that you carefully read the sections of the manual that describe the use of the features you are using, and at least skim other portions of the manual to find out what additional features are available. Also, you will likely want to print this manual, to make reading and reference while programming easier. To print this manual, simply set your printer to a mode that supports IBM-graphics characters, and type the following line from your DOS prompt: COPY OPENDOOR.DOC PRN: ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 15 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ COMPILING A PROGRAM WITH OPENDOORS ─┐ └──────────────────────────────────────┘ The process for compiling programs written with OpenDoors is very similar to the process for compiling any other program. However, there are two additional steps you must remember: to include the opendoor.h header file, and to link your program with the appropriate OpenDoors library. All programs written in OpenDoors, must "include" the opendoor.h header file. This is easily accomplished by placing the line #include "opendoor.h" at the beginning of your Turbo C program. You must also link the opendoor library file into your program. This can be accomplished by specifically including the appropriate library in your project file. If you are unfamiliar with the process of using project files, please refer to your Turbo C manuals. The library files included with this version of OpenDoors are listed in the following chart. Please be sure to use the library file that corrosponds to the memory model you are using. (Refer to your Turbo C manuals for more information on memory models) ┌─────────────┬──────────────────────────────────┐ │ Library │ Memory │ │ Filename │ Model │ ├─────────────┼──────────────────────────────────┤ │ ODOORT.LIB │ The Tiny memory model library │ │ │ │ │ ODOORS.LIB │ The Small memory model library │ │ │ │ │ ODOORM.LIB │ The Medium memory model library │ │ │ │ │ ODOORC.LIB │ The Compact memory model library │ │ │ │ │ ODOORL.LIB │ The Large memory model library │ │ │ │ │ ODOORH.LIB │ The Huge memory model library │ └─────────────┴──────────────────────────────────┘ For more information on including thrid-party libraries in your programs, please also see your Turbo C manuals. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 16 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ BASICS OF DOOR PROGRAMMING WITH OPENDOORS ─┐ └─────────────────────────────────────────────┘ While OpenDoors allows you to write door programs in almost the same manner as you would any normal program, there are a few things you should keep in mind, when writing a door program in OpenDoors. This section will give you an overview of how OpenDoors does it's thing, and what you should know to get things to work correctly. When a Door starts up, one of the first things it must do is to read the control files 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 Apex, RemoteAccess, Maximus, or what have you), will create a file of information about the system, who is on-line, and so on. Several different BBS packages produce their own style of file. OpenDoors currently recognizes many door information files, and future versions will recognize others. Thus, your Door will be able to run on any system such as Apex and RemoteAccess that outputs both of these files, any system such as RBBS-PC, which just outputs the DORINFO1.DEF, as well as any system such as PC-Board, if a conversion program is used. The Door itself will actually be loaded in one of two manners. Either the BBS will perform a "shell" and run the Door while the BBS system resides in memory (often called a type 7 exit), or will exit to a batch file, which will trap an errorlevel and load the appropriate door. (often called a type 15 exit). In either case, when the door gains control, it will first read these files, and then begin to communicate with the modem. OpenDoors, as with almost all other door systems, does all it's modem communication with the fossil driver. The fossil driver is loaded either as a .SYS device driver from Config.Sys at boot-up, or from an .EXE file as a TSR program, and provides the BBS software with a standard interface layer for communicating with just about any type of modem. Hence, whenever your door is not running in local mode, it will require a fossil driver, such as X00 or BNU to be loaded. In order to read these door information files into it's internal storage structures, to initialize communications with the fossil driver, to setup the status line, etc., OpenDoors provides a function, 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. However, there are times when you will want to know information about the user who is on-line, or what-have-you, before 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 Programmer's Manual ───────────────────────────────────── Page 17 │ └─────────────────────────────────────────────────────────────────────────────┘ OpenDoors will provide you with a structure, by the name of od_control, which allows you to access all the information about the user who is on-line, the system your door is running on, and to allow 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 of this manual entitled "The OpenDoors Control Structure". Once the door has initialized itself, it will then begin communications with the user who is online. OpenDoors takes care of all this communications, with it's various input and display functions. When the Door has finished, it will then write any information that has changed back into the door information file (if applicatble), finish communicating with the modem, and return to the BBS. In OpenDoors, this is accomplished with the od_exit() function. This function will terminate the doors 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. You *MUST* exit your door by calling the od_exit() function. Exiting without doing this will cause strange results, and your door will not function correctly. Thus, the one of the most simple door programs written in OpenDoors could look as follows: #include "opendoors.h" main() { od_disp_str("Welcome to my first Door!\n\r"); od_disp_str("Press any key to return to the BBS!\n\r"); od_get_key(TRUE); od_exit(10,FALSE); } Again, notice the inclusion of the opendoors.h file. All doors written with OpenDoors must include the OPENDOORS header file in order to compile correctly. The first two lines in the main function simply call the OpenDoors display string function (which sends the output to both the modem and the local screen). The next line is the OpenDoors single-key input function. The TRUE value causes the system to wait for a keypress (again, either from remote or local keyboard). The last line of the main function then ends the door, returning an errorlevel of 10. The FALSE indicates that you do not wish to have OpenDoors terminate the call (hang up on the user). If you placed a TRUE in its place, then a remote user would be logged off when the door exits. Try compiling this program as described in the section "COMPILING A PROGRAM WITH OPENDOORS", then try running it from your BBS. Congratulations, you have written your first door! ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 18 │ └─────────────────────────────────────────────────────────────────────────────┘ For more information on the functions available from OpenDoors, or the control structure, see the corresponding sections in this manual. It would also be a very good idea if you had a look at the sample door included with OpenDoors, RAVote. ┌─ THE SAMPLE DOOR: RAVOTE ─┐ └───────────────────────────┘ One of the best ways to really see how OpenDoors works, and how much potential it has, is to look at the source code for the sample door included, RAVote. While this is by no means a complex door, it should certainly give you a good idea of how things work with OpenDoors, and will likely give you many ideas for your own doors. You can run the door as included in the archive by typing RAVOTE (the archive also contains a sample DORINFO1.DEF file, which will allow you to test any doors in local mode.) If you wish to manually create your own DORINFO1.DEF file, you can do so very easily. This is a simple text file with 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 │ PETEBOROUGH, ON │ │ 10 │ ANSI mode (0=off, 1=on)│ 1 │ │ 11 │ User's security level │ 32000 │ │ 12 │ User's time left │ 60 │ └──────────────┴────────────────────────┴───────────────────┘ Also, feel free to make any changes you wish to the door, and recompile it! One of the best and most 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. Contrary to its name, it will run with any BBS system, not just RemoteAccess. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 19 │ └─────────────────────────────────────────────────────────────────────────────┘ The RAVote door behaves similarly to most other door programs, and will have a fair bit in common with any other door you write in OpenDoors. What you see in the output window is identical to what the user on remote will be seeing. If the user has ANSI mode turned on, you will see the same colours as they do, and if they have screen clearing turned on, your screen will clear when their's does. The status line at the bottom of the screen will list the name of the user currently on-line (if you're 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). You will also be told how much time the user has left, and there will be indicators as to whether the user has ANSI mode on, etc. If the user wishes to Chat with the sysop (ie, they have paged the sysop, but haven't had a response yet), a [Want-Chat] indicator will be flashing on the status line. Try Paging the sysop, using OpenDoors built in sysop page feature! The following function keys will also be available to the sysop only in any OpenDoors door: []/[] - Use the arrow keys to increase or decrease how much time the user has left in the door. [Alt]-[C] - Allows the sysop to break into chat with the user at any time. [Alt]-[C] again, or [ESC] will end chat mode. (notice that the Want-Chat indicator will be turned off if it was flashing too. If your door is running under Apex, RemoteAccess or QuickBBS, paging from within the door will even cause the Want-Chat indicator to stay lit when the user returns to the BBS) [Alt]-[J] - Allows the sysop to shell to DOS, if enough memory is available. Simply type EXIT to return to the door again. [Alt]-[H] - Hangup on the user. When the sysop does this, OpenDoors will optionally call a function you have indicated in the OpenDoors control structure, to allow you to close files, etc. OpenDoors will then exit to a batch file with the appropriate errorlevel: 0 - A critical error has occurred 1 - Carrier lost, user off-line 2 - Sysop terminated call, user off-line 3 - User time used up, user STILL ON-LINE 4 - Keyboard inactivity timeout, user off-line 5-255 - Defined by your door These errorlevel will allow users of your door to optionally log the user back on-line, place the BBS in "wait for call" mode, or whatever they wish, depending on how the door exited ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 20 │ └─────────────────────────────────────────────────────────────────────────────┘ [Alt]-[L] - This nasty key locks the user out of the BBS. It first hangs up on the user, and then sets their security level to 0, to prevent them from ever logging on again. This feature may require use of the EXITINFO.BBS file, depending on what system the door is running under. [Alt]-[K] - The "User Keyboard-Off" key, will allow the sysop to temporarily prevent the user from typing anything on his keyboard. This has no effect on the local keyboard, but causes OpenDoors to ignore any keystrokes from remote. [Alt]-[N] - The "Sysop Next" key, this function reserves the system for use by the sysop after the user logs off, if the door is running under an Apex or RA 1.00 or later system. [Alt]-[D] - "Drop to BBS" key. This function allows the sysop to exit the door and return the user to the BBS, without hanging up. Now, let's take a closer look at the actual source code for the RAVote door. If you haven't already printed out a copy of this manual, and possibly the RAVOTE.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. If you are placing the OPENDOOR.H in your include directory, along with the rest of your header files, use the line: #include <opendoor.h> You may notice the file structure just before the main function in the RAVote door. RAVote stores it's data file of questions, results, and who has voted on what in a single fixed length file called RAVOTE.BBS. This file is simply a direct image of the file structure. The elements in this structure includes the total number of questions, the total number of users that the door knows about, the questions they have and have not voted on, the actual questions and answers themselves, and so on. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 21 │ └─────────────────────────────────────────────────────────────────────────────┘ Next, the RAVote door checks for any command line parameters. If there are any, the first one is taken as the path to the DORINFO1.DEF and EXITINFO.BBS files. If no command line parameter is specified, then RAVote will not change the value of the od_control.info_path variable, which will cause OpenDoors to look for these files in the current directory. This is a good feature to implement in your doors, either by accepting command line parameters, or in a configuration file, as it will allow people to run your door from its own directory. Next, the RAVote program calls the od_disp_str() function to display its name, etc. to the screen. At this time, the OpenDoors subsystem will also initialize itself, setting up several internal structures, reading the user information files (DORINFO1.DEF & EXITINFO.BBS), and will begin communicating with the modem (if it is not running in local mode). The next line in the main() function of the RAVote door looks as follows: od_control.od_before_exit=save_file; This line simply tells OpenDoors to call the save_file() function (to save the RAVOTE.BBS data file) before it exits. If you do not wish OpenDoors to call any function before exiting, simply leave this variable set to NULL (as it is set in the od_init() function). Since whenever OpenDoors detects a loss of carrier, that the user has used up his/her time, etc., it will exit right away, without returning to your program. Setting up a function to have OpenDoors to call before exiting will allow you to finish any uncompleted business, such as closing data files, or what have you. After RAVote has done all of these door related setup, it moves on to it's own business. If the RAVOTE.BBS file exists in the current directory, it is opened and read. If the file does not exist, then RAVote creates a new one. Next, RAVote searches through the data file for the name of the user who is currently on-line. This allows RAVote to keep track of all the people who have used it, with its own statistics about them. RAVote also compares the name of the user currently on-line to the name of the system's sysop. If they match, the RAVote will also enable it's sysop-only functions, such as deleting questions from the door. Once RAVote has done all of this housekeeping, it is ready to go to work. Before the main menu is displayed each time, you will notice that the screen is cleared (the od_clr_scr() function only clears the screen if the user has screen clearing mode turned on), as well as the keyboard input buffer. The keyboard buffer is cleared by the od_clear_keybuffer() function, to prevent strange things from happening if the user has been pounding on his keyboard while the door is loading, etc. While all the internal OpenDoors functions check for ANSI mode, RAVote also checks itself, so that it does not display extended characters (such as the line and box drawing characters) to users without ANSI capabilities. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 22 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ THE OPENDOORS DOORDRIVER FUNCTIONS ─┐ └──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CLEAR_KEYBUFFER() Function to clear the input keyboard buffer │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_clear_keybuffer(void) FORMAT: od_clear_keybuffer(); RETURNS: N/A DESCRIPTION: OpenDoors maintains its own keyboard input buffer, to allow the user to "type ahead". This keyboard input buffer will include both the keys hit by the user on-line, and the non-function keys (ie, Alt-C won't appear in here), 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 temorarily prevent the user from having any control over the door, he may use the Alt-K key. The key strokes placed in the OpenDoors type-ahead buffer will be retrieved by the od_get_key() and od_input_str() functions. Thus, if the user chose the key from a menu while it was being displayed, as soon as your program calls the od_get_key() function, this keystroke will already be waiting. 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 hoping it 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 accidentially 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. To erase the contents of the type-ahead buffer, you simply call the od_clear_keybuffer() function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 23 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CLR_LINE() Clears the rest of the current display line │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_clr_line(void) FORMAT: od_clr_line(); 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: 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". 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 or AVATAR 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 teh line manually, the use of this function will cause your door's graphics to display much more quickly when ANSI or AVATAR modes are active. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 24 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CLR_SCR() The OpenDoors clear screen function │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_clr_scr(void) FORMAT: od_clr_scr(); RETURNS: N/A DESCRIPTION: The od_clr_scr() function can be used to clear the door screen. (ie, the user's screen and local screen with the exception of the status line are cleared.) This function will detect the user's screen clearing setting, and only clear the screen if screen clearing is turned on. For more information on the user's screen clearing setting, please refer to the user_attrib variable in the OpenDoors Control Structure section of this manual. If you wish to force a screen clear, even if the user does not have screen clearing turned on (this is not recommended), simply use the function call: od_emulate(12); The od_clr_scr() function acomplishes screen clearing by sending an ASCII 12 character to the remote terminal. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 25 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_DISP() Sends a buffer of text with optional local echo │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_disp(char *buffer,int size,char local_echo) FORMAT: od_clr_line(buffer,size,local_echo); RETURNS: N/A DESCRIPTION: In the past, this function has only been for internal use by the other OpenDoors routines. You will probably have little use for this function in the majority of cases. However, this function can be useful if you wish to have more control over OpenDoor's functioning. The od_disp() function is called with three parameters. The first parameter, *buffer, is a pointer to a buffer of characters you wish to have displayed. The second parameter, size, is simply the number of characters in the buffer. If the third parameter, local_echo, is set to TRUE, then all characters sent to the modem will also be displayed on the local screen. If set to FALSE, then the buffer will be sent to the modem without being echoed to the sysop's screen. For example: To display a single character: od_disp(*character,1,TRUE); To send an ANSI sequence without echoing it to the local screen: od_disp(string,strlen(string),FALSE); ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 26 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_DISP_STR() Displays a string to the screen (remote & local) │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_disp_str(char *string) FORMAT: od_disp_str(string); RETURNS: N/A DESCRIPTION: This function displays the contents of the null-terminated string pointed to by *string. Display is, of course, sent to the local screen and modem (presuming the door is not running in local mode). All modem output is accomplished through the Fossil driver. If directvideo=1, then the screen display is accomplished by direct writes, either to video memory, or to the DesqView screen buffer, if DesqView is active If directvideo is set to 0, then BIOS function calls are used for video output. While using direct video writes results in much greater screen updates speeds, it will also cause difficulties for people running in multitaskers, such as DesqView. Ideally, you could design your door to either accept a command-line parameter or a setting in it's configuration file to allow the sysop using your door to select either direct or BIOS writes. The only thing to keep in mind when using the od_disp_str() function, is that you should use /n/r instead of just /n for a new line. Since many terminal programs require a carriage-return line-feed sequence (/n/r), instead of just a line-feed (/n), for proper results, your door will have to send both characters to the modem. For example, instead of using: od_disp_str("Hello world!\n"); You should use: od_disp_str("Hello world!\n\r"); If you wish to do fancy output formatting, (ie, use of printf style %d, %s, etc. commands), the best thing to do is use the od_printf() function instead. To change the cursor colour or location of output with the od_disp_str() function, please refer to the od_set_cursor() and the od_set_attrib() functions. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 27 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_EMULATE() Displays a character with ANSI/AVATAR emulation │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_emulate(register char in_char) FORMAT: od_emulate(in_char); RETURNS: N/A DESCRIPTION: This function allows you to send sequences to the internal OpenDoors terminal emulator one character at a time. The OpenDoors terminal emulator is fully documented in the description of the od_send_file() function, below. As with the od_disp() function, the od_emulate() function is primarily intended for internal use by OpenDoors, and in most cases you will probably have no need for this function. The characters passed to the od_emulate function will both be sent directly to the modem, and sent to the local screen, after being translated by the terminal emulator. Thus, you could send the characters ESCape,[,2,;,4,H to the emulator to use the ANSI position cursor function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 28 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_EXIT() The OpenDoors Program Termination function │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_exit(int errorlevel,char term_call) FORMAT: od_exit(errorlevel,term_call); RETURNS: N/A DESCRIPTION: You MUST USE THIS FUNCTION when you want your Door to exit. It will deinitialize the fossil driver, re-write changed information to the EXITINFO.BBS file, call your end-of-program function (if any), and then exit with the specified errorlevel. Also, if term_call is set to TRUE, it will also log the user off (for options such as logging off within the door) ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 29 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_GET_KEY() Function to input a key from the keyboard │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_get_key(int wait) FORMAT: od_get_key(FALSE); or od_get_key(TRUE); RETURNS: The next key waiting from the keyboard, or 0 if none. DESCRIPTION: This function gets the next key waiting in the keyboard buffer (see OD_CLEAR_KEYBUFFER for more information on this buffer). 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 sit and wait for a key to be pressed, and then return the value of the key pressed. The ascii character of the key is returned. For example, if you called: key=od_get_key(TRUE); and the user hit the enter key, key would be equal to 13. ┌───────────────────────────┐ │ Some Common ASCII codes │ ├───────────────────────────┤ │ 8 - BackSpace │ │ 9 - Tab │ │ 13 - Enter │ │ 27 - Escape │ │ 32 - Space │ └───────────────────────────┘ You can, of course, also test for any character keys by placing the character in single quotes, for example: key=od_get_key(TRUE); if(key=='?') help(); ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 30 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_INIT() The OpenDoors Initialization function │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_init(void) FORMAT: od_init(); RETURNS: N/A DESCRIPTION: This function initializes any door running under OpenDoors. This function must be called manually if you wish to access data about the user, etc., before you call any other OpenDoors functions. If you do not call the od_init function, it will be called automatically on the first call to any other OpenDoors function. The od_init function will read the DORINFO1.DEF and optionally EXITINFO.BBS (if it exists) in the directory specified by the variable od_control.info_path. It also begins communication with the modem, puts up the status line, and sets 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 section of this manual entitled "The OpenDoors control structure". ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 31 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_INPUT_STR() Input a string from the user. │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_input_str(char *string,int max_len,char minchar, char maxchar) FORMAT: od_input_str(string,max_len,minchar,maxchar); RETURNS: N/A DESCRIPTION: This function allows you to input up to the specified number of characters from the user, with all characters being between the value of minchar and the value of maxchar. Some examples of the od_input_str() function are as follows: ■ 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 Programmer's Manual ───────────────────────────────────── Page 32 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_KERNAL() The OpenDoors Central Control function │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_kernal(void) FORMAT: od_kernal(); RETURNS: N/A DESCRIPTION: This is the function that keeps track of carrier detection, user time left and inactivity timeouts, sysop hotkeys, reading from the modem and updating the status line. It is important that your program calls this or some other OpenDoors function at least every second, if you wish your door to have a quick response. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 33 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_LIST_FILES() List files in a particular file area (using FILES.BBS)│ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_list_files(char *directory) FORMAT: od_list_files(directory); 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 is available from many BBS systems. The file names and descriptions are taken from the FILES.BBS located in the directory pointed to by *directory. Thus, to list the files available for download in C:\APEX\FILES\UPLOADS, simply: od_list_files("C:\\APEX\\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 ODOORS30.LZH The newest version of OpenDoors! RAVOTE30.ZIP RAVote user voting door. BID10.ZIP BBS info. door for new BBS users 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 ODOORS30.LZH The newest version of OpenDoors! RAVOTE30.ZIP RAVote user voting door. BID10.ZIP BBS info. door for new BBS users 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. You may alter the colours 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 ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 34 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_PAGE() "Page The Sysop" function │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_page(void) FORMAT: od_page(); RETURNS: N/A DESCRIPTION: This function can be called to allow the user to page the sysop. It will check for valid paging hours, ask the user why he wishes to chat with the sysop, and page the sysop. The sysop will then be free to break into chat at any time. Sysop paging will also be aborted if the user does not enter a reason for chat. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 35 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_PRINTF() Performs formatted output (remote & local) │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_printf(char *format,...) FORMAT: od_printf(format,arg1,arg2,...,argx); RETURNS: N/A DESCRIPTION: This functions allows you to perform formatted output, in the same manner as you can do normal output with the od_disp_str() function. od_printf() is used in the same manner as any other printf function. For example, to display the time left on-line, you could do: od_printf("Time Left: %d\n\r",od_control.caller_timelimit); For more information on using printf(), please see your Turbo C manuals. For more information on output with the od_printf() function, please see also the od_disp_str() function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 36 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_REPEAT() Repeat the specified character n times │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_repeat(char value,unsigned char times) FORMAT: od_repeat(value,times); RETURNS: N/A DESCRIPTION: This function will repeat character (value), (times) times. In AVATAR mode, this is accomplished by sending a single control sequence (which can make many updates VERY fast). If AVATAR is not enabled, this function simply sends the specified character over and over the appropriate number of times. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 37 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_SEND_FILE() Sends a file from the disk, using terminal emulation │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_send_file(char *filename) FORMAT: od_send_file(filename); 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 or AVATAR text file. The od_send_file() function can be used to display exising BBS text files, such as GOODBYE.A?? 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, and could also optionally allow sysops to customize your door for use on their system. 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 at a 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 three files MAINMENU.ASC, MAINMENU.ANS and MAINMENU.AVT; the .ASC file containing no graphics control codes, the .ANS file containing ANSI graphics control codes, and the .AVT file containing AVATAR 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 extention altogether. Thus, a call to: od_send_file("MAINMENU"); would cause OpenDoors to automatically send the approprate 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 extention), the three filename extentions it will look for are listed on the following page: ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 38 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌───────────┬───────────────────────────────────────────────┐ │ Extention │ 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 │ └───────────┴───────────────────────────────────────────────┘ Thus, if the user has AVATAR graphics enabled od_send_file() will first search for the .AVT file. If no file exists with the specified filename and a .AVT extention, od_send_file() will then search for a .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 disply the .ASC file. The 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 sysop's local screen (regardless of the actual filename extention). 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 Apex/Remote Access/QuickBBS style control codes. The control codes supported by OpenDoors are listed in the chart below. When these control codes are inserted into the file, OpenDoors will replace them with various pieces of user or system information. ┌─────────┬───────┬───────────────────────────────────┐ │ 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 │ └─────────┴───────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 39 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────┬───────┬───────────────────────────────────┐ │ CONTROL │ ASCII │ │ │ CODE │ VALUE │ DESCRIPTION │ ├─────────┼───────┼───────────────────────────────────┤ │ ^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 │ │ ^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 │ └─────────┴───────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 40 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_SET_ATTRIB() Function to change the text colour in ANSI mode │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_set_attrib(int color) FORMAT: od_set_attrib(color); RETURNS: N/A DESCRIPTION: This function will only have an effect if the user has ANSI mode turned on. In ANSI mode, this function can be used to change the current colour of the text being displayed. The color is passed as an IBM-style screen attribute, not as the actuall ANSI color codes. The color codes are as follows: ┌──── Forground colour ┌─┴┐ Bit: 76543210 └─┬┘ └──────── Background colour ┌───────────────────────┐ ┌───────────────┬──────────┐ │ Forground colours │ │ Background │ Flashing │ ├─────┬─────────────────┤ ├─────┬─────────┼──────────┤ │ 0 │ Black │ │ 0 │ Black │ Off │ │ 1 │ Blue │ │ 16 │ Blue │ Off │ │ 2 │ Green │ │ 32 │ Green │ Off │ │ 3 │ Cyan │ │ 48 │ Cyan │ Off │ │ 4 │ Red │ │ 64 │ Red │ Off │ │ 5 │ Magenta │ │ 80 │ Magenta │ Off │ │ 6 │ Brown │ │ 96 │ Brown │ Off │ │ 7 │ White (grey) │ │ 112 │ White │ Off │ │ 8 │ Bright Black │ │ 128 │ Black │ On │ │ 9 │ Bright Blue │ │ 144 │ Blue │ On │ │ 10 │ Bright Green │ │ 160 │ Green │ On │ │ 11 │ Bright Cyan │ │ 176 │ Cyan │ On │ │ 12 │ Bright Red │ │ 192 │ Red │ On │ │ 13 │ Bright Magenta │ │ 208 │ Magenta │ On │ │ 14 │ Yellow │ │ 224 │ Brown │ On │ │ 15 │ White (bright) │ │ 240 │ White │ On │ └─────┴─────────────────┘ └─────┴─────────┴──────────┘ To calculate the desired colour index, simply add the number for your forground colour to the number for your background colour. ***NOTE*** If you prefer to set the colours using forground and background colours separately, you can use od_set_color. For example: od_set_color(L_WHITE,D_BLACK); Would set the current colour to Light White on Dark Black. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 41 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_SET_CURSOR() Function to locate the cursor in ANSI mode │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: void od_set_cursor(int row, int col) FORMAT: od_set_cursor(row,col); RETURNS: N/A DESCRIPTION: This function will only have an effect if the user has ANSI mode turned on. In ANSI mode, this function can be used to position the cursor anywhere on the screen (cursor is moved both locally and on the remote terminal). Row can have a value of 1 to 23, and col can have a value of 1 to 80. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 42 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ THE OPENDOORS CONTROL STRUCTURE ─┐ └───────────────────────────────────┘ The OpenDoors "Control Structure" is used by the door-driver portion of OpenDoors to provide you with a large range of information, and to allow you to control OpenDoor's behaviour. While OpenDoors takes care of just about every detail of your door's operation, there will still be times when you want to take complete control yourself. The OpenDoors control structure is your gateway to all types of information about the user who is on-line, as well as allowing your to customize OpenDoor's performance. The OpenDoors control structure is simply a normal C struct, named od_control, and defined in the file OPENDOOR.H. Listed below are simply the names of the structure elements. So, if you wish to access something such as system_name, you will have to refer to it as: od_control.system_name 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 colours, 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. The information in this second type of variable is read from the door information file, a small file created by the BBS specifically for the purpose of communicating with doors. Depending on what BBS system your door is running under, the type of door information file will vary. Since different door information files provide different amounts of information, some variables in the control structure will only be available when your door is running under particular BBS systems, while other variables will be available with many or all BBS systems. 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 OpenDoor door can run DIRECTLY under ANY BBS SYSTEM that produces one of these files formats, and under ANY OTHER BBS system when used in conjuction with a door information file conversion utility. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 43 │ └─────────────────────────────────────────────────────────────────────────────┘ ╔═════╦══════════════════════════╦════════════════════════════════════════════╗ ║ Ref ║ File Format ║ Example BBS Systems ║ ╠═════╬══════════════════════════╬════════════════════════════════════════════╣ ║ C ║ CHAIN.TXT ║ Apex, WWIV ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ D ║ DORINFO1.DEF ║ RBBS-PC ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ E ║ DORINFO1.DEF ║ QuickBBS ║ ║ ║ & ║ Remote Access (versions 0.01-0.04) ║ ║ ║ EXITINFO.BBS (Std. Ver.) ║ ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ O ║ DOOR.SYS (DoorWay Style) ║ Apex, Remote Access ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ P ║ DOOR.SYS (PCB/GAP Style) ║ Apex ║ ║ ║ ║ PC-Board ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ S ║ SFDOORS.DAT ║ Apex ║ ║ ║ ║ Spitfire ║ ║ ║ ║ TriTel ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ W ║ CALLINFO.BBS ║ Apex, WildCat ║ ╟─────╫──────────────────────────╫────────────────────────────────────────────╢ ║ X ║ DORINFO1.DEF ║ Apex ║ ║ ║ & ║ Remote Access (versions 1.00 and later) ║ ║ ║ EXITINFO.BBS (Ext. Ver.) ║ ║ ╚═════╩══════════════════════════╩════════════════════════════════════════════╝ The following chart lists all elements (variables) in the OpenDoors control strucutre, along with a description of each variable's usage. The "ref." column of this chart corresponds to the reference letters for the various door information file types, listed above. For those variables in the control structure with letters in their "ref." column, the information contained within them is only valid when your door is running under the corresponding door information file. For example, the user_lastdate variable is only available for door types E, X, C and P (and thus will only contain valid information if your door is running under BBS systems such as Apex, QuickBBS, Remote Access, WWIV, PC-Board and GAP). The type of Door Information file being used is stored in the variable od_control.od_info_type, as described below. Often, you will wish to check the value of this variable to determine whether certain neccessary information is avialable to your door. If the information is not available, you may want to simply use some sort of default value for the variable, or alternatively, not allow your door to run under certain BBS systems. Those variables in the OpenDoors control structure that do not have ANYTHING listed in the "ref." column are always available, regardless of what BBS system your door is running under. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 44 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│ info_path[60] │ This variable contains the path to the │ │ │ │ │ DORINFO1.DEF, and optionally EXITINFO.BBS│ │ │ │ │ files. If this variable is not set, then │ │ │ │ │ OpenDoors will default to the current │ │ │ │ │ directory. Keep in mind that C requires │ │ │ │ │ you to place two backslashes in your │ │ │ │ │ string to get one (ie. "C:\\QUICKBBS\\") │ │ │ │ │ Note also that this should only be set │ │ │ │ │ *BEFORE* calling any OpenDoors functions │ │ │ │ │ │ │CDEOPSWX│char│ port │ The port number of the modem being used │ │ │ │ │ by the door. This is the number used by │ │ │ │ │ the Fossil driver, thus 0=COM1, 1=COM2, │ │ │ │ │ and so on. This could be useful to know │ │ │ │ │ if you are shelling to DSZ, etc. to do │ │ │ │ │ a file transfer. │ │ │ │ │ │ │CDEOPSWX│int │ baud │ This variable contains the baud rate at │ │ │ │ │ which the user is online. This could be │ │ │ │ │ useful to know if you are shelling to │ │ │ │ │ DSZ, etc. to do a file transfer. │ │ │ │ │ │ │ DE X│char│ system_name[40] │ This variable contains the name of the │ │ │ │ │ BBS, as read from the DORINFO1.DEF file │ │ │ │ │ │ │ DE X│char│ sysop_name[40] │ This variable contains the name of the │ │ │ │ │ BBS's sysop │ │ │ │ │ │ │ E X│long│ system_calls │ Total number of calls the BBS has │ │ │ │ │ received. │ │ │ │ │ │ │ E X│char│ system_last_caller │ String containing the name of the │ │ │ │ │ previous caller to the BBS. │ │ │ │ │ │ │ E X│char│ timelog_start_date │ String containing the first day of the │ │ │ │ │ system time usage graph │ │ │ │ │ │ │ E X│int │ timelog_busyperhour│ An array of 24 elements indicating how │ │ │ │ │ busy the BBS has been in each hour of │ │ │ │ │ the day. │ │ │ │ │ │ │ E X│int │ timelog_busyperday │ An array of 7 elements indicating how │ │ │ │ │ much the BBS has been busy each day. Note│ │ │ │ │ that this is not set by several BBS │ │ │ │ │ systems, such as RemoteAccess │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 45 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │CDEOPSWX│char│ user_name[36] │ Name of the user currently on-line │ │ │ │ │ │ │ DE PSWX│char│ user_location[26] │ The city from which the user is calling │ │ │ │ │ │ │ E PSWX│char│ user_password[16] │ The user's password for the BBS │ │ │ │ │ │ │ E P X│char│ user_dataphone[13] │ The user's business/data phone number │ │ │ │ │ │ │ E PS X│char│ user_homephone[13] │ The user's home/voice phone number │ │ │ │ │ │ │ E X│char│ user_lasttime[6] │ String containing the time of the user's │ │ │ │ │ last call, in the format: │ │ │ │ │ │ │ │ │ │ HH:MM │ │ │ │ │ │ │C E P X│char│ user_lastdate[9] │ String containing the date of the user's │ │ │ │ │ last call, in the format: │ │ │ │ │ │ │ │ │ │ MM-DD-YY │ │ │ │ │ │ │ E X│char│ user_attribute │ The user's attribute flags. Each bit of │ │ │ │ │ this flag stores a seperate piece of │ │ │ │ │ information the user or a seperate user │ │ │ │ │ setting, 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 │ │ │ │ │ │ └─────┴──────┴───────────────────────┘ │ │ │ │ │ │ │ E X│char│ user_flags[4] │ Sysop defined user access flags (A-D) │ │ │ │ │ │ │ E X│int │ user_credit │ The user's netmail credit (in cents) │ │ │ │ │ │ │ E X│int │ user_pending │ Amound of pending netmail credit │ │ │ │ │ │ │ E X│int │ user_messages │ Number of messages written by user │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 46 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ E X│int │ user_lastread │ Number of last message read │ │ │ │ │ │ │C E PSWX│int │ user_security │ The user's security level │ │ │ │ │ │ │ E P X│int │ user_numcalls │ Number of times the user has called │ │ │ │ │ │ │ E PS X│int │ user_uploads │ Number of files the user has uploaded │ │ │ │ │ │ │ E PS X│int │ user_downloads │ Number of files the user has d/led │ │ │ │ │ │ │ E S X│int │ user_upk │ Number of Kbytes uploaded │ │ │ │ │ │ │ E S X│int │ user_downk │ Number of Kbytes downloaded │ │ │ │ │ │ │ E PS X│int │ user_todayk │ Number of Kbytes downloaded today │ │ │ │ │ │ │ E X│int │ user_time_used │ Amount of time user has used today │ │ │ │ │ │ │C E P WX│int │ user_screen_length │ Length of the user's screen │ │ │ │ │ │ │ E X│char│ user_last_pwdchange│ When the user last changed password │ │ │ │ │ │ │ E X│char│ user_attrib2 │ Additional user attribute flags. As with │ │ │ │ │ the user_attrib variable, each bit of │ │ │ │ │ this flag stores a seperate piece of │ │ │ │ │ information the user or a seperate user │ │ │ │ │ setting, 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 │ │ │ │ │ │ └─────┴──────┴───────────────────────┘ │ │ │ │ │ │ │ E X│char│ event_status │ The status of the next system event │ │ │ │ │ │ │ E X│char│ event_starttime[6] │ When the next event is scheduled to run │ │ │ │ │ │ │ E X│char│ event_errorlevel │ ErrorLevel for the next event │ │ │ │ │ │ │ E X│char│ event_days │ Which days the event is active │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 47 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ E X│char│ event_force │ TRUE if the user should be forced off- │ │ │ │ │ line in order to accomodate this event │ │ │ │ │ │ │ E X│char│ event_last_run[9] │ Date the event was last run │ │ │ │ │ │ │ E X│char│ caller_netmail │ Has NetMail been entered this call │ │ │ │ entered │ (caller_netmailentered) │ │ │ │ │ │ │ E X│char│ caller_echomail │ Has EchoMail been entered this call │ │ │ │ entered │ (caller_echomailentered) │ │ │ │ │ │ │ E X│char│ caller_logintime[6]│ Time at which the user logged on │ │ │ │ │ │ │ E X│char│ caller_logindate[9]│ Date on which the user logged on │ │ │ │ │ │ │CDEOPSWX│int │ caller_timelimit │ Amount of time user has left online, in │ │ │ │ │ minutes │ │ │ │ │ │ │ E X│long│ caller_loginsec │ Security level user had upon login │ │ │ │ │ │ │ E X│long│ caller_credit │ How much credit the user has │ │ │ │ │ │ │ E X│int │ caller_userrecord │ Number of record in USERS.BBS file │ │ │ │ │ │ │ E X│int │ caller_readthru │ User's readthru status │ │ │ │ │ │ │ E X│int │ caller_numpages │ Number of times users has paged sysop │ │ │ │ │ │ │ E X│int │ caller_downlimit │ User's daily download limit │ │ │ │ │ │ │ E X│char│ caller_ │ Time at which the door information file │ │ │ │ timeofcreation[6] │ was created. │ │ │ │ │ │ │ E X│char│ caller_ │ User's password at logon │ │ │ │ logonpassword[16] │ │ │ │ │ │ │ │ E X│char│ caller_wantchat │ Does the user want to chat? │ │ │ │ │ │ │CDEOPSWX│char│ caller_ansi │ Does the user have ANSI mode on │ │ │ │ │ │ │C PS │int │ caller_usernum │ The user's user record number within the │ │ │ │ │ user file. │ │ │ │ │ │ │C │char│ caller_callsign[12]│ User's amature radio call-sign, if any │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 48 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │C │char│ caller_sex │ Lists the gender of the user, contains: │ │ │ │ │ `F' for female │ │ │ │ │ or │ │ │ │ │ `M' for male │ │ │ │ │ │ │ X│int │ ra_deducted_time │ Time that has been deducted from user │ │ │ │ │ │ │ X│char│ ra_menustack[50][9]│ The current Apex/RA menu stack │ │ │ │ │ │ │ X│char│ ra_menustackpointer│ Pointer to position in menu stack │ │ │ │ │ │ │C X│char│ ra_userhandle[36] │ The user's handle (alias), if any │ │ │ │ │ │ │ X│char│ ra_comment[81] │ Sysop's comment about the user │ │ │ │ │ │ │ X│char│ ra_firstcall[9] │ Date of the user's fist call │ │ │ │ │ │ │ X│char│ ra_combinedrecord │ The user's combined message areas │ │ │ │ │ │ │ X│char│ ra_birthday[9] │ Date of the user's birth │ │ │ │ │ │ │ P X│char│ ra_subdate[9] │ Date user's subscription expires │ │ │ │ │ │ │C X│char│ ra_screenwidth │ # characters on user's screen │ │ │ │ │ │ │ S X│char│ ra_error_free │ Is it an error free connection │ │ │ │ │ │ │ S X│char│ ra_sysop_next │ "Sysop Next" toggle │ │ │ │ │ │ │ X│char│ ra_emsi_session │ Has an IEMSI session been established │ │ │ │ │ │ │ X│char│ ra_emsi_crtdef[41] │ EMSI display mode string │ │ │ │ │ │ │ X│char│ ra_emsi_protocols │ EMSI protocols supported string │ │ │ │ │ │ │ X│char│ ra_emsi_capabilitie│ EMSI capabilities string │ │ │ │ │ │ │ X│char│ ra_emsi_requests[41│ EMSI requests string │ │ │ │ │ │ │ X│char│ ra_emsi_software[41│ EMSI software string │ │ │ │ │ │ │ X│char│ ra_hold_attr1 │ EMSI hold attribute settings │ │ │ │ │ │ │ X│char│ ra_hold_attr2 │ second EMSI hold attribute │ │ │ │ │ │ │ X│char│ ra_hold_len │ EMSI hold length │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 49 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│ od_status_on │ If TRUE, then the status line is on, if │ │ │ │ │ FALSE, then the status bar is off. │ │ │ │ │ │ │ │char│ od_okaytopage │ This allows you to enable and disable the│ │ │ │ │ sysop paging at any time. Or, if this │ │ │ │ │ variable is set to MAYBE, then OpenDoors │ │ │ │ │ will refer to the od_pagestartmin and │ │ │ │ │ od_pageendmin variables to decide whether│ │ │ │ │ sysop paging is available at the current │ │ │ │ │ time. │ │ │ │ │ │ │ │int │ od_pagestartmin │ When sysop paging can begin │ │ │ │ │ │ │ │int │ od_pageendmin │ When sysop paging must end │ │ │ │ │ │ │ │void│ (*od_before_exit) │ OpenDoors will always call the function │ │ │ │ │ pointed to by this element whenever it │ │ │ │ │ exits. (regardless as to whether the door│ │ │ │ │ requested an exit by calling od_exit, or │ │ │ │ │ OpenDoors exits because of loss of │ │ │ │ │ carrier, etc. See the RAVote Demo Door │ │ │ │ │ for an example of using this feature. │ │ │ │ │ │ │ │ │ │ │ │ │void│ (*od_cbefore_chat) │ The function pointed to by this pointer │ │ │ │ │ will be called prior to entering sysop │ │ │ │ │ chat mode. This may be useful for │ │ │ │ │ allowing you to save the screen contents │ │ │ │ │ prior to chat, and restoring them │ │ │ │ │ afterwards. │ │ │ │ │ │ │ │void│ (*od_cafter_chat) │ The function pointed to by od_cafter_chat│ │ │ │ │ will be called after chat mode has ended.│ │ │ │ │ │ │ │void│ (*od_cbefore_shell)│ As with od_cbefore_chat, od_cbefore_shell│ │ │ │ │ will be called prior to any sysop shell │ │ │ │ │ to DOS. │ │ │ │ │ │ │ │void│ (*od_cafter_shell) │ The function pointed to by this pointer │ │ │ │ │ will be called after any sysop shell │ │ │ │ │ to DOS. │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 50 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │int │ od_inactivity │ The number of seconds of inactivity │ │ │ │ │ permitted before the user is automaticall│ │ │ │ │ logged off. This value defaults to 200 │ │ │ │ │ seconds, and the user will be warned 5 │ │ │ │ │ seconds before an inactivity timeout. │ │ │ │ │ If you do not wish to have inactivity │ │ │ │ │ timeouts, merely set this variable to a │ │ │ │ │ ridiculously high value, such as 30,000 │ │ │ │ │ │ │ │char│ od_clear_on_exit │ This variable defaults to TRUE. It will │ │ │ │ │ indicate whether you wish OpenDoors to │ │ │ │ │ clear the screen before it exits. While │ │ │ │ │ this does not make a major difference, │ │ │ │ │ if you do not clear the screen, it can │ │ │ │ │ make for smoother looking transitions │ │ │ │ │ from the door back to the BBS, as the │ │ │ │ │ sysop does not have to stare at a blank │ │ │ │ │ screen for a few seconds. │ │ │ │ │ │ │ │char│ od_user_keyboard_on│ Is the user's keyboard enabled (toggled │ │ │ │ │ by the Alt-K hotkey) │ │ │ │ │ │ │ │char│ od_chat_color1 │ Colour of the sysop's text in chat mode. │ │ │ │ │ For information on colour attributes, see│ │ │ │ │ the od_set_attrib() function. │ │ │ │ │ │ │ │char│od_chat_color2 │ Colour of the user's text in chat mode. │ │ │ │ │ │ │ │char│*od_before_shell │ Pointer to the string you wish OpenDoors │ │ │ │ │ to display before it does a DOS shell. │ │ │ │ │ This defaults to "Please wait a moment", │ │ │ │ │ but you can set it to anything you want. │ │ │ │ │ If you set the value of this pointer to │ │ │ │ │ NULL, then nothing will be displayed │ │ │ │ │ when the sysop shells to DOS (useful │ │ │ │ │ for ANSI doors where you don't want to │ │ │ │ │ have your screen screwed up when the │ │ │ │ │ sysop shells to DOS. │ │ │ │ │ │ │ │char│*od_after_shell │ The same as od_before_shell, displayed │ │ │ │ │ after the sysop returns from a DOS shell │ │ │ │ │ │ │ │char│*od_before_chat │ The same as od_before_shell, displayed │ │ │ │ │ whenever the sysop chooses to enter chat │ │ │ │ │ mode. │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 51 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│*od_after_chat │ The same as od_before_shell, displayed │ │ │ │ │ when chat mode is terminated. │ │ │ │ │ │ │ │char│*od_help_text │ Pointer to a string that is displayed │ │ │ │ │ on the 24th line of the screen when the │ │ │ │ │ sysop presses the F9 (help) key. This │ │ │ │ │ defaults to simply listing all the │ │ │ │ │ OpenDoors hotkeys. Note that this string │ │ │ │ │ MUST be 79 characters in length! │ │ │ │ │ │ │ │char│od_num_keys │ These three variables allow you to add │ │ │int │od_hot_key[16] │ your own Sysop Hotkeys to any door. │ │ │int │od_last_hot │ Simply find the ascii code & scan code │ │ │ │ │ of the function key you wish to trap. │ │ │ │ │ (as returned by bioskey()), and place │ │ │ │ │ each of them in the 0th, 1st, 2nd, etc. │ │ │ │ │ positions of the od_hot_key array. Then │ │ │ │ │ set od_num_keys to the number of hotkeys │ │ │ │ │ you have defined. Whenever OpenDoors │ │ │ │ │ receives one of these hotkeys, it will │ │ │ │ │ be placed in the od_last_hot variable. │ │ │ │ │ Thus, in each iteration of this loop you │ │ │ │ │ can check for a non-zero value in the │ │ │ │ │ od_control.od_last_hot variable. If one │ │ │ │ │ is found, you can process your hotkey, │ │ │ │ │ and then reset this value back to 0. │ │ │ │ │ │ │ │char│od_avatar │ Is either TRUE or FALSE, depending on │ │ │ │ │ whether AVATAR graphics mode is active. │ │ │ │ │ If you door is running under Apex or RA │ │ │ │ │ 1.00-, this is detected automatically. │ │ │ │ │ Otherwise, you may wish to set this │ │ │ │ │ variable manually. │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 52 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│od_info_type │ This variable lists the type of BBS door │ │ │ │ │ information file that OpenDoors was able │ │ │ │ │ to get user information from. This │ │ │ │ │ variable will allow you to identify what │ │ │ │ │ elements of the control structure are │ │ │ │ │ available, as described prior to this │ │ │ │ │ chart. This variable will contain one of │ │ │ │ │ these values: │ │ │ │ │ │ │ │ │ │ ┌──────────────┬──────────────┬─────┐ │ │ │ │ │ │ VALUE │ FILENAME │ REF │ │ │ │ │ │ ├──────────────┼──────────────┼─────┤ │ │ │ │ │ │ DORINFO1 │ DORINFO1.DEF │ D │ │ │ │ │ │ │ EXITINFO │ EXITINFO.BBS │ E │ │ │ │ │ │ │ RA1EXITINFO │ EXITINFO.BBS │ X │ │ │ │ │ │ │ CHAINTXT │ CHAIN.TXT │ C │ │ │ │ │ │ │ SFDOORSDAT │ SFDOORS.DAT │ S │ │ │ │ │ │ │ CALLINFO │ CALLINFO.BBS │ W │ │ │ │ │ │ │ DOORSYS_GAP │ DOOR.SYS │ P │ │ │ │ │ │ │ DOORSYS_DRWY │ DOOR.SYS │ O │ │ │ │ │ │ └──────────────┴──────────────┴─────┘ │ │ │ │ │ (For more complete information │ │ │ │ │ on each reference letter, please │ │ │ │ │ refer to the door information │ │ │ │ │ file types chart.) │ │ │ │ │ │ │ │char│od_page_len │ This allows you to customize how many │ │ │ │ │ beeps a sysop page will consist of. │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 53 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│od_disable │This variable can be used to disable │ │ │ │ │certain OpenDoors features that are │ │ │ │ │normally active, to allow for maximum │ │ │ │ │customization. Each bit of this variable │ │ │ │ │represents a different feature that can │ │ │ │ │be disabled. To DISABLE the feature, you │ │ │ │ │set the bit that corrosponds to that │ │ │ │ │feature, and to ENABLE the feature, the │ │ │ │ │bit is reset. Each bit is represented by │ │ │ │ │a keyword, as follows: │ │ │ │ │ │ │ │ │ │ DIS_INFOFILE - This allows you to │ │ │ │ │ prevent OpenDoors from attempting │ │ │ │ │ to read a door information file. │ │ │ │ │ If you wish to disable reading │ │ │ │ │ of the info file, you must do so │ │ │ │ │ prior to calling any OpenDoors │ │ │ │ │ functions. You must also set │ │ │ │ │ any variables, such as comm port, │ │ │ │ │ baud rate, user name, etc. │ │ │ │ │ yourself. │ │ │ │ │ │ │ │ │ │ DIS_CARRIERDETECT - This allows you │ │ │ │ │ to prevent OpenDoors from exiting │ │ │ │ │ when it looses carrier detection. │ │ │ │ │ You may set or reset this bit at │ │ │ │ │ any time. Use of this flag might │ │ │ │ │ be useful, for example, when │ │ │ │ │ writing a call-back-verification │ │ │ │ │ door, where the system actually │ │ │ │ │ hangs up on the user and then │ │ │ │ │ calls back. │ │ │ │ │ │ │ │ │ │ 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 │ │ │ │ │ any time. │ │ │ │ │ │ │ │ │ │For example, to disable carrier detection,│ │ │ │ │you could use this line: │ │ │ │ │ │ │ │ │ │ od_control.od_disable|=DIS_CARRIERDETECT;│ │ │ │ │ │ │ │ │ │and to re-enable carrier detection, you │ │ │ │ │could: │ │ │ │ │ │ │ │ │ │ od_control.od_disable&=~DIS_CARRIERDETECT│ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 54 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │int │key_hangup │The `key_' variables allow you to redefine│ │ │ │ │the sysop function keys. (Such as hangup, │ │ │ │ │shell to dos, etc.) The function keys can │ │ │ │ │be customized by setting these values to │ │ │ │ │the ascii value and scan-code of the │ │ │ │ │desired key (as returned by the bioskey() │ │ │ │ │function). The key_hangup variable allows │ │ │ │ │you to redefine the sysop key-combination │ │ │ │ │used to hangup on the user. │ │ │ │ │ │ │ │int │key_drop2bbs │This variable allows you to redfine the │ │ │ │ │sysop key-combination used to drop the │ │ │ │ │user back to the BBS system, without │ │ │ │ │logging them off. This key is set in the │ │ │ │ │same manner as the key_hangup variable │ │ │ │ │ │ │ │int │key_dosshell │As above, allows you to redefine the │ │ │ │ │sysop Shell to DOS key. │ │ │ │ │ │ │ │int │key_chat │Used to redefine the sysop Chat key. │ │ │ │ │ │ │ │int │key_sysopnext │Used to redefine the "sysop next" key. │ │ │ │ │ │ │ │int │key_lockout │Used to redfine the "lockout-user" key. │ │ │ │ │ │ │ │int │key_help │Sets the key that displays the help- │ │ │ │ │status line for the sysop. │ │ │ │ │ │ │ │int │key_nohelp │Sets the key that returns the sysop's │ │ │ │ │status line to normal. │ │ │ │ │ │ │ │int │key_keyboardoff │Alters the key that allows the sysop to │ │ │ │ │temporarily disable the user's keyboard. │ │ │ │ │ │ │ │int │key_moretime │The key that increases the user's time │ │ │ │ │ │ │ │int │key_lesstime │The key that decreases the user's time │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 55 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────────┬────┬────────────────────┬──────────────────────────────────────────┐ │ REF. │ │ │ │ │CDEOPSWX│TYPE│ VARIABLE NAME │ VARIABLE DESCRIPTION │ ├────────┼────┼────────────────────┼──────────────────────────────────────────┤ │ │char│od_rbbs_node │If your door is running under RBBS-PC, │ │ │ │ │you may wish it to force OpenDoors to │ │ │ │ │read the DORINFO?.DEF file for a node │ │ │ │ │other than node 1 (ie, DORINFO3.DEF, etc.)│ │ │ │ │To do this, simply set the od_rbbs_node │ │ │ │ │variable to the node your door is running │ │ │ │ │under. If this variable is not set, │ │ │ │ │OpenDoors will automatically look for the │ │ │ │ │node 1 file (DORINFO1.DEF) │ │ │ │ │ │ │ │char│od_list_title_col │These five variables set the colour used │ │ │char│od_list_name_col │by the od_list_files() function when │ │ │char│od_list_size_col │listing the files in a particular file │ │ │char│od_list_comment_col │area. The od_list_title_col variable │ │ │char│od_list_offline_col │allows you to set the colour of title │ │ │ │ │lines in the FILES.BBS file, the │ │ │ │ │od_list_name_col allows you to set the │ │ │ │ │filename colour, od_list_size_col allows │ │ │ │ │you to set the colour of the file size │ │ │ │ │column, od_list_comment_col allows you │ │ │ │ │to set the comment colour, and │ │ │ │ │od_list_offline_col allows you to set the │ │ │ │ │colour of the missing files indicator. │ │ │ │ │All of these variables are set to their │ │ │ │ │default values by the od_init() function. │ └────────┴────┴────────────────────┴──────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 56 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ BBS SYSTEM AND CONFIGURATION FILES ─┐ └──────────────────────────────────────┘ OpenDoors provides a full set of routines for reading and writing various BBS system and configuration files. This portion of the "System File Engine" will automatically detect the type of configuration and system files present on the system. When you are reading or writing a configuration file, OpenDoors will automatically read this information into structures for you, performing any necessary variable converstions for you. Thus, you need not worry yourself with any of the internal file formats used by various BBS systems, as OpenDoors will automatically read the specific data; and in fact you do not even have to know what BBS system your door or utility is running under in most cases. (note that the current version of the OpenDoors "System File Engine" only supports Apex, RemoteAccess and RA backwards compatible BBS systems.) The configuration/system file portion of the File Engine are divided into these portions: General Configuration (CONFIG.RA): This is where the general BBS configuration information such as system directories, colours, modem control codes, and much more. File Area Configuration (FILES.RA): This gives you access to a list of the various file areas on the BBS, with information on each area such as it's name, directory, and so on. Message Area Configuration (MESSAGES.RA): This gives you access to a list of the message areas on the BBS, with information on each area such as it's name, type and other information. BBS Timelog (TIMELOG.BBS): This structure stores a record of how busy the BBS has been on average at different times of day. This is the same information that is used to construct a system activity graph. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 57 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ MAIN CONFIGURATION FILE(S) ─┐ └──────────────────────────────┘ Among the BBS system files that OpenDoors gives you access to is the main BBS configuration. These file(s) give you access to a wide variety of general BBS configuration information, that can be useful in almost any BBS door, utility program, etc. This information is stored in a dynamically allocated structure, pointed to by cfg. Below each variable in this structure is listed, along with a brief description of the information stored within it. Since the cfg variable is actually a pointer to the structure, and not the structure itself, remember that you must access elements within it by using the -> operator in C. For example, to print the name of the BBS system your utility is running under, you could do: puts(cfg->system_name); Or to set the maximum baud rate of the BBS to 9600, you could: cfg->baud=9600; Beginning on the next page are the individual elements of the cfg structure, along with a brief description of their use. Note that before this information can be accessed, you must read it using the od_read_config() function, and to save your changes to the configuration you must use the od_write_config() function. The use of both of these functions is described after the chart. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 58 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ int │ version_id │ This entry indicates the BBS software │ │ │ │ version that the configuration file was │ │ │ │ created by. Thus, for version 0.04, this │ │ │ │ variable would have a value of 0x0004. For │ │ │ │ version 1.00, it would contain a value of │ │ │ │ 0x010 │ │ │ │ │ │ char │ commport │ Comm port that the modem is on. (NOT │ │ │ │ FOSSIL port - ie, COM1==1, COM2==2, etc.) │ │ │ │ │ │ int │ baud │ This unigned int stores the maximum baud │ │ │ │ rate supported by the BBS │ │ │ │ │ │ char │ init_tries │ Number of times to attempt to initialize │ │ │ │ the modem before exiting with an error │ │ │ │ │ │ char │ init_str[71] │ Modem command string used to re-initialize │ │ │ │ the modem when the BBS is first brought │ │ │ │ on-line │ │ │ │ │ │ char │ busy_str[71] │ Modem command string sent to the modem when │ │ │ │ the BBS is unavailable. (ie, ATH1) │ │ │ │ │ │ char │ init_resp[41] │ The modem response string that indicates │ │ │ │ modem initialization was successful │ │ │ │ │ │ char │ busy_resp[41] │ The modem response string that indicates │ │ │ │ the busy command was successful │ │ │ │ │ │ char │ connect_300[41] │ String sent by modem when a 300 baud │ │ │ │ connection has been established │ │ │ │ │ │ char │ connect_1200[41] │ 1200 baud connect string │ │ │ │ │ │ char │ connect_2400[41] │ 2400 baud connect string │ │ │ │ │ │ char │ connect_4800[41] │ 4800 baud connect string │ │ │ │ │ │ char │ connect_9600[41] │ 9600 baud connect string │ │ │ │ │ │ char │ connect_19k[41] │ 19K baud connect string │ │ │ │ │ │ char │ connect_38k[41] │ 38K baud connect string │ │ │ │ │ │ char │ answer_phone │ TRUE/FALSE value, indicating whether the │ │ │ │ BBS should manually answer inbound calls │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 59 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ ring_str[21] │ String sent by the modem when an inbound │ │ │ │ call (ring) is detected │ │ │ │ │ │ char │ answer_str[21] │ Command string to be sent to the modem to │ │ │ │ force a manual answer │ │ │ │ │ │ char │ flush_buffer │ Should the modem buffer be flushed prior │ │ │ │ to sending strings. │ │ │ │ │ │ int │ modem_delay │ Delay to be used when sending command │ │ │ │ strings to the modem │ │ │ │ │ │ int │ minimum_baud │ Unsigned integer indicating the lowest │ │ │ │ baud rate at which inbound calls should │ │ │ │ be permitted │ │ │ │ │ │ int │ graphics_baud │ Unsigned integer indicating the lowest baud │ │ │ │ rate at which ANSI/AVATAR graphics modes │ │ │ │ should be permitted │ │ │ │ │ │ int │ transfer_baud │ Unsigned integer indicating the lowest baud │ │ │ │ rate at which file transfers should be │ │ │ │ permitted │ │ │ │ │ │ char │ slow_baud_time_start[6]│ String containing 24-hour time at which │ │ │ │ slow baud rate calls may begin │ │ │ │ │ │ char │ slow_baud_time_end[6] │ String containing 24-hour time at which │ │ │ │ slow baud rate calls must end │ │ │ │ │ │ char │ download_time_start[6] │ String containing 24-hour time at which │ │ │ │ file downloads may begin │ │ │ │ │ │ char │ download_time_end[6] │ String containing 24-hour time at which │ │ │ │ file downloads must end │ │ │ │ │ │ char │ paging_time_start[6] │ String containing 24-hour time when sysop │ │ │ │ paging may begin │ │ │ │ │ │ char │ paging_time_end[6] │ String containing 24-hour time when sysop │ │ │ │ paging must end │ │ │ │ │ │ char │ loading_msg[71] │ Text displayed to user when a door or │ │ │ │ external program is being loaded. │ │ │ │ │ │ char │ list_prompt[71] │ Text displayed to user as a list prompt │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 60 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ int │ pwd_expiry │ After how many calls should the user be │ │ │ │ forced to change their password │ │ │ │ │ │ char │ menu_path[61] │ Path to the directory where the BBS menu │ │ │ │ files are stored │ │ │ │ │ │ int │ text_path[61] │ Path to the directory where the BBS text │ │ │ │ files (.ASC/.ANS/.AVT files) are stored │ │ │ │ │ │ int │ net_path[61] │ Path to the netmail directory │ │ │ │ │ │ int │ nodelist_path[61] │ Path to the nodelist files │ │ │ │ │ │ int │ msg_base_path[61] │ Path to hudson message base and user base │ │ │ │ files │ │ │ │ │ │ int │ sys_path[61] │ Path to the main system directory │ │ │ │ │ │ int │ external_ed_cmd[61] │ Command string used to invoke the external │ │ │ │ full-screen editor │ │ │ │ │ │ struc│ _net_address address[10│ Array of 10 structures storing the node │ │ │ │ address(es) of the system. The members of │ │ │ │ this structure are zone, net, node and │ │ │ │ point. Thus, to set the zone of the second │ │ │ │ AKA, you would use: │ │ │ │ │ │ │ │ cfg->address[2].zone=89; │ │ │ │ │ │ charr│ system_name[31] │ String containing the name of the BBS │ │ │ │ │ │ int │ new_security │ Unsigned integer indicating the security │ │ │ │ level that should be given to new users │ │ │ │ │ │ int │ new_credit │ The netmail credit that should initially │ │ │ │ be assigned to new users │ │ │ │ │ │ char │ new_flags[4] │ A, B, C and D flags that should be assigned │ │ │ │ to new users. │ │ │ │ │ │ char │ origin_line[61] │ Default origin line to be used in EchoMail │ │ │ │ messages │ │ │ │ │ │ char │ quote_string[16] │ String indicating what text should be placed│ │ │ │ prior to each line of quoted text when the │ │ │ │ message quoting features is being used │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 61 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ sysop[36] │ Full name of the sysop of the BBS │ │ │ │ │ │ char │ log_file_name[61] │ Name of the logfile that the BBS writes to │ │ │ │ │ │ char │ fast_logon │ TRUE/FALSE value indicating whether "fast" │ │ │ │ local logons should be permitted for the │ │ │ │ sysop │ │ │ │ │ │ char │ allow_sys_rem │ TRUE/FALSE value indicating whether the │ │ │ │ sysop should be permitted to log on from │ │ │ │ remote │ │ │ │ │ │ char │ mono_mode │ TRUE/FALSE value indicating whether the │ │ │ │ system is running on a colour or monochrome │ │ │ │ monitor │ │ │ │ │ │ char │ strict_pwd_checking │ Should "strict" password checking be used │ │ │ │ by the BBS system? TRUE/FALSE value │ │ │ │ │ │ char │ direct_write │ Should the BBS system perform it's display │ │ │ │ updates by direct writing. TRUE=yes, FALSE= │ │ │ │ BIOS │ │ │ │ │ │ char │ show_check │ TRUE/FALSE value indicating whether the BBS │ │ │ │ should perform display syncronizing when │ │ │ │ performing direct screen writes to eliminate│ │ │ │ "snow" on old CGA graphics cards │ │ │ │ │ │ int │ credit_factor │ Time credit factor that should be awarded to│ │ │ │ users after uploads │ │ │ │ │ │ int │ user_time_out │ The number of seconds prior to a user │ │ │ │ inactivity timeout │ │ │ │ │ │ int │ logon_time │ The maximum amount of time that the user │ │ │ │ should be granted to complete the logon │ │ │ │ procedure │ │ │ │ │ │ int │ password_tried │ Number of password tries that should be │ │ │ │ permitted before a caller is denied │ │ │ │ access and hung up on │ │ │ │ │ │ int │ max_page │ The maximum number of times which a user is │ │ │ │ permitted to page the sysop per day │ │ │ │ │ │ int │ page_length │ The number of seconds a sysop page should │ │ │ │ last │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 62 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ check_for_multi_logon │ TRUE/FALSE value indicating whether the BBS │ │ │ │ system should prevent the user from logging │ │ │ │ on to more than one node at a time │ │ │ │ │ │ char │ exclude_sysop_from_list│ TRUE/FALSE value indicating whether or not │ │ │ │ the sysop should be excluded from the user │ │ │ │ list, "today's callers" list, etc. │ │ │ │ │ │ char │ one_word_names │ TRUE/FALSE value indicating whether or not │ │ │ │ one word names should be permitted on the │ │ │ │ BBS │ │ │ │ │ │ char │ check_mail │ YES/NO/ASK value indicating whether the │ │ │ │ user's "mailbox" should be checked for new │ │ │ │ mail since their last call, at time of │ │ │ │ logon │ │ │ │ │ │ char │ ask_voice_phone │ Should the system ask new users for their │ │ │ │ home/voice phone number (TRUE/FALSE value) │ │ │ │ │ │ char │ ask_data_phone │ Should the system ask new users for their │ │ │ │ business/data phone number (TRUE/FALSE) │ │ │ │ │ │ char │ do_full_mail_check │ Should the system perform a "full" mail │ │ │ │ check when searching for new messages to │ │ │ │ user (TRUE/FALSE value) │ │ │ │ │ │ char │ allow_file_shells │ TRUE/FALSE value indicating whether or not │ │ │ │ shells to programs should be permitted from │ │ │ │ within text files │ │ │ │ │ │ char │ fix_upload_dates │ TRUE/FALSE value indicating whether or not │ │ │ │ file dates should be reset after uploads │ │ │ │ │ │ char │ show_file_dates │ TRUE/FALSE value indicating whether or not │ │ │ │ file dates should be listed along with │ │ │ │ filenames in file-lists │ │ │ │ │ │ char │ ansi │ YES/NO/ASK value for new user ANSI setting │ │ │ │ │ │ char │ clear_screen │ YES/NO/ASK value for new user's screen │ │ │ │ clearing setting │ │ │ │ │ │ char │ more_prompt │ YES/NO/ASK value for the "continue Y/N" │ │ │ │ prompt setting for new users │ │ │ │ │ │ char │ upload_msgs │ TRUE/FALSE value indicating whether message │ │ │ │ uploads should be permitted │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 63 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ kill_sent │ TRUE/FALSE value indicating whether netmail │ │ │ │ messages should be deleted after they have │ │ │ │ been sent │ │ │ │ │ │ int │ crash_ask_sec │ Unsigned int indicating the minimum security│ │ │ │ level at which netmail "CRASH" mode is │ │ │ │ permitted │ │ │ │ │ │ char │ crash_ask_flags[4] │ A, B, C, and D flag settings required to │ │ │ │ send CrashMail. │ │ │ │ │ │ int │ crash_sec │ Unsigned int indicating the minimum security│ │ │ │ level at which netmail "CRASH" mode is │ │ │ │ always used │ │ │ │ │ │ char │ crash_flags[4] │ A, B, C and D flag settings required for │ │ │ │ netmail "CRASH" mode to always be used │ │ │ │ │ │ int │ f_attach_sec │ Unsigned int inidcating the minimum secuirty│ │ │ │ level at which netmail file attaches should │ │ │ │ be permitted │ │ │ │ │ │ char │ f_attach_flags[4] │ A, B, C and D flag settings required to use │ │ │ │ netmail file-attaching │ │ │ │ │ │ char │ norm_fore │ Normal forground colour │ │ │ │ │ │ char │ norm_back │ Normal background colour │ │ │ │ │ │ char │ stat_fore │ Status line forground colour │ │ │ │ │ │ char │ stat_back │ Status line background colour │ │ │ │ │ │ char │ hi_fore │ Highlight forground colour │ │ │ │ │ │ char │ hi_back │ Highlight background colour │ │ │ │ │ │ char │ wind_fore │ Window forground colour │ │ │ │ │ │ char │ wind_back │ Window background colour │ │ │ │ │ │ char │ exit_local │ Errorlevel at which to exit after a │ │ │ │ local-mode call │ │ │ │ │ │ char │ exit_300 │ Errorlevel at which to exit after a 300 │ │ │ │ baud call │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 64 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ exit_1200 │ Errorlevel to use after 1200 baud call │ │ │ │ │ │ char │ exit_2400 │ Errorlevel to use after 2400 baud call │ │ │ │ │ │ char │ exit_4800 │ Errorlevel to use after 4800 baud call │ │ │ │ │ │ char │ exit_9600 │ Errorlevel to use after 9600 baud call │ │ │ │ │ │ char │ exit_19k │ Errorlevel to use after 19K baud call │ │ │ │ │ │ char │ exit_38k │ Errorlevel to use after 38K baud call │ │ │ │ │ │ char │ multi_line │ TRUE/FALSE value indicating wether multi- │ │ │ │ line mode should be activated │ │ │ │ │ │ char │ min_pwd_len │ Minimum number of characters permitted │ │ │ │ for passwords │ │ │ │ │ │ int │ min_up_space │ Minimum number of Kbytes that must be free │ │ │ │ on drive to permit uploads │ │ │ │ │ │ char │ hot_keys │ New user hot-keys setting (YES/NO/ASK value)│ │ │ │ │ │ char │ border_fore │ Forground colour of border │ │ │ │ │ │ char │ border_back │ Background colour of boarder │ │ │ │ │ │ char │ bar_fore │ Screen status bar (not sysop's status line!)│ │ │ │ forground colour │ │ │ │ │ │ char │ bar_back │ Screen status bar background colour │ │ │ │ │ │ char │ log_style │ Type of log-file format to be used. │ │ │ │ │ │ char │ multi_tasker │ Type of multi-tasker under which the BBS is │ │ │ │ running │ │ │ │ │ │ char │ pwd_board │ Message board where password failure │ │ │ │ messages should be created. │ │ │ │ │ │ int │ buffer_size │ Size of the BBSes internal communications │ │ │ │ buffer │ │ │ │ │ │ char │ f_keys[10][61] │ Macro-key string for each of the function │ │ │ │ keys │ │ │ │ │ │ char │ why_page │ TRUE/FALSE value indicating whether the BBS │ │ │ │ should ask users their reason for wanting to│ │ │ │ chat with the Sysop │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 65 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ leave_msg │ TRUE/FALSE value indicating whether the BBS │ │ │ │ should give the user the option of posting │ │ │ │ a message to the sysop if he does not answer│ │ │ │ the page │ │ │ │ │ │ char │ show_missing_files │ TRUE/FALSE value indicating whether files │ │ │ │ listed in the FILES.BBS file, that do not │ │ │ │ actually exist should be displayed to the │ │ │ │ user │ │ │ │ │ │ char │ missing_string[11] │ String that should be used to flag these │ │ │ │ "missing" files │ │ │ │ │ │ char │ allow_netmail_replies │ TRUE/FALSE value indicating whether users │ │ │ │ should be able to perform NetMail replies │ │ │ │ to messages in EchoMail areas │ │ │ │ │ │ char │ logon_prompt[41] │ String that should be displayed to the user │ │ │ │ to prompt for their name, etc. │ │ │ │ │ │ char │ check_new_files │ YES/NO/ASK value indicating whether a new- │ │ │ │ files scan should be performed at logon time│ │ │ │ │ │ char │ reply_header[61] │ String containing the header to be placed in│ │ │ │ replies to messages addressed to other users│ │ │ │ │ │ char │ blank_secs │ Number of seconds that should be allowed to │ │ │ │ pass prior to screen blanking │ │ │ │ │ │ char │ protocol_attrib[6] │ File transfer attributes for each of the │ │ │ │ built-in file transfer protocols │ │ │ │ │ │ char │ error_free_string[16] │ Modem connect string that indicates an │ │ │ │ error-free connection has been established │ │ │ │ │ │ char │ default_combined[25] │ 200 bits indicating which of the 200 message│ │ │ │ areas should be enabled by default, for │ │ │ │ combined message reading │ │ │ │ │ │ int │ renum_threshold │ Unsigned integer indicating the message │ │ │ │ number threshold after which messages should│ │ │ │ be automatically re-numbered by the message │ │ │ │ base packer │ │ │ │ │ │ char │ left_bracket │ The character to be used for the left │ │ │ │ bracket (such as '(', '[', '{', etc.) in │ │ │ │ various BBS system prompts. │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 66 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ right_bracket │ Character to be used for the right bracket │ │ │ │ │ │ char │ ask_for_handle │ TRUE/FALSE value indicating whether new │ │ │ │ users should be prompted for a pseudonym/ │ │ │ │ handle │ │ │ │ │ │ char │ ask_for_birthdate │ TRUE/FALSE value indicating whether new │ │ │ │ users should be prompted for their date │ │ │ │ of birth │ │ │ │ │ │ char │ confirm_msg_deletes │ TRUE/FALSE value indicating whether or not │ │ │ │ the BBS system should confirm all requests │ │ │ │ to delete messages │ │ │ │ │ │ char │ location_prompt[61] │ String of text that should be displayed as │ │ │ │ a prompt for a new user's location │ │ │ │ │ │ char │ page_prompt[61] │ Prompt that should be displayed when asking │ │ │ │ for user's "reason for chat" │ │ │ │ │ │ char │ user_file_prompt[41] │ Text that should be displayed while the BBS │ │ │ │ system is searching for a user's name in │ │ │ │ the user file │ │ │ │ │ │ char │ new_user_group │ Group number that new users should be │ │ │ │ automatically placed in │ │ │ │ │ │ char │ avatar │ YES/NO/ASK value indicating whether new │ │ │ │ users AVATAR graphics setting should be │ │ │ │ enabled │ │ │ │ │ │ char │ bad_pwd_area │ Message area number in which users may │ │ │ │ leave a message to the sysop after having │ │ │ │ forgotten their password │ │ │ │ │ │ char │ location[41] │ String containing the name of the city/etc │ │ │ │ where the BBS system is located │ │ │ │ │ │ char │ do_after_action │ What the BBS system should do after │ │ │ │ performing some action, such as checking │ │ │ │ for new mail, etc. (ie, pause for a few │ │ │ │ seconds to allow user to read screen) │ │ │ │ │ │ char │ cr_prompt[41] │ String containing prompt that should be │ │ │ │ displayed when waiting for the user to hit │ │ │ │ their Enter key │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 67 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── CONFIGURATION STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ cr_fore │ CR prompt's forground colour │ │ │ │ │ │ char │ cr_back │ CR prompt's background colour │ │ │ │ │ │ char │ continue_prompt[41] │ String that should be displayed for the │ │ │ │ "Continue [Y]/[N]/[=]". │ │ │ │ │ │ char │ list_path[61] │ String containing path to directory │ │ │ │ containing files lists │ │ │ │ │ │ char │ full_msg_view │ YES/NO/ASK value indicating what a new │ │ │ │ user's full-screen-message-viewer setting │ │ │ │ should be │ │ │ │ │ │ char │ emsi_enable │ TRUE/FALSE value indicating whether the │ │ │ │ IEMSI features should be activated │ │ │ │ │ │ char │ emsi_new_user │ TRUE/FALSE value indicating whether first- │ │ │ │ time callers should be permitted to use the │ │ │ │ IEMSI features │ │ │ │ │ │ char │ config_path[80] │ Path where the BBS configuration file is │ │ │ │ found │ │ │ │ │ │ char │ config_type │ Type of BBS configuration that was found by │ │ │ │ OpenDoors. At this time, this value will │ │ │ │ always be Remote Access │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 68 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_CONFIG() Reads the BBS configuration into the cfg structure │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_config(void) FORMAT: od_read_config(); RETURNS: TRUE if successful FALSE if unable to read configuration DESCRIPTION: This function reads the BBS configuration that is located in the directory pointed to by the global variable default_path. od_read_config() will automatically detect the type of BBS configuration present in this directory, and read it into the configuration structure pointed to by cfg. (see above). This structure is dynamically allocated by the od_read_config() function. If not enough memory is present to read this configuration, or if no OpenDoors compatible configuration files are found in the directory, this function will return FALSE. If successful, then this function will return TRUE. All variables and data stored in the configuration files are automatically converted to C format for your use. If you wish to save any changes made to this configuration, simply call the od_write_config() function. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_CONFIG() Saves changes to the previously read BBS configuration│ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_config(void) FORMAT: od_write_config(); RETURNS: TRUE if successful FALSE if unable to write configuration, or if not enough memory is available to write configuration. DESCRIPTION: This function will write any changes to the BBS configuration that was previously read by the od_read_config() function. All variables are automatically converted from C format back to their original formats. Note that this function can only be called if the od_read_config() function has already been successfully used to read the BBS configuration. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 69 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ FILE AREAS CONFIGURATION ─┐ └────────────────────────────┘ Among the BBS system files that OpenDoors gives you access to is the BBS file areas configuration. This configuration file gives you access to a list of the various file areas on the BBS, with information on each area such as it's name, directory, and so on. This information is stored in a dynamically allocated structure, pointed to by file_info. Below each variable in this structure is listed, along with a brief description of the information stored within it. Since the file_info variable is actually a pointer to the structure, and not the structure itself, remember that you must access elements within it by using the -> operator in C. For example, to print the name of the first file area: puts(file_info->area[0].name); Or to set the minimum security level for access to the 2nd file area, you would: file_info->area[1].security=100; On the next page are the individual elements of the file_info structure, along with a brief description of their use. Note that before this information can be accessed, you must read it using the od_read_files() function, and to save your changes to the configuration you must use the od_write_files() function. The use of both of these functions is described after the chart. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 70 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────────── FILE AREAS STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼─────────────────────────┼────────────────────────────────────────────┤ │ │ │ │ │ char │ area[x].name[31] │ String containing the name of file area `x'│ │ │ │ │ │ char │ area[x].attrib │ Attribute settings of file area `x' │ │ │ │ │ │ char │ area[x].path[41] │ Full path to the files available for │ │ │ │ download from file area `x' │ │ │ │ │ │ int │ area[x].security │ Unsigned int containing the minimum │ │ │ │ security level required to access files │ │ │ │ from file area `x' │ │ │ │ │ │ char │ area[x].flags_a │ User's A, B, C and D flag settings │ │ char │ area[x].flags_b │ required to access files from file area │ │ char │ area[x].flags_c │ `x' │ │ char │ area[x].flags_d │ │ │ │ │ │ │ int │ area[x].private_security│ Security level to access private files in │ │ │ │ file area `x' │ │ │ │ │ │ char │ area[x].priv_flags_a │ User's A, B, C and D flag settings │ │ char │ area[x].priv_flags_b │ required to access private files in file │ │ char │ area[x].priv_flags_c │ area `x' │ │ char │ area[x].priv_flags_d │ │ │ │ │ │ │ char │ files_path[80] │ Path to the file areas configuration file │ │ │ │ │ │ char │ files_type │ Type of file areas configuration found. │ │ │ │ At this time, will always be RA │ └──────┴─────────────────────────┴────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 71 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_FILES() Reads the file area configuration │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_files(void) FORMAT: od_read_files(); RETURNS: TRUE if successful FALSE if unable to read configuration DESCRIPTION: This function reads the BBS file area configuration that is located in the directory pointed to by the global variable default_path. od_read_files() will automatically detect the type of file areas configuration present in this directory, and read it into the configuration structure pointed to by file_info. (see above). This structure is dynamically allocated by the od_read_files() function. If not enough memory is present to read this configuration, or if no OpenDoors compatible configuration files are found in the directory, this function will return FALSE. If successful, then this function will return TRUE. All variables and data stored in the configuration files are automatically converted to C format for your use. If you wish to save any changes made to this configuration, simply call the od_write_files() function. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_FILES() Saves changes to the previously read file areas config│ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_files(void) FORMAT: od_write_files(); RETURNS: TRUE if successful FALSE if unable to write configuration, or if not enough memory is available to write configuration. DESCRIPTION: This function will write any changes to the file areas configuration that was previously read by the od_read_files() function. All variables are automatically converted from C format back to their original formats. Note that this function can only be called if the od_read_files() function has already been successfully used to read the file areas configuration. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 72 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ MESSAGE AREAS CONFIGURATION ─┐ └───────────────────────────────┘ Among the BBS system files that OpenDoors gives you access to is the BBS message areas configuration. This configuration file gives you access to a list of the message areas on the BBS, with information on each area such as it's name, type and other information. This information is stored in a dynamically allocated structure, pointed to by message_info. Below each variable in this structure is listed, along with a brief description of the information stored within it. Since the message_info variable is actually a pointer to the structure, and not the structure itself, remember that you must access elements within it by using the -> operator in C. For example, to print the name of the first message area: puts(message_info->area[0].name); Or to set the 2nd message area to be an EchoMail area, you would: message_info->area[1].area_type=TYPE_ECHOMAIL; Beginning on the next page are the individual elements of the message_info structure, along with a brief description of their use. Note that before this information can be accessed, you must read it using the od_read_msgs() function, and to save your changes to the configuration you must use the od_write_msgs() function. The use of both of these functions is described after the chart. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 73 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── MESSAGE AREAS STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼─────────────────────────┼────────────────────────────────────────────┤ │ char │ area[x].name[41] │ String that contains the full name of │ │ │ │ message area # `x' │ │ │ │ │ │ char │ area[x].area_type │ Type of message area # `x'. The message │ │ │ │ area types are one of the following │ │ │ │ constants, defined in the opendoors.h file │ │ │ │ │ │ │ │ TYPE_LOCAL - Messages in this type of │ │ │ │ area are local only to this BBS, │ │ │ │ and do not contain any exportation │ │ │ │ information │ │ │ │ │ │ │ │ TYPE_NETMAIL - Messages in this type of│ │ │ │ area will contain netmail specific │ │ │ │ information, such as to and from │ │ │ │ node addresses │ │ │ │ │ │ │ │ TYPE_ECHOMAIL - Messages in this type │ │ │ │ of area will contain echomail │ │ │ │ specific information, such as │ │ │ │ tearlines and origin lines. │ │ │ │ │ │ char │ area[x].message_kinds │ This variable indicates the type of │ │ │ │ messages that are permitted in message area│ │ │ │ # `x'. Message kinds are again constants │ │ │ │ which are defined in the opendoor.h file, │ │ │ │ and are one of the following: │ │ │ │ │ │ │ │ KIND_BOTH - Messages posted by users │ │ │ │ may be either public or private │ │ │ │ │ │ │ │ KIND_PRIVATE - Messages posted by users│ │ │ │ must always be private │ │ │ │ │ │ │ │ KIND_PUBLIC - Messages posted by users │ │ │ │ must always be public │ │ │ │ │ │ │ │ KIND_READONLY - No messages may be │ │ │ │ posted by users │ └──────┴─────────────────────────┴────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 74 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── MESSAGE AREAS STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼─────────────────────────┼────────────────────────────────────────────┤ │ char │ area[x].attrib │ This variable contains the message area │ │ │ │ attributes for message area # `x'. This │ │ │ │ bitmap has the following bits, who's │ │ │ │ masks are defined again in the opendoor.h │ │ │ │ file: │ │ │ │ │ │ │ │ AREA_ECHOINFO - Indicates whether or │ │ │ │ not EchoMail information should be │ │ │ │ appended to messages in this area │ │ │ │ │ │ │ │ AREA_COMBINED - Indicates whether or │ │ │ │ not this area can be accessed in │ │ │ │ "combined read" mode │ │ │ │ │ │ │ │ AREA_FILEATTACH - Indicates whether or │ │ │ │ not local file attaches should be │ │ │ │ permitted in this area │ │ │ │ │ │ │ │ AREA_ALIASES - Indicates whether users │ │ │ │ may post messages under any alias │ │ │ │ │ │ │ │ AREA_HANDLE - Indicates whether or not │ │ │ │ users may post messages under their │ │ │ │ "handle" │ │ │ │ │ │ char │ area[x].days_kill │ Number of days after which messages in this│ │ │ │ area should be removed by the message base │ │ │ │ packer │ │ │ │ │ │ char │ area[x].recv_kill │ Number of days after which received │ │ │ │ messages in this area should be removed by │ │ │ │ the message base packer │ │ │ │ │ │ int │ area[x].max_msgs │ The maximum number of messages the message │ │ │ │ base packer should leave in this message │ │ │ │ area │ │ │ │ │ │ int │ area[x].read_sec │ Minimum security level and flag settings │ │ char │ area[x].read_flags_a │ a user must have to READ messages in this │ │ char │ area[x].read_flags_b │ area │ │ char │ area[x].read_flags_c │ │ │ char │ area[x].read_flags_d │ │ │ │ │ │ │ int │ area[x].write_sec │ Minimum security level and flag settings │ │ char │ area[x].write_flags_a │ a user must have to POST messages in this │ │ char │ area[x].write_flags_b │ area │ │ char │ area[x].write_flags_c │ │ │ char │ area[x].write_flags_d │ │ └──────┴─────────────────────────┴────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 75 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── MESSAGE AREAS STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼─────────────────────────┼────────────────────────────────────────────┤ │ │ │ │ │ int │ area[x].sysop_sec │ Minimum security level and flag settings │ │ char │ area[x].sysop_flags_a │ a user must have to access the sysop- │ │ char │ area[x].sysop_flags_b │ specific functions for messages in this │ │ char │ area[x].sysop_flags_c │ area │ │ char │ area[x].sysop_flags_d │ │ │ │ │ │ │ char │ area[x].origin_line[61] │ String containing the origin line for │ │ │ │ EchoMail messages posted in this area. If │ │ │ │ this string is blank, then the default │ │ │ │ origin line will be used. │ │ │ │ │ │ char │ area[x].which_aka │ Which of the 10 "AKAs" should be used for │ │ │ │ the origin address of EchoMail OR NetMail │ │ │ │ messages posted in this area │ │ │ │ │ │ char │ msg_path[80] │ String containing the path to the message │ │ │ │ area configuration file │ │ │ │ │ │ char │ msg_type │ Type of message area configuration file │ │ │ │ that was found by OpenDoors. In this │ │ │ │ version, this will always be RA │ └──────┴─────────────────────────┴────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 76 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_MSGS() Reads the message area configuration │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_msgs(void) FORMAT: od_read_msgs(); RETURNS: TRUE if successful FALSE if unable to read configuration DESCRIPTION: This function reads the BBS message area configuration that is located in the directory pointed to by the global variable default_path. od_read_msgs() will automatically detect the type of message areas configuration present in this directory, and read it into the configuration structure pointed to by message_info. (see above). This structure is dynamically allocated by the od_read_msgs() function. If not enough memory is present to read this configuration, or if no OpenDoors compatible configuration files are found in the directory, this function will return FALSE. If successful, then this function will return TRUE. All variables and data stored in the configuration files are automatically converted to C format for your use. If you wish to save any changes made to this configuration, simply call the od_write_msgs() function. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_MSGS() Saves changes to the loaded message areas configuration│ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_msgs(void) FORMAT: od_write_msgs(); RETURNS: TRUE if successful FALSE if unable to write configuration, or if not enough memory is available to write configuration. DESCRIPTION: This function will write any changes to the message areas configuration that was previously read by the od_read_msgs() function. All variables are automatically converted from C format back to their original formats. Note that this function can only be called if the od_read_msgs() function has already been successfully used to read the message areas configuration. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 77 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ SYSTEM EVENTS CONFIGURATION ─┐ └───────────────────────────────┘ OpenDoors also gives you access to the BBS system events configuration. System events can be configured on the BBS to cause it to perform specific activities at pre-scheduled times, such as performing system maintainence, performing mail events, and so on. Using the od_read_events() and od_write_events() functions, you can access and alter information on the various events that have been scheduled. This information is available through the event_file structure, described on the chart below: ┌──────┬────────────────── SYSTEM EVENTS STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ char │event_file.event[x].status │ This variable contains the │ │ │ │ status of event x. The status of│ │ │ │ an event is one of three values,│ │ │ │ defined in opendoor.h: │ │ │ │ │ │ │ │ ES_DELETED - This event should │ │ │ │ be ignored, and can be │ │ │ │ overwritten by the data of │ │ │ │ another event if you wish. │ │ │ │ │ │ │ │ ES_ENABLED - This event is │ │ │ │ enabled, and will be run by │ │ │ │ the BBS at it's scheduled │ │ │ │ time. │ │ │ │ │ │ │ │ ES_DISABLED - This event has │ │ │ │ been temporarily disabled by│ │ │ │ the sysop, and should be │ │ │ │ ignored. However, it's │ │ │ │ information should not be │ │ │ │ erased. │ │ │ │ │ │ char │event_file.event[x].time[6] │ This string contains the time of│ │ │ │ day at which event x is │ │ │ │ scheduled. │ │ │ │ │ │ char │event_file.event[x].errorlevel │ This variable lists the │ │ │ │ level at which the BBS software │ │ │ │ should exit in order to execute │ │ │ │ this event. │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 78 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── SYSTEM EVENTS STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ char │event_file.event[x].days │ This byte is a bitmap indicating│ │ │ │ which of the 7 days of the week │ │ │ │ on which this event should be │ │ │ │ run. (ie, bit 0 == Sunday, │ │ │ │ bit 1 == Monday, etc.) │ │ │ │ │ │ char │event_file.event[x].forced │ This TRUE/FALSE value indicates │ │ │ │ whether or not the user should │ │ │ │ be forced offline in order to │ │ │ │ run this event. │ │ │ │ │ │ char │event_file.event[x].last_date_run[9]│ This string contains the date on│ │ │ │ which event x was last run. │ │ │ │ │ │ char │event_file.filename │ This string stores the full path│ │ │ │ and filename of the event │ │ │ │ configuration file that has been│ │ │ │ read. Normally, you should not │ │ │ │ alter this variable │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 79 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_EVENTS() Reads the system events configuration │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_events(void) FORMAT: od_read_events(); RETURNS: TRUE if successful FALSE if unable to read configuration DESCRIPTION: This function reads the event configuration located in the directory listed in the default_path variable. If the event configuration was found, it will be read into the system event configuration structure, described above. This function will return a value of TRUE if it was successful in reading the system event configuration, or FALSE if it OpenDoors was unable to read the events. You should always check the value returned by this function before attempting to access the system events structure. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_EVENTS() Saves the previously loaded system events config │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_events(void) FORMAT: od_write_events(); RETURNS: TRUE if successful FALSE if unable to save configuration DESCRIPTION: This function is used to save the previously loaded events configuration, stored in the system events structure (described on the previous pages). The event information will be written back to the same file from which it was loaded. This function will return a value of TRUE if it was able to save the event configuration. If it was unable to save the configuration, or if you call this function without having already read the configuration with od_read_events(), then od_write_events() will return a value of FALSE. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 80 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ EXTERNAL PROTOCOLS CONFIGURATION ─┐ └────────────────────────────────────┘ OpenDoors also gives you access to the BBS's external protocols configuration. The external protocols configuration functions give you the ability to access and/or alter the setup of various external file transfer protocols that have been installed into the BBS. Using the od_read_protocols() and od_write_protocols() functions, you can access and alter information on any external protocols that have been installed into the BBS. This information is available through the protocol_file structure, described on the chart below: ┌──────┬──────────────── EXTERNAL PROTOCOLS STRUCTURE ────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ char │protocol_file.record[x].name[16] │This variable contains the name │ │ │ │of external protocol #x, as it │ │ │ │is displayed to the BBS user. │ │ │ │ │ │ char │protocol_file.record[x].active_key │This variable contains the key │ │ │ │used to selected external │ │ │ │protocol #x from the menu. │ │ │ │ │ │ char │ ...record[x].opus_ctl_file │This entry has a TRUE/FALSE │ │ │ │value, indicating whether or not │ │ │ │this protocol uses an OPUS type │ │ │ │logfile. │ │ │ │ │ │ char │protocol_file.record[x].batch_avail │This entry also has a TRUE/FALSE │ │ │ │value, and indicates whether the │ │ │ │protocol supports batch file │ │ │ │transfers. │ │ │ │ │ │ char │protocol_file.record[x].enabled │This entry has a value of 1 if │ │ │ │the external protocol is │ │ │ │enabled, and 0 if the protocol │ │ │ │has been temporarily disabled. │ │ │ │ │ │ char │protocol_file.record[x].log_file[81]│This string lists the filename of│ │ │ │the logfile produced by external │ │ │ │protocol #x. │ │ │ │ │ │ char │protocol_file.record[x].ctl_file[81]│This string lists the control │ │ │ │file to be produced for each │ │ │ │external protocol. │ │ │ │ │ │ char │protocol_file.record[x].down_cmd[81]│This string contains the command │ │ │ │that should be executed by the │ │ │ │BBS in order to start a download │ │ │ │using each external protocol. │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 81 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────── EXTERNAL PROTOCOLS STRUCTURE ────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ char │protocol_file.record[x].down_ctl[81]│This string contains the filename│ │ │ │of the control file to use when │ │ │ │performing a file download. │ │ │ │ │ │ char │protocol_file.record[x].up_cmd[81] │This string contains the command │ │ │ │that should be executed by the │ │ │ │BBS in order to start an upload │ │ │ │using external protocol #x. │ │ │ │ │ │ char │protocol_file.record[x].up_ctl[81] │This string contains the filename│ │ │ │of the control file to use when │ │ │ │performing a file download. │ │ │ │ │ │ char │ ...record[x].up_log_keyword[21] │This is the keyword that the BBS │ │ │ │software should look for in the │ │ │ │log to find an upload. │ │ │ │ │ │ char │ ...record[x].down_log_keyword[21] │This is the keyword that the BBS │ │ │ │software should look for in the │ │ │ │log to find any downloads. │ │ │ │ │ │ char │ ...record[x].desc_word_num │The word number in the logfile │ │ │ │of the transfer description. │ │ │ │ │ │ char │ ...record[x].name_word_num │The word number in the logfile │ │ │ │of the filename. │ │ │ │ │ │ char │protocol_file.filename[80] │This string stores the full path │ │ │ │and filename of the BBS external │ │ │ │protocols configuration. Normally│ │ │ │you should not alter this │ │ │ │variable yourself. │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 82 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_PROTOCOLS() Read the BBS external protocols configuration │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_protocols(void) FORMAT: od_read_protocols(); RETURNS: TRUE if successful FALSE if unable to read configuration DESCRIPTION: This function reads the protocol configuration located in the directory listed in the default_path variable. If the protocl configuration was found, it will be read into the external protocol configuration structure, described above. This function will return a value of TRUE if it was successful in reading the external protocol configuration, or FALSE if it OpenDoors was unable to read the protocol configuration. You should always check the value returned by this function before attempting to access the external protocols structure. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_PROTOCLS() Saves previously loaded external protocols config │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_protocols(void) FORMAT: od_write_protocols(); RETURNS: TRUE if successful FALSE if unable to save configuration DESCRIPTION: This function is used to save the previously loaded external protocols configuration, stored in the external protocols structure (described on the previous pages). The protocols information will be written back to the same file from which it was loaded. This function will return a value of TRUE if it was able to save the external protocol configuration. If it was unable to save the external protocol configuration, or if you call this function without having already read the configuration with od_read_protocols(), then od_write_protocols() will return a value of FALSE. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 83 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ ACCESSING THE NODE ACTIVITY INFORMATION ─┐ └───────────────────────────────────────────┘ On multi-line BBS systems, the node activity ("useron") functions can provide your programs with information such as who is online on each node, what they are doing, and whether or not they are available for "chat". This information could be useful for a wide variety of applications, such as an activity summary program for SysOps (to allow them to see at a glance what is happening on the BBS), a multi-line chat door, or simply adjusting this information to let other nodes know what the user using your program is doing. In order to begin accessing the BBS node activity information, you must first call the od_useron_open() function. When you are finished accessing this information, you must also close the information files by calling the od_useron_close() function. The node activity information is accessed through the user_on structure, which is described in the chart below. At any time, this structure may contain the information about the activity of any single node. To read the node activity information for a particular node, use the od_useron_read() function, and to save any changes made to this information, use the od_useron_write() function. ┌──────┬────────────────── NODE ACTIVITY STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ user_on.name[36] │ This variable stores the name of the user │ │ │ │ currently online on the currently read node.│ │ │ │ (see the od_useron_read() function for more │ │ │ │ information on the currently read node.) │ │ │ │ │ │ char │ user_on.node │ This variable stores the node number of the │ │ │ │ currently read node. If you wish to remove │ │ │ │ a particular node from the node activity │ │ │ │ file, simply read the node, set this │ │ │ │ variable to 0, and then save the node again.│ │ │ │ Otherwise, you should not alter the value of│ │ │ │ this variable. │ │ │ │ │ │ int │ user_on.baud │ This unsigned integer contains the baud rate│ │ │ │ at which the user on the currently read node│ │ │ │ is connected. │ │ │ │ │ │ char │ user_on.location[26] │ This string contains the city from which the│ │ │ │ user on the currently read node is calling │ │ │ │ from. │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 84 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬────────────────── NODE ACTIVITY STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────┼─────────────────────────────────────────────┤ │ char │ user_on.do_not_disturb │ This variable contains a TRUE/FALSE value │ │ │ │ indicating whether the user on the currently│ │ │ │ read node does not which to be disturbed. │ │ │ │ (ie, is not available for chat) │ │ │ │ │ │ char │ user_on.status │ This variable contains a status value, │ │ │ │ indicating what sort of activity the user │ │ │ │ on the currently read node is engaged in. │ │ │ │ This value will be one of the following │ │ │ │ constants, defined in the opendoor.h file: │ │ │ │ │ │ │ │ STATUS_BROWSE - Indicates that the user is│ │ │ │ browsing (ie, in a menu) on the BBS │ │ │ │ │ │ │ │ STATUS_XFER - Indicates that the user is │ │ │ │ currently performing a file transfer. │ │ │ │ │ │ │ │ STATUS_MESSAGE - Indicates that the user │ │ │ │ is writing a message. │ │ │ │ │ │ │ │ STATUS_DOOR - Indicates that the user is │ │ │ │ in a door or external program. │ │ │ │ │ │ │ │ STATUS_CHAT - Indicates that the user is │ │ │ │ currently chatting with the sysop. │ │ │ │ │ │ │ │ STATUS_QUEST - Indicates that the user is │ │ │ │ currently answering a questionaire. │ └──────┴────────────────────────┴─────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 85 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_USERON_OPEN() Opens the node activity file for access │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_useron_open(void) FORMAT: od_useron_open(); RETURNS: TRUE if successful FALSE if unable to open node activity file DESCRIPTION: This function opens the node activity file for access, and must be called prior to calling other od_useron_ functions. The node activity file (USERON.BBS on Apex or RemoteAccess systems), should be able to be located in the directory listed in the default_path variable. This function will return a value of TRUE if it was able to open the node activity file, and will return a value of FALSE if it was unable to open the file. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 86 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_USERON_READ() Reads the node activity info. for specified node │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_useron_read(unsigned char node) FORMAT: od_useron_read(node); RETURNS: TRUE if successful FALSE if unable to locate node activity information DESCRIPTION: This function reads the node activity information for the specified node. This function is simply called with the node number (from 1 - 250 in Apex and Remote Access systems) of the node for which you wish to read the node activity information. If there is a user online on this node, the information will be read into the node activity structure, described above, and a value of TRUE will be returned. If there is no user online on the specified node, or if some error has occurred, then the od_useron_read() function will return a value of FALSE. Thus, you will probably want to check the value returned by this function prior to continuing on in your program. Note that the node activity information file must be opened using the od_useron_open() function before the od_useron_read() function can be used. In order to read the node activity information for every node, simply loop through all of the possible node numbers (ie. 1-99), and checking which nodes exist by the value returned by the od_useron_read() function. For example: #include "opendoor.h" int main(int argc,char *argv[]) { register unsigned char node; if(!od_useron_open()) return(1); for(node=1;node<=99;++node) { if(od_useron_reasd(node)) { cprintf("%s from %s is currently on node %d\n\r", user_on.name, user_on.location, user_on.node); } } od_useron_close(); return(0); } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 87 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_USERON_WRITE() Save the currently read node activity information │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_useron_write(void) FORMAT: od_useron_write(); RETURNS: TRUE if successful FALSE if no node activity information is currently loaded DESCRIPTION: This function saves any changes you have made to the node activity information for the the currently read node back to the useron file. Thus, you may only call this function after having previously succeded in reading the node activity information for a specific node using the od_useron_read() function. The od_useron_write() function will return a value of TRUE if it was able to save the node activity information, or return a FALSE if you have no node activity information is currently loaded. If you wish to remove a certain node from the node activity information file (ie, if the particular node has just gone offline), simply load that node with the od_useron_read() function, set the node number to 0, and write it back to the useron file using the od_useron_write() function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 88 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_USERON_CLOSE() Closes the node activity information file │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_useron_close(void) FORMAT: od_useron_close(); RETURNS: TRUE if successful FALSE if the node activity information file has not been opened DESCRIPTION: This function closes the node activity information file (USERON.BBS on Apex and Remote Access systems) after you have finished accessing the node activity information. This function will return a value of TRUE if it was successfully able to close the node activity information file, and will return a value of FALSE if the useron file has not previously been opened. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 89 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ ACCESSING CALL HISTORY INFORMATION ─┐ └──────────────────────────────────────┘ OpenDoors also gives you full access to the BBS call history files, which provides information such as the total number of calls that the BBS has received, and a list of the calls to the BBS so far today - with information such as when each call started and ended, what user was online, and so on. On Apex, RemoteAccess, QuickBBS and compatible systems, this information is stored in the files SYSINFO.BBS and LASTCALL.BBS. In order to access the BBS call history information, you must first open these files, by simply calling the od_calls_open() function. When you are finished accessing this information, you should then close the BBS call history files using the od_calls_close() function. Each of the individual calls in the call history can then be read by calling the od_calls_read_next() function, and new calls may be added to the history by calling the od_calls_add() function. All of the call history information is accessed through the call_history structure, outlined in the table below: ┌──────┬─────────────────── CALL HISTORY STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ char │ call_history.node │ This variable lists the node │ │ │ │ number that the caller of the │ │ │ │ currently loaded call history │ │ │ │ record was on. │ │ │ │ │ │ char │ call_history.name[36] │ This string contains the name of│ │ │ │ the particular caller. │ │ │ │ │ │ char │ call_history.location[26] │ This string contains the │ │ │ │ location of the particular │ │ │ │ caller from the call history. │ │ │ │ │ │ int │ call_history.baud_rate │ This unsigned integer indicates │ │ │ │ the baud rate at which the │ │ │ │ particular caller was connected │ │ │ │ │ │ long │ call_history.times │ This variable indicates the │ │ │ │ total number of times that the │ │ │ │ user has called the BBS. │ │ │ │ │ │ char │ call_history.logon_time[6] │ This two strings indicate the │ │ char │ call_history.logoff_time[6] │ times at which the call from │ │ │ │ the call history began and │ │ │ │ ended. │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 90 │ └─────────────────────────────────────────────────────────────────────────────┘ The following variables from the call_history function are independant of any particular call history record, and will always contain the same value, regardless of what call history record is loaded into the variables listed on the previous page. (The variables on the previous page are from the LASTCALL.BBS file, and these variables are from the SYSINFO.BBS file) ┌──────┬─────────────────── CALL HISTORY STRUCTURE ───────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼────────────────────────────────────┼─────────────────────────────────┤ │ │ │ │ │ long │ call_history.total_system_calls │ This variable will always │ │ │ │ contain the total number of │ │ │ │ calls that the BBS has received │ │ │ │ │ │ char │ call_history.last_system_caller[36]│ This variable will always │ │ │ │ contain the name of the LAST │ │ │ │ caller to the BBS │ └──────┴────────────────────────────────────┴─────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 91 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CALLS_OPEN() Opens the BBS call history files for access │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_calls_open(void) FORMAT: od_calls_open(); RETURNS: TRUE if successful FALSE if unable to open the BBS call history files DESCRIPTION: This function opens the BBS call history files for access, and must be called prior to calling other od_calls_ functions. The node activity files (LASTCALL.BBS and SYSINFO.BBS on Apex and RemoteAccess systems), should be able to be located in the directory listed in the default_path variable. This function will return a value of TRUE if it was able to open the call history files, and will return a value of FALSE if it was unable to open the files. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 92 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CALLS_READ_NEXT() Reads the next BBS call history record │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_calls_read_next(void) FORMAT: od_calls_read_next(); RETURNS: TRUE if successful FALSE if there are no more call history entries or if the BBS call history file has not been opened DESCRIPTION: This function will read the next BBS call history record from the call history file. This information is stored in the first part of the call_history structure, described above. The od_calls_read_next() function will return a value of TRUE if it was able to read the next record, or FALSE if there are no more records to read. Thus, to read through the BBS call history file, you would simply read each record one at a time by calling the od_calls_read_next() function. For example, the following program will display a list of the user's who have called the BBS today: #include "opendoor.h" int main(int argc,char *argv[]) { od_calls_open(); cprintf("NAME LOCATION BAUD NODE"); cprintf(" CALLS LOGON LOGOFF\n\r"); while(od_calls_read_next()) { cprintf("%-20.20s %-15.15s %6u %-2.2d %-4.4d %s %s\n\r", call_history.name, call_history.location, call_history.baud_rate, call_history.node, call_history.times, call_history.logon_time, call_history.logoff_time); } od_calls_close(); } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 93 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CALLS_ADD() Adds a new BBS call history record to the file │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_calls_add(void) FORMAT: od_calls_add(); RETURNS: TRUE if successful FALSE if unsuccessful DESCRIPTION: This function can be used to add a new call history record to the BBS call history file. Simply set all of the variable in the first part of the call_history structure (described above) to the desired values, and then call this function. This function will automatically increment the total number of calls to the BBS, and set the name of the last caller. Note that the call history files must be opened using the od_calls_open() function prior to using the od_calls_add() function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 94 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CALLS_CLOSE() Closes the BBS call history files │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_calls_close(void) FORMAT: od_calls_close(); RETURNS: TRUE if successful FALSE if the BBS call history files have not been opened DESCRIPTION: This function closes the BBS call history files after you have finished accessing the node activity information. This function will return a value of TRUE if it was successfully able to close the BBS call history files, and will return a value of FALSE if the files are not currently opened. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 95 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ BBS TIMELOG FILE ─┐ └────────────────────┘ Among the BBS system files that OpenDoors gives you access to is the timelog file. This file stores a record of how busy the BBS has been on average at different times of day. This is the same information that is used to construct a system activity graph. This information is stored in a dynamically allocated structure, pointed to by timelog. Below each variable in this structure is listed, along with a brief description of the information stored within it. Since the timelog variable is actually a pointer to the structure, and not the structure itself, remember that you must access elements within it by using the -> operator in C. For example, to print the date on which the timelog begins: puts(timelog->start_date); Below are the individual elements of the timelog structure. Note that before this information can be accessed, you must read it using the od_read_timelog() function, the use of which is described after the chart. ┌──────┬─────────────────── BBS TIMELOG STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼─────────────────────────┼────────────────────────────────────────────┤ │ char │ start_date[9] │ This string contains the date on which the │ │ │ │ timelog begins, in the format MM-DD-YY. │ │ │ │ │ │ int │ busy_per_hour[24] │ This array of unsigned integers lists the │ │ │ │ RELATIVE amount of time for which the BBS │ │ │ │ has been busy, on average, during each of │ │ │ │ the 24 hours of the day. │ │ │ │ │ │ int │ busy_per_day[7] │ This array of unsigned integers lists the │ │ │ │ RELATIVE amount of time for which the BBS │ │ │ │ has been busy, on average, during each of │ │ │ │ the 7 days of the week. │ └──────┴─────────────────────────┴────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 96 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_TIMELOG() Reads the BBS timelog file into the timelog structure │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_timelog(void) FORMAT: od_read_timelog(); RETURNS: TRUE if successful FALSE if unable to read the timelog DESCRIPTION: This function reads the BBS timelog that is located in the directory pointed to by the global variable default_path. od_read_timelog() will automatically detect the type of BBS timelog file present in this directory, and read it into the structure pointed to by timelog. (see above). This structure is dynamically allocated by the od_read_timelog() function. If not enough memory is present to read the timelog, or if no OpenDoors compatible timelog files are found in the directory, this function will return FALSE. If successful, then this function will return TRUE. All variables and data stored in the timelog file are automatically converted to C format for your use. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 97 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ BBS MENU FILES ─┐ └──────────────────┘ OpenDoors also provides you with access to the BBS menu files. This could be usefull in many cases, such as allowing your door programs to use the same menu files used on the rest of the BBS, or in writing your own menu editor. You may also wish to use this function in an installation program to automatically add your door to the BBS'es menu structure. Each menu file will consist of one or more "lines", each of which contains information such as the hot-key, text to display, command to execute, minimum security level, etc. for each command on the menu. The second, third, fourth, ... entries in the menu file are individual "lines" on the menu. However, the entry is not a true line, but instead a special information entry that contains information on the menu prompt. Thus, for the menu: [!] Logoff [/] Return to Main Menu [S] Leave message for sysop Enter your choice: The first entry in the menu file would contain the "Enter your choice:" prompt. The second entry would then contain the information for the "logoff" command, the third the information for the "return to main menu" command, and so on. You may use the OpenDoors function od_read_menu() and od_write_menu() to read and write any menu file. The menu file information is stored in the structure pointed to by the menuentry structure, which is allocated by the od_read_menu() function. This structure is described on the following page. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 98 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────────── MENU FILE STRUCTURE ─────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ char │menuentry->entry[x].type │ This variable contains the menu │ │ │ │ command type (ie, read message, │ │ │ │ change menu, logoff, etc.) of menu │ │ │ │ entry x. Please refer to the BBS │ │ │ │ documentation for complete │ │ │ │ information on each of the menu │ │ │ │ command #'s. (This information is │ │ │ │ beyond the scope of this manual.) │ │ │ │ │ │ int │menuentry->entry[x].security │ This two variables indicate the │ │ char │menuentry->entry[x].flag[4] │ minimum security level and flag │ │ │ │ settings a user must have to access │ │ │ │ menu entry x. │ │ │ │ │ │ char │menuentry->entry[x].display[76]│ This variable contains the text that │ │ │ │ should be displayed for menu entry x.│ │ │ │ If no text is to be displayed for │ │ │ │ this menu entry, then this string │ │ │ │ should simply contain a ';' character│ │ │ │ │ │ char │menuentry->entry[x].hotkey │ This variable contains the key │ │ │ │ (letter, number or symbol) that is │ │ │ │ used to select the particular menu │ │ │ │ command. │ │ │ │ │ │ char │menuentry->entry[x].options[81]│ This string contains special │ │ │ │ information that will be specific │ │ │ │ to each menu command type. For │ │ │ │ example, for the change menu │ │ │ │ command, this string would list the │ │ │ │ name of the menu to change to. │ │ │ │ │ │ char │menuentry->entry[x].foreground │ These two variables indicate the │ │ char │menuentry->entry[x].background │ normal and highlighted colours │ │ │ │ for the particular menu item. │ │ │ │ │ │ char │menuentry->num_entries │ This variable lists the number of │ │ │ │ menu items this particular menu │ │ │ │ actually has. This can be a │ │ │ │ value anywhere from 0-32 entries. │ │ │ │ │ │ char │menuentry->filename[80] │ This variable indicates the path and │ │ │ │ filename of the currently loaded menu│ │ │ │ file. If you wish to re-save the menu│ │ │ │ under a different filename, simply │ │ │ │ change the filename stored in this │ │ │ │ variable. │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ───────────────────────────────────── Page 99 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_MENU() Reads a BBS menu file into the menu file structure │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_menu(char *filename) FORMAT: od_read_menu(filename); RETURNS: TRUE if successful FALSE if unsuccessful DESCRIPTION: The od_read_menu() function will read the contents of a BBS menu file into the menu file structure. The `filename' parameter should list the complete path and filename of the BBS menu files to be loaded. If the od_read_menu() function is successful, it will store the contents of the menu file in the menu file structure, and return a value of TRUE. If the menu file was not found, or if there was not enough memory to read the structure, then this function will return a value of FALSE. ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_MENU Writes the BBS menu file in the menu file structure │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_menu(void) FORMAT: od_write_menu(); RETURNS: TRUE if successful FALSE if unsuccessful DESCRIPTION: This function writes the currently loaded BBS menu file from the menu file structure back to disk. The od_write_menu() function will return a value of TRUE if successful. If no menu file has been loaded, or there is not enough memory to save the menu file structure, the od_write_menu() function will return a value of FALSE. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 100 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ ACCESSING THE BBS USER BASE FILES ─┐ └─────────────────────────────────────┘ OpenDoors provides you with a complete user base engine for reading, altering, adding or removing users for any Apex, QuickBBS, SuperBBS, Remote Access or compatible user base. For systems running Apex or newer versions of Remote Access, the extended information in the USERSXI.BBS file is also made available, as well as all of the information in the USERS.BBS file - all automatically of course. The chart below lists all the variables available in the user record structure. Those variables that contain information from the USERSXI.BBS file will only be available if the user_type variable is equal to USER_RA100, as shown in the chart below. Again, the user record structure is automatically dynamically allocated by OpenDoors, and thus the structure elements are accessed using C's pointer-to-structure-element operator (->). As always, OpenDoors automatically converts all variables between the format in which they are stored and the standard C variable formats for your use. ┌────┬────┬───────────────── USER RECORD VARIABLES ───────────────────────────┐ │EXT.│ │ │ │ │INFO│TYPE│VARIABLE NAME │DESCRIPTION │ ├────┼────┼───────────────────────────────┼───────────────────────────────────┤ │ │char│user_record->name[36] │Name of the currently loaded user │ │ │ │ │ │ │ │char│user_record->location[26] │Location where the user lives │ │ │ │ │ │ │ │char│user_record->password[16] │User's password │ │ │ │ │ │ │ │char│user_record->data_phone[13] │The user's business/data phone │ │ │ │ │number │ │ │ │ │ │ │ │char│user_record->voice_phone[13] │The user's home/voice phone number │ │ │ │ │ │ │ │char│user_record->last_time[6] │String containing the 24-hour │ │ │ │ │format time of the user's last call│ │ │ │ │ │ │ │char│user_record->last_date[9] │String containing the date of the │ │ │ │ │user's last call │ └────┴────┴───────────────────────────────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 101 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────┬────┬───────────────── USER RECORD VARIABLES ───────────────────────────┐ │EXT.│ │ │ │ │INFO│TYPE│VARIABLE NAME │DESCRIPTION │ ├────┼────┼───────────────────────────────┼───────────────────────────────────┤ │ │char│user_record->attrib1 │User's attribute flags. Each bit of│ │ │ │ │this flag stores a seperate piece │ │ │ │ │of information the user or a │ │ │ │ │seperate user setting, as follows: │ │ │ │ │ │ │ │ │ │ ┌─────┬───────────────────────┐ │ │ │ │ │ │ BIT │ DESCRIPTION │ │ │ │ │ │ ├─────┼───────────────────────┤ │ │ │ │ │ │ 0 │ Is the user deleted │ │ │ │ │ │ │ 1 │ Is screen clearing on │ │ │ │ │ │ │ 2 │ Is "more" prompt on │ │ │ │ │ │ │ 3 │ Is ANSI mode on │ │ │ │ │ │ │ 4 │ User no-kill setting │ │ │ │ │ │ │ 5 │ Transfer-priority │ │ │ │ │ │ │ 6 │ Full screen editor │ │ │ │ │ │ │ 7 │ Quiet mode │ │ │ │ │ │ └─────┴───────────────────────┘ │ │ │ │ │ │ │ │char│user_record->flag[4] │The User's A, B, C and D flag │ │ │ │ │settings │ │ │ │ │ │ │ │int │user_record->netmail_credit │The amount of netmail credit that │ │ │ │ │the user has │ │ │ │ │ │ │ │int │user_record->credit_pending │The credit that is pending for user│ │ │ │ │ │ │ │int │user_record->msgs_posted │Total number of messages posted by │ │ │ │ │the user │ │ │ │ │ │ │ │int │user_record->last_read │System message number of the last │ │ │ │ │message read by the user │ │ │ │ │ │ │ │int │user_record->security │Unsigned integer containing the │ │ │ │ │user's security level │ │ │ │ │ │ │ │int │user_record->num_calls │The number of calls the user has │ │ │ │ │placed to the BBS │ │ │ │ │ │ │ │int │user_record->uploads │The number of uploads the user has │ │ │ │ │made │ │ │ │ │ │ │ │int │user_record->downloads │The number of downloads that the │ │ │ │ │user has made │ │ │ │ │ │ │ │int │user_record->upload_k │Total number of KiloBytes uploaded │ │ │ │ │by the user │ │ │ │ │ │ │ │int │user_record->download_k │Total number of KBytes downloaded │ └────┴────┴───────────────────────────────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 102 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────┬────┬───────────────── USER RECORD VARIABLES ───────────────────────────┐ │EXT.│ │ │ │ │INFO│TYPE│VARIABLE NAME │DESCRIPTION │ ├────┼────┼───────────────────────────────┼───────────────────────────────────┤ │ │ │ │ │ │ │int │user_record->today_k │Total K downloaded by the user on │ │ │ │ │the day of their last call │ │ │ │ │ │ │ │int │user_record->elapsed_time │The amount of time that the user │ │ │ │ │used on the day of their last call │ │ │ │ │ │ │ │int │user_record->screen_length │The user's screen length setting │ │ │ │ │ │ │ │char│user_record->last_pwd_change │The number of calls the user has │ │ │ │ │placed to the BBS since their last │ │ │ │ │password change │ │ │ │ │ │ │ │char│user_record->attrib2 │Additional user attribute flags. As│ │ │ │ │with the attrib1 variable, each bit│ │ │ │ │of this flag stores a seperate │ │ │ │ │piece of information the user or a │ │ │ │ │seperate user setting, as follows: │ │ │ │ │ │ │ │ │ │ ┌─────┬───────────────────────┐ │ │ │ │ │ │ BIT │ DESCRIPTION │ │ │ │ │ │ ├─────┼───────────────────────┤ │ │ │ │ │ │ 0 │ User hot-keys setting │ │ │ │ │ │ │ 1 │ Is AVATAR graphics on │ │ │ │ │ │ │ 2 │ Full screen reader │ │ │ │ │ │ │ 3 │ Hidden from userlist │ │ │ │ │ │ └─────┴───────────────────────┘ │ │ │ │ │ │ │ │char│user_record->group │The group number to which the user │ │ │ │ │belongs │ │ │ │ │ │ │Yes │char│user_record->handle[36] │The user's pseudonym, or handle │ │ │ │ │ │ │Yes │char│user_record->comment[81] │A string containing any comments │ │ │ │ │the sysop wants to remember about │ │ │ │ │the user │ │ │ │ │ │ │Yes │char│user_record->first_date[9] │String containing the date of the │ │ │ │ │user's first call │ │ │ │ │ │ │Yes │char│user_record->combined_areas[25]│200 bits corrosponding to each of │ │ │ │ │the 200 message areas - indicating │ │ │ │ │whether or not the user wants each │ │ │ │ │area included in their combined │ │ │ │ │message reading │ │ │ │ │ │ │Yes │char│user_record->birth_date[9] │String containing the date of the │ │ │ │ │user's birthday │ └────┴────┴───────────────────────────────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 103 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌────┬────┬───────────────── USER RECORD VARIABLES ───────────────────────────┐ │EXT.│ │ │ │ │INFO│TYPE│VARIABLE NAME │DESCRIPTION │ ├────┼────┼───────────────────────────────┼───────────────────────────────────┤ │ │ │ │ │ │Yes │char│user_record->expiry_date[9] │String containing the date that the│ │ │ │ │user's account will expire │ │ │ │ │ │ │Yes │char│user_record->screen_width │Width of the user's terminal screen│ │ │ │ │ │ │ │char│user_type │This variable indicates the type │ │ │ │ │of user file that has been opened. │ │ │ │ │This value will be one of two │ │ │ │ │constants defined in the opendoor.h│ │ │ │ │file: │ │ │ │ │ │ │ │ │ │USER_RA100 - Indicates that the │ │ │ │ │ extended information in a │ │ │ │ │ USERSXI.BBS file is available. │ │ │ │ │ When this information is │ │ │ │ │ available, those entries in the │ │ │ │ │ user record with a "YES" in the │ │ │ │ │ `Ext. Info' column may be used │ │ │ │ │ │ │ │ │ │USER_RA_QBBS - Indicates that no │ │ │ │ │ extended information from a │ │ │ │ │ USERSXI.BBS file is available. │ │ │ │ │ When this information is not │ │ │ │ │ available, those entries in the │ │ │ │ │ user record with a "YES" in the │ │ │ │ │ `Ext. Info' column may not be │ │ │ │ │ used │ │ │ │ │ │ │ │ │ │(notice that this variable is not │ │ │ │ │ a member of the user_record │ │ │ │ │ structure) │ │ │ │ │ │ │ │int │num_users │This variable indicates the total │ │ │ │ │number of users present in the │ │ │ │ │currently opened user record file │ │ │ │ │ │ │ │int │user_number │This variable indicates the user │ │ │ │ │number of the user record that is │ │ │ │ │currently loaded. If no user record│ │ │ │ │is currently loaded, then this │ │ │ │ │value will be equal to -1. │ └────┴────┴───────────────────────────────┴───────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 104 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_OPEN_USERS() Opens the users file for manipulation │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_open_users(char *path) FORMAT: od_open_users(path); RETURNS: TRUE if successful FALSE if unable to open users file, or if not enough memory is present DESCRIPTION: The od_open_users() function is used to open the users, and must be called before any of the other user file manipulation functions may be called. The od_open_users() function will automatically attempt to allocate memory for the user record storage. If there is not enough memory available to store this user record, the user base will not be opened, and this function will return a FALSE. You must pass to the od_open_users() function a string indicating the directory where the users file is stored. If you are writing a program that uses the users file, as well as other BBS configuration, it would probably be a good idea to get the path to the users file from the BBS configuration. For example: strcpy(default_path,""); od_read_config(); od_open_users(cfg->msg_base_path); Once the user file has been successfully opened (ie, if this function returns a TRUE value), you will be able to determine the number of users on the BBS using the num_users variable. You will also be able to use all of the user base manipulation functions (listed below). Once you are finished working with the user file, you should close it using the od_close_users() function, as described below. If a USERSXI.BBS file exists in this directectory, it will also be opened, and the extended user information will automatically be made available to you by the other user base manipulation functions. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 105 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_READ_USER() Reads a user record from the opened user base │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_read_user(int num) FORMAT: od_read_user(num) or od_read_user(-1) RETURNS: TRUE if successful FALSE if unable to read user, if the user file has not been opened, or if the end of the user file has been reached DESCRIPTION: The od_read_user() function is used to read a user from the users file. You can randomly read any user from the user file, by passing a number from 0 to num_users-1 to the od_read_user function. Alternatively, you can read the next user from the file, by passing a value of -1 to this function. When the user file is first opened, the record pointer will be set to the first record, so you can read all records from the user file in sequence by simply always passing a value of -1 to the od_read_user() function. For example: // program to print every user's name, along with the // date of their account expiry od_open_users(""); // open user file printf("DATE NAME\n"); // print titles while(od_read_user(-1)) // while users left printf("%s %s\n",user_record->expiry_date, user_record->name); // print user info od_close_users(); // close user file Note that the users file must be opened prior to using the od_read_user() function. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 106 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_WRITE_USER() Writes the currently read user back to user base │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_write_user(void) FORMAT: od_write_user(); RETURNS: TRUE if successful FALSE if unable to write user, if the user file has not been opened, or if no user is currently loaded DESCRIPTION: The od_write_user() function is used to write a user back to the user file after the record has been read. If no user record is currently loaded, then this function will return with an error. As always, this function will automatically convert your variables from their C format to the format in which they are stored in the file. If the extended information from a USERSXI.BBS file is present, then the changed record will also be saved in the USERSXI.BBS file, automatically. Thus, an example of use of the od_write_user() function would be: // program to give any user with 5 or more uploads // a security level of 50. (This could be used to // only give users download priviledges after they // have uploaded 5 times) od_open_users(""); while(od_read_user(-1)) if(user_record->uploads >= 5 && user_record->security < 50) { user_record->security=50; od_write_user(); } od_close_users(); If you wish to delete a user from the user file, simply read their record, set their deleted bit (see the user record structure), and then write the user to the user file. The user will then be removed the next time the sysop's user base packing utility is run. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 107 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_ADD_USER() Adds a new user to the user file │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_add_user(void) FORMAT: od_add_user(); RETURNS: TRUE if successful FALSE if unable to write user, or if the user file has not been opened DESCRIPTION: The od_add_user() function is used to add a new user to the currently opened user file. To create a new user, simply set all of the variables in the user record structure (those entries that begin with user_record->) to the value they should have for the new user, and then call the od_add_user() function. The currently loaded user will then become this new user - the last user in the file. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 108 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_CLOSE_USERS() Closes the currently opened user file │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_close_users(void) FORMAT: od_close_users(); RETURNS: TRUE if successful FALSE if unsuccessful DESCRIPTION: The od_close_users() function should be used to close the currently loaded user file after all processing with that file has been completed. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 109 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ THE MESSAGE BASE MANIPULATION ROUTINES ─┐ └──────────────────────────────────────────┘ The OpenDoors message base engine, which currently supports the Hudson message base format used by many popular BBS packages such as Apex, RemoteAccess, QuickBBS, SuperBBS and others. Future vesions will be expanded to support other message base formats as well, so that your programs need only be recompiled to automatically gain support for other BBSes, such as PC-Board, Maximus, etc. Use of the message base can be very helpfull in many doors and utilties - either to allow users to post messages to other users or the sysop, or to allow the utility to send it's own messages to users. These message base routines also support the RemoteAccess 1.01 Hudson Message Base Locking Specifications, which allow various utilities, multiple BBS nodes, etc. to all access the message base at the same time. If you wish to disable the use of RA 1.01 locking, simply set the global variable ra_101_locking to FALSE. To access the message base, simply open the message base using the od_msg_open() function. When you are finished accessing the message base, simply close it again using the od_msg_close() function. OpenDoors currently requires access to the BBS configuration in order to determine information such as message area types and the location of the message base. Thus, if the configuration strucuture has not already been created (as it is by the od_read_config() fuction), OpenDoors will attempt to read the configruation from the directory listed in the default_path global variable. Once the message base has been opened, you can access information about the message base, such as the total number of messages, etc., through the msg_info structure. While accessing the message base, message header information can be accessed through the message header structure, pointed to by the msg_hdr. This message header contains information on the message you are currently working with, such as who the message is from, who it is addressed to, etc. Both of these structures are documented on the following pages. Following this, you will find references for each of the message base engine functions. Refer carefully to these references for information on performing various functions with the message base, such as reading messages, posting new messages, and so on. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 110 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬─────────── MESSAGE BASE INFORMATION STRUCTURE ───────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ int │ msg_info->first_msg │ Unsigned integer listing the number │ │ │ │ of the first message in the message │ │ │ │ base │ │ │ │ │ │ int │ msg_info->last_msg │ Unsigned integer listing the number │ │ │ │ of the last message in the message │ │ │ │ base │ │ │ │ │ │ int │ msg_info->total_msgs │ Unsigned integer listing the total │ │ │ │ number of messages in the message │ │ │ │ base │ │ │ │ │ │ int │ msg_info->total_on_board[200] │ Unsigned integer listing the total │ │ │ │ number of messages on each of the │ │ │ │ message "boards" │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌──────┬──────────────── MESSAGE HEADER STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ int │ msg_hdr->message_number │ Unsigned integer listing the message │ │ │ │ number of the message that we are │ │ │ │ currently working with. You should │ │ │ │ not change this value. │ │ │ │ │ │ int │ msg_hdr->previous_reply │ Unsigned integer listing the message │ │ │ │ number of the previous message in │ │ │ │ the "reply chain". │ │ │ │ │ │ int │ msg_hdr->next_reply │ Unsigned integer listing the message │ │ │ │ number of the next message in the │ │ │ │ "reply chain". │ │ │ │ │ │ int │ msg_hdr->times_read │ Unsigned integer inidcating the │ │ │ │ number of times this message has been│ │ │ │ read. (Not normally used) │ │ │ │ │ │ int │ msg_hdr->start_block │ Block number of the first block of │ │ │ │ the message text. You should not │ │ │ │ alter this value. │ │ │ │ │ │ int │ msg_hdr->num_blocks │ Number of blocks in the message text.│ │ │ │ Again, you should not alter this │ │ │ │ value. │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 111 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────── MESSAGE HEADER STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ int │ msg_hdr->dest_net │ For netmail messages, these variables│ │ int │ msg_hdr->dest_node │ will list the origin and destination │ │ int │ msg_hdr->origin_net │ node addresses of the message │ │ int │ msg_hdr->origin_node │ │ │ char │ msg_hdr->dest_zone │ │ │ char │ msg_hdr->origin_zone │ │ │ │ │ │ │ int │ msg_hdr->cost │ Unsigned int indicating the estimated│ │ │ │ cost of sending this netmail message.│ │ │ │ │ │ char │ msg_hdr->msg_attr │ Attribute bits for this message. Each│ │ │ │ bit is represented by a seperate │ │ │ │ constant, defined in the opendoor.h │ │ │ │ file. These bits are as follows: │ │ │ │ │ │ │ │ MSG_DELETED - If set, indicates that│ │ │ │ the message has been deleted, and│ │ │ │ should never be displayed to the │ │ │ │ user. Deleted messages will later│ │ │ │ be removed from the message base │ │ │ │ when the sysop runs a message │ │ │ │ base packing utility. │ │ │ │ │ │ │ │ MSG_OUTGOING_NET - If set, indicates│ │ │ │ that this message is a netmail │ │ │ │ message that has not yet been │ │ │ │ exported from the message base. │ │ │ │ │ │ │ │ MSG_NETMAIL - If set, indicates that│ │ │ │ this is a netmail message. │ │ │ │ │ │ │ │ MSG_PRIVATE - If set, indicates that│ │ │ │ the message is private, and │ │ │ │ should only be read by the sysop,│ │ │ │ the person who posted the │ │ │ │ message, and the person to whom │ │ │ │ the message is addressed. │ │ │ │ │ │ │ │ MSG_RECEIVED - If set, indicates tha│ │ │ │ the person to whom the message is│ │ │ │ addressed has read (received) it.│ │ │ │ │ │ │ │ MSG_OUTGOING_ECHO - If set, indicate│ │ │ │ that the message is an echomail │ │ │ │ message that has not yet been │ │ │ │ sent. │ │ │ │ │ │ │ │ MSG_LOCAL - If set, indicates that │ │ │ │ this is a local message. │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 112 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────── MESSAGE HEADER STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ char │ msg_hdr->net_attr │ Netmail bits for this message. Each │ │ │ │ bit is represented by a seperate │ │ │ │ constant, defined in the opendoor.h │ │ │ │ file. These bits (except for the │ │ │ │ file attach bit), will usually only │ │ │ │ be used for netmail messages. These │ │ │ │ bits are as follows: │ │ │ │ │ │ │ │ NET_KILL_SENT - If this bit is set, │ │ │ │ it indicates that the message │ │ │ │ should be deleted after it has │ │ │ │ been sent (exported from the │ │ │ │ message base). │ │ │ │ │ │ │ │ NET_SENT - Indicates that the │ │ │ │ message has been sent. │ │ │ │ │ │ │ │ NET_FILE_ATTACH - Indicates that │ │ │ │ there are files attached to this │ │ │ │ message. │ │ │ │ │ │ │ │ NET_CRASH - Indicates that the │ │ │ │ netmail message should be sent │ │ │ │ with "Crash" priority. │ │ │ │ │ │ │ │ NET_REQ_RECEIPT - Indicates a │ │ │ │ request for a message received │ │ │ │ receipt. │ │ │ │ │ │ │ │ NET_REQ_AUDIT - Indicates a request │ │ │ │ for an audit. │ │ │ │ │ │ │ │ NET_RETURN_RECEIPT - Indicates that │ │ │ │ this message is a return receipt.│ │ │ │ │ │ char │ msg_hdr->board │ Unsigned integer from 0 to 199, │ │ │ │ indicating the message board number │ │ │ │ that this message is located in. Do │ │ │ │ not change this value. │ │ │ │ │ │ char │ msg_hdr->time[6] │ String listing the time at which the │ │ │ │ message was created. │ │ │ │ │ │ char │ msg_hdr->date[9] │ String listing the date on which the │ │ │ │ message was created. │ │ │ │ │ │ char │ msg_hdr->who_to[36] │ String listing the user name to which│ │ │ │ the message is addressed. │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 113 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────┬──────────────── MESSAGE HEADER STRUCTURE ────────────────────────────┐ │ TYPE │ VARIABLE NAME │ DESCRIPTION │ ├──────┼───────────────────────────────┼──────────────────────────────────────┤ │ char │ msg_hdr->who_from[36] │ String listing the user name from │ │ │ │ whom the message was sent. │ │ │ │ │ │ char │ msg_hdr->subject[73] │ String indicating the subject of │ │ │ │ this message. │ └──────┴───────────────────────────────┴──────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 114 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_OPEN() Opens the message base for access │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_open(void) FORMAT: od_msg_open(); RETURNS: TRUE if successful FALSE if unable to open message base, if configuration was not available, or if not enough memory was available DESCRIPTION: The od_msg_open() function allocates memory for the OpenDoors message base engine and opens the message base for access, and must be called prior to using any of the message base manipulation routines. The od_msg_open() function will also setup and read data into the message base information structure, as described above. If the od_msg_open() function returns a TRUE value, then the message base is ready for access, and you are free to call any of the other message base manipulation functions. Once you are finished with the message base, you should close the message base files, using the od_msg_close() function. The OpenDoors message base engine also requires that the main BBS configuration and BBS message area configuration be available. If this information has not already been read when the message base is opened, OpenDoors will attempt to read the configuration from the directory listed in the default_path global variable. Following is an example of a program that uses the message base information read by the od_msg_open() function: // program to display the total # of messages in each area #include "opendoor.h" int main(int argc,char *argv[]) { unsigned char counter; if(!od_msg_open()) return(1); printf("# MSGS MESSAGE AREA\n"); for(counter=0;counter<200;++counter) { if(strlen(message_info->area[counter].name)==0) { printf("%-5d %s\n", msg_info->total_on_board[counter], message_info->area[counter].name); } } } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 115 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_POST() Writes (posts) a new message to the message base │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_post(char *text) FORMAT: od_msg_post(text); RETURNS: TRUE if successful FALSE if unable to write message, or if message base has not been opened DESCRIPTION: The od_msg_post() function is used to post a new message in the message base. This could either be a message written by a user to another person, or a "robot" message from your program to one or more users. In order to post a message, you must first set some of the variables in the message header structure to the values they should have for this message, then call the od_msg_post() function, passing to it the text of your message. If the message is an echomail message, OpenDoors will automatically add tearline and origin line information (as configured in the message area configuration) for you. The entries in the header structure that you must set prior to calling the od_msg_post function are: msg_hdr->board msg_hdr->who_to[36] msg_hdr->who_from[36] msg_hdr->subject[73] msg_hdr->msg_attr msg_hdr->previous_reply msg_hdr->next_reply Also, if you are posting a message in a netmail area, you should set the following variables: msg_hdr->dest_net msg_hdr->dest_node msg_hdr->origin_net msg_hdr->origin_node msg_hdr->dest_zone msg_hdr->origin_zone msg_hdr->cost msg_hdr->net_attr On the following page is an example of a program that makes use of the od_msg_post() function. *IMPORTANT* Remember that lines in message are always seperated with the carriage return character ('\r'), not the linefeed character ('\n')! ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 116 │ └─────────────────────────────────────────────────────────────────────────────┘ Here is an example of a program that makes use of the od_msg_post() function. This program simply posts a message wishing happy birthday to any user who's birthday is today: #include "opendoor.h" // include header file #include <time.h> #include <string.h> int main(int argc,char *argv[]) { time_t timer; struct tm *tblock; char today[6]; strcpy(default_path,""); // set default path od_read_config(); // read configuration // open user base if(!od_open_users(cfg->msg_base_path)) return(1); if(!od_msg_open()) return(1); // open message base timer=time(NULL); // get today's date tblock=localtime(&timer); sprintf(today,"%02.2d-%02.2d",tblock->tm_mon+1, tblock->tm_mday); while(od_read_user(-1)) // loop through every user { if(strncmp(today,user_record->birth_date,5)==0) { // post message to user msg_hdr->board=0; // set message header info strcpy(msg_hdr->who_to,user_record->name); strcpy(msg_hdr->who_from,"OpenDoors"); strcpy(msg_hdr->subject,"Happy Birthday!"); msg_hdr->msg_attr=MSG_PRIVATE; msg_hdr->previous_reply=0; msg_hdr->next_reply=0; // send message od_msg_post("Happy Birthday to you!\n"); } } od_close_users(); // close files od_msg_close(); } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 117 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_READ_HDR() Reads the message header of the specified message │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_read_hdr(unsigned int num) FORMAT: od_msg_read_hdr(num); RETURNS: TRUE if successful FALSE if unable to read header, if invalid message number, or if message base has not been opened DESCRIPTION: The od_msg_read_hdr() function is used to read the header information for a message from the message base. This information will then be available through the message header structure, described above. Note that the message base must be opened, using the od_msg_open() function, prior to calling the od_msg_read_hdr() function. The od_msg_read_hdr() can be called in one of two modes. The first mode allows you to randomly read the header of any message in the message base, and the second allows you to instantly read the next message header. To randomly read any message header from the message base, simply call the od_msg_read_hdr() function, passing to it the message number of the header you wish to read. For example, to display the subject of the first message on the system, simply: od_msg_read_hdr(msg_info->first_msg); puts(msg_hdr->subject); Alternatively, you may wish to simply read the next header from the message base. Using this mode will be faster than requiring OpenDoors to search the message header file in order to find the particular message number you asked for. To cause the od_msg_read_hdr() function to read the header of the next message in the message base, simply pass to it the constand NEXT_MESSAGE (defined in the opendoor.h header file.) For example to read all message to the end of the message base, you could: while(od_msg_read_hdr(NEXT_MESSAGE)) { printf("From: %s To: %s Re: %s\n", msg_hdr->who_from, msg_hdr->who_to, msg_hdr->subject); } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 118 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_READ_TEXT() Reads the text of a particular message │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_read_text(char *text,unsigned int max_len) FORMAT: od_msg_read_text(text,max_len); RETURNS: TRUE if successful FALSE if unable to read message, if invalid message number, or if message base has not been opened DESCRIPTION: The od_msg_read_text() function is used to read the actual text of a message in the message base. In order to read the text of a message, you must first call the od_msg_read_hdr() function for the desired message number. Then, you simply call the od_msg_read_text() function, passing to it a pointer to a buffer to hold the message, along with the maximum length of the buffer. Note that the message base must be opened, using the od_msg_open() function, prior to calling the od_msg_read_text() function. For example, to load the text of the first message on the system, simply: #define MAX_MSG_LEN 20000 ... char message[MAX_MSG_LEN]; od_msg_read_hdr(msg_info->first_msg); od_msg_read_text((char *)&message,MAX_MSG_LEN); Note that messages are always stored with carriage returns (\r) between lines, but no line feeds (\n). Thus, to display a message that you have read, you might do something like: od_msg_read_hdr(NEXT_MESSAGE); od_msg_read_text((char *)&message,MAX_MSG_LEN); text=(char *)&buffer; while(*text) { if(*text=='\r') { cputs("\n\r"); } else { putch(*text); } text++; } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 119 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_CHANGE_HDR() Saves changes to currenlty loaded message header │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_change_hdr(void) FORMAT: od_msg_change_hdr(); RETURNS: TRUE if successful FALSE if unable to write header, if no header has been read, or if message base has not been opened DESCRIPTION: The od_msg_change_hdr() function can be used to allow you to make changes to the header of a message that already exists. Two important reasons for doing this would be to set the received bit on a message after it has been read, and to set the deleted bit on a message, in order to delete it. The od_msg_change_hdr() function will save the currently loaded message header. Thus, in order to change a message header, you must first read the header with the od_msg_read_hdr() function. Then make any changes you wish to make to the message header, and save it back to the message base using the od_msg_change_hdr() function. This function will return a value of TRUE if it was able to save the changed message header, and FALSE if it was unable to make these changes. Common causes of od_msg_change_hdr() being unable to save the new message header are either that the message header has not been previously read, or that the message base has not been opened. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 120 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────────┐ │OD_MSG_CLOSE() Closes the message base files after access │ └─────────────────────────────────────────────────────────────────────────┘ PROTOTYPE: int od_msg_close(void) FORMAT: od_msg_close(); RETURNS: TRUE if successful FALSE if message base has not been opened DESCRIPTION: The od_msg_close() function is simply used to close the message base files and shutdown the OpenDoors message base engine. Always be sure to call the od_msg_close() function when you are finished accessing the message base. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 121 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ TROUBLESHOOTING COMMON PROBLEMS ─┐ └───────────────────────────────────┘ If you are experiencing difficulty programming with OpenDoors, I would encourage you to try following these steps to solve your problem: 1.) Re-read the section(s) of this manual, your Turbo C manuals and your program itself that apply to the problem you are experiencing. 2.) Check the solutions to common problems section below, to see if your specific problem is dealt with. 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 below 4.) If you are still stuck, please feel more than free to get in touch with me! (see the end of the manual for information on reaching me) I am always more than happy to help anyone with their OpenDoors problems! ┌─ THE OD_ERRNO VARIABLE ─┐ └─────────────────────────┘ To assist in the debugging of programs written with OpenDoors, the BBS system file functions (including configuration files, message files, user files, etc.) use the od_errno global variable. When any of these functions are unable to perform their function, and return a value of FALSE, the od_errno variable will indicate the nature of the error that has occured. The od_errno variable will use the same values as are used by Turbo C's errno variable, and are listed on the following page. For example, you could use the following piece of code to test for a lack of available memory: if(errno==ENOMEM) { printf("The last error to occur was as a result of lack of memory!\n"); } ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 122 │ └─────────────────────────────────────────────────────────────────────────────┘ VALUES OF OD_ERRNO VARIABLE od_errno MEANING ────────────────────────────────────────────────────────────────────── EZERO Error Zero EINVFNC An attempt was made to call an invalid function number ENOFILE OpenDoors was unable to find the specified file ENOPATH OpenDoors was unable to find the specified path ECONTR Indicates that internal memory blocks have been corrupted EINVMEM An attempt was made to access and invalid memory block EINVENV Indicates that the environment has been corrupted EINVFMT An invalid format was used in calling OpenDoors functions. For example, you tried to write a user record back to the file which has not been previously read. EINVACC Indicates an invalid access code has been used EINVDAT Indicates that data was found to be invalid. Often, this will indicate that a file on the disk has been damaged. EINVDRV Indicates that a specified disk drive does not exist ENMFILE Inidcates that the end of a file has been reached, or that whatever was being searched for could not be found. ENOENT Indicates that specified file or directory does not exist EMFILE Indicates that there are not enough file handles available. The user should increase the FILES= setting in their CONFIG.SYS file. EACCES Unable to access a particual file, probably because it is already in use by another program. EBADF Bad file number. This error will often occur as a result of attempting to access a file that has not been opened. ENOMEM Indicates that not enough memory is available. Try using a larger memory model, and freeing memory used by other programs. ENODEV An attempt was made to access a device that doesn't exist. ERANGE A value was found to be out of range. This can occur when you try to use a pathname/filename that is too long, or if you are attempting to read a user number beyond the end of the user file. EEXIST An attempt was made to create a file that already exists. EFAULT Another unspecified error has occured. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 123 │ └─────────────────────────────────────────────────────────────────────────────┘ ─────────────────────────────────────────────────────────────────────────────── COMMON PROBLEM SOLUTION ─────────────────────────────────────────────────────────────────────────────── Program Won't Compile 1.) Check that the compiler is able to locate the OpenDoors header file, "OPENDOOR.H". This can be accompilshed either by 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 RAVOTE.C) and the library file are listed in your project file, and that the project file is loaded. (For help with project files, please refer to your Turbo C manuals) 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. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 124 │ └─────────────────────────────────────────────────────────────────────────────┘ ─────────────────────────────────────────────────────────────────────────────── COMMON PROBLEM SOLUTION ─────────────────────────────────────────────────────────────────────────────── Screen Will Not Clear 1.) If you are using the od_clr_scr() function to clear the screen, but are not getting any results, this is likely because the user 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_emulate(12); The sysop's "Shell to 1.) If you press the Alt-J function key, but DOS" function key does do not get any results, your problem is not work likely as a result of lack of memory. If enough memory is not available to load the command processor (usually COMMAND.COM) when the Alt-J function key is pressed, OpenDoors will automatically return to the door. Get a "Fixup Overflow" 1.) This problem was probably caused by a error when linking mismatch between your memory model selection in your compiler, and the memory model 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. Difficulty compiling 1.) The OpenDoors built-in terminal emulation doors that use OpenDoors routines, od_emulate() and od_send_file() terminal emulation under require Turbo C++ or Borland C++ in order old versions of Turbo C to be compiled into your programs. You may, however, "trick" the old versions of Turbo C into compiling your door, by creating a global variable, _wscroll. Simply place the line: int _wscroll; at the beginning of your source code file. You will now be able to compile your program and use these function under old versions of Turbo C, however a few of the AVATAR-specific control codes will not always function correctly. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 125 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ OPENDOORS HISTORY ─┐ └─────────────────────┘ This section of the manual is a brief history of the additions and enhancments that OpenDoors has gone through to get to where it is today. OpenDoors is constantly being improved and upgraded, and almost all of the changes are made in response to requests by current users of OpenDoors. In fact, almost every reasonable request to date has been implemented in the current version of OpenDoors. (If you are a registered user of OpenDoors, do you notice where some of your own suggestions have been implemented?) If you are upgrading from a previous version of OpenDoors, this history list will also help you to identify what new features are available in this version. Version 1.00 - Initial beta test version of the OpenDoors doordriver. Proved to be very bug-free. Version 1.10 - Many features have been improved upon and added since version 1.00. Version 1.20 - Made several changes: ■ Support for the new RemoteAccess 1.00 enhanced exitinfo.bbs file, with many extra pieces of information. ■ Added a Alt-K function key to allow the sysop to temporarily disable the user's keyboard ■ Added full support for turning on and off status line. Status line has been changed slightly in format, and [F9] help function key added. ■ Improved sysop chat mode (added multi-colour and wordwrap) ■ Fixed up shell-to-DOS to automatically shell to the command processor specified in COMSPEC instead of always using COMMAND.COM. OpenDoors now also returns to system to the drive and directory it was in before DOS shell was issued. ■ Added support for the new RemoteAccess sysop next key. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 126 │ └─────────────────────────────────────────────────────────────────────────────┘ Version 1.30 - A few quick changes to perfect all the features of this version before beginning major development work on OpenDoors 2.00. Fixed two problems: ■ The status line can no longer be turned back on by the sysop using F1 - F9 keys, if your door has turned it off to put it's own on instead. ■ A rather major problem was fixed for use of OpenDoors in conjunction with RA 1.00. We accidentally forgot to save some of the data that is unused in previous versions, but has now been implemented in the new version. This bug caused some very obscure bugs, such as the USERSXI.BBS file being fried. All fixed now. Version 1.40 - Another maintenance release. This version should now function perfectly when used in conjunction with older versions of Turbo C. Other changes in this version include: ■ Better error recovery in the case that something on the BBS has been screwed up. ■ More customability of OpenDoors, including allowing the user (programmer) to alter the various OpenDoors messages, and provisions for user defined function keys for the sysop. (ie, you could make Alt-Y another hotkey for the sysop) Version 2.00 - Yet another release, prior to the next major upgrades, some new features have been implemented including: ■ Added support for AVATAR graphics. OpenDoors will automatically detect the presence of AVATAR graphics mode when running under Remote Access, and will allow your door to toggle it when running under other BBS systems. ■ Improved ANSI routines. Added some new functions, and changed existing functions to send shorter ANSI codes in some cicumstances. ■ The "Sysop Next" key should now work correctly with RA 1.00 and later. Version 2.10 - Changes in this version include: ■ Implementation of a registration key-code for ease of upgrading to registered versions. ■ Added an od_printf() function for ease of formatted output from within OpenDoors. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 127 │ └─────────────────────────────────────────────────────────────────────────────┘ Version 2.20 - More improvments, including: ■ Fixing of some minor bugs, such as incorrect handling of the path to DORINFO1.DEF/EXITINFO.BBS files. ■ Added support for more customability, such as hooks for functions that will be called before and after Shell to DOS and sysop chat. ■ OpenDoors is now DesqView aware. OpenDoors will automatically detect the presence of DesqView, and uses the DesqView `virtual screen buffer' for screen display if present. ■ A QuickBBS 2.75 compatibility problem has also been fixed. Version 2.30 - Fixed a small bug in the registration system. Version 3.00 - A MAJOR upgrade, released as a beta-test version, including the following additions/changes: ■ Debuged, Debuged and debuged some more! ■ Added support for door information files from: WWIV, PC-Board, Spitfire, WildCat, GAP, TriTel and others. ■ Added .ASC/.ANS/.AVT file display support with automatic interpretation of QBBS/SuperBBS/RA control characters. ■ Added ALT-D key to drop the user back to the BBS without hanging up. ■ Added direct access to RA style configuration, file area, message area, external protocols, event configuration, caller history, users online, menu files, user base and other system files. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 128 │ └─────────────────────────────────────────────────────────────────────────────┘ ■ Added complete set of message base manipulation routines, with full support for the RA 1.01 message base locking scheme. ■ The user manual has also been re-worked to (hopefully) make it easier to work with. Version 3.10 - The following bug fixes and changes have been made since since the release of version 3.00: ■ Time fields in messages are now correctly formatted ■ Corrected a bug in the od_set_attrib function where the intensity setting would not correctly be transmitted to the remote when using ANSI graphics. ■ Fixed a bug in the re-writing of the DORINFO1.DEF which cause sysop and user's last names to be corrupted. ■ Registered users may now disable the display of copyright and registration information when the door starts up. Version 3.20 - A few more changes and bug fixes were made since version 3.10: ■ Fixed the FILES.BBS lister to correctly support FILES.BBS files located in directories other than the default dir, and added page pausing to the FILES.BBS lister. Version 3.30 - The following changes and bug fixes were made since version 3.20: ■ OpenDoors no longer re-writes the DORINFO1.DEF upon exiting. No BBS's are known to actually make use of the information changed in DORINFO1.DEF, and re-writing this file was causing more troubles than it was worth. ■ The od_msg_read_hdr() function's NEXT_MESSAGE command now works correctly. ■ Added an od_errno variable to assist in debugging of programs written with the BBS file engine portion of OpenDoors. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 129 │ └─────────────────────────────────────────────────────────────────────────────┘ Version 3.40 - A minor upgrade version, with the following changes: ■ Fixed a compatibility problem with locked baud rates. Now, if OpenDoors receives a baud rate the door information file that is not supported in the FOSSIL definitions, it will continue without setting the baud rate. (Whereas before, OpenDoors would report an error and exit.) ■ Made some changes to the manual, and included a utility to remove the extended-ASCII characters from the manual to ease printing on some printers. ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 130 │ └─────────────────────────────────────────────────────────────────────────────┘ ┌─ CLOSING WORDS ─┐ └─────────────────┘ While OpenDoors by no means handles every aspect of door and BBS utility programming, I'm sure you'll find that it will allow you to get into programming your own doors and utilities easier than ever before! As you have seen, OpenDoors handles everything for you, and (in my honest opinion), does a lot better job than many other similar products (most of which cost $50, $75, or even more). But, what you see here is by no means the final version of OpenDoors! We're constantly building on it, and I can guarantee you what you see in the next release will be even more impressive than this! Do keep in mind, though, that we will be upping the price for future versions, so now is the time to register! Here are some of the things we have up planned for future releases: ■ A Windows version of OpenDoors, which will permit easier creation of doors for windows-specific BBS systems, such as Apex. Of course, all registered users of the DOS version of OpenDoors will also be registered for the Windows version. ■ Addition of some of the new Remote Access features, such as sysop page overriding, etc. ■ Direct interfacing with many more BBS formats for configuration & message files. ■ Built in file-transfer protocols. ■ Support for other BBS systems. ■ Stomp any of the bugs that may still exist. This product has already been very extesively tested, but there are always things we don't know about. ■ Lots and lots more! ┌─────────────────────────────────────────────────────────────────────────────┐ │ OpenDoors Programmer's Manual ──────────────────────────────────── Page 131 │ └─────────────────────────────────────────────────────────────────────────────┘ However, what exactly the new version looks like will depend a lot on what people want. If you have any questions, comments, or suggestions, please feel more to free to contact me at 1:243/1.8 in FidoNet. Also, if there are any BBS systems or file formats that you would like to see supported in future versions, for which you have the technical specifications, send them along and I'll see what I can do! If you are having difficulty getting in touch with me, feel free to contact Jake Wadland on his BBS at 1-705-749-6110 (1:229/326 in FidoNet). I would also like to take this chance to thank everyone who has registered OpenDoors, given me encouragment to continue developing this package, and everyone who has helped with suggestions and bug-reports. Special thanks to all users who have made suggestions and to Robert La Ferte for his help in beta testing, and putting up with me! Thank-you, and don't forget to register your copy of OpenDoors today!