home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Shareware 1 2 the Maxx
/
sw_1.zip
/
sw_1
/
PROGRAM
/
ODOORS34.ZIP
/
OPENDOOR.DOC
< prev
next >
Wrap
Text File
|
1992-05-07
|
358KB
|
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!