home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #1
/
monster.zip
/
monster
/
TRIBBS
/
TBAPI501.ZIP
/
TBAPI.DOC
< prev
next >
Wrap
Text File
|
1994-01-04
|
101KB
|
2,839 lines
THE TRIBBS (R) API
VERSION 5.01
COPYRIGHT (C) 1994 BY TRISOFT
COPYRIGHT NOTICE
The TriBBS API is distributed as freeware. It may be used by
programmers to write doors and utilities that are compatible with the
TriBBS Bulletin Board System. All other use is strictly forbidden.
To keep TriBBS a relatively low cost system for the sysop to run, you
may NOT charge more than $25 a copy for any software that is developed
using the TriBBS API without the express written permission of
TriSoft.
Additionally, you must mention in the documentation for any software
that you develop using the TriBBS API that the program uses the TriBBS
API.
WARRANTY
The TriBBS API is distributed without warranty. In no event will
TriSoft be liable to you for damages, including any loss of profits,
lost savings, or other incidental or consequential damages arising out
of your use of or inability to use the program, even if TriSoft or an
authorized representative has been advised of the possibility of such
damages. TriSoft will not be liable for any such claim by any other
party.
TRADEMARK NOTICE
TriBBS is a registered trademark of TriSoft.
All other trademarks are the property of their respective owners.
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
FUNDAMENTAL DATA TYPES . . . . . . . . . . . . . . . . . . . . . . 2
SHORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
USHORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
LONG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
ULONG . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
COMPLEX DATA TYPES . . . . . . . . . . . . . . . . . . . . . . . . 3
SYSDAT1DATA . . . . . . . . . . . . . . . . . . . . . . . . . 3
SYSDAT2DATA . . . . . . . . . . . . . . . . . . . . . . . . . 7
NODEDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
USERSDATA . . . . . . . . . . . . . . . . . . . . . . . . . . 10
USERSINDEX . . . . . . . . . . . . . . . . . . . . . . . . . . 12
USERSSUPMESSAGES . . . . . . . . . . . . . . . . . . . . . . . 13
USERSSUPFILES . . . . . . . . . . . . . . . . . . . . . . . . 13
MCONFDATA . . . . . . . . . . . . . . . . . . . . . . . . . . 14
MPTRDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
MIDXDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
FAREADATA . . . . . . . . . . . . . . . . . . . . . . . . . . 18
DOORSTMPDATA . . . . . . . . . . . . . . . . . . . . . . . . . 19
GLOBAL VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . 22
AliasIndex . . . . . . . . . . . . . . . . . . . . . . . . . . 22
DoorsTmpData . . . . . . . . . . . . . . . . . . . . . . . . . 22
FAreaData . . . . . . . . . . . . . . . . . . . . . . . . . . 22
FAreaFile . . . . . . . . . . . . . . . . . . . . . . . . . . 22
IsShare . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
MConfData . . . . . . . . . . . . . . . . . . . . . . . . . . 22
MConfFile . . . . . . . . . . . . . . . . . . . . . . . . . . 22
MIdxData . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MIdxFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MPtrData . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MPtrFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MTxtFile . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
NodeData . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Node1sMainDirectory . . . . . . . . . . . . . . . . . . . . . 23
NumberOfFileAreas . . . . . . . . . . . . . . . . . . . . . . 23
NumberOfMessageAreas . . . . . . . . . . . . . . . . . . . . . 24
NumberOfUsers . . . . . . . . . . . . . . . . . . . . . . . . 24
SysDat1Data . . . . . . . . . . . . . . . . . . . . . . . . . 24
SysDat2Data . . . . . . . . . . . . . . . . . . . . . . . . . 24
TBErrorRoutine . . . . . . . . . . . . . . . . . . . . . . . . 24
UsersData . . . . . . . . . . . . . . . . . . . . . . . . . . 25
UsersFile . . . . . . . . . . . . . . . . . . . . . . . . . . 25
UsersIndex . . . . . . . . . . . . . . . . . . . . . . . . . . 25
UsersSupFile . . . . . . . . . . . . . . . . . . . . . . . . . 25
UsersSupFiles . . . . . . . . . . . . . . . . . . . . . . . . 25
UsersSupMessages . . . . . . . . . . . . . . . . . . . . . . . 25
i
THE TRIBBS API FUNCTIONS . . . . . . . . . . . . . . . . . . . . . 26
fsgetc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
fsgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
fsgetstring . . . . . . . . . . . . . . . . . . . . . . . . . 26
fsopen . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
fsprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
fsputc . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
fsputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
fsread . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
fswrite . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
TBBasicSingleToDouble . . . . . . . . . . . . . . . . . . . . 27
TBCheckForShareExe . . . . . . . . . . . . . . . . . . . . . . 27
TBCompress . . . . . . . . . . . . . . . . . . . . . . . . . . 27
TBGetNextMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . 28
TBInitialCaps . . . . . . . . . . . . . . . . . . . . . . . . 28
TBInitialize . . . . . . . . . . . . . . . . . . . . . . . . . 28
TBMakePathName . . . . . . . . . . . . . . . . . . . . . . . . 29
TBNumberInFAREADAT . . . . . . . . . . . . . . . . . . . . . . 29
TBNumberInMCONFDAT . . . . . . . . . . . . . . . . . . . . . . 30
TBNumberInMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . 30
TBNumberInMnnnnPTR . . . . . . . . . . . . . . . . . . . . . . 30
TBNumberInUSERSDAT . . . . . . . . . . . . . . . . . . . . . . 30
TBOpenFAREADAT . . . . . . . . . . . . . . . . . . . . . . . . 30
TBOpenMCONFDAT . . . . . . . . . . . . . . . . . . . . . . . . 30
TBOpenMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . . . 30
TBOpenMnnnnPTR . . . . . . . . . . . . . . . . . . . . . . . . 30
TBOpenMnnnnTXT . . . . . . . . . . . . . . . . . . . . . . . . 31
TBOpenUSERSDAT . . . . . . . . . . . . . . . . . . . . . . . . 31
TBOpenUSERSSUP . . . . . . . . . . . . . . . . . . . . . . . . 31
TBReadDOORSTMP . . . . . . . . . . . . . . . . . . . . . . . . 31
TBReadFAREADAT . . . . . . . . . . . . . . . . . . . . . . . . 31
TBReadMCONFDAT . . . . . . . . . . . . . . . . . . . . . . . . 31
TBReadMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadMnnnnPTR . . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadNODEDAT . . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadSYSDAT1DAT . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadSYSDAT2DAT . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadUSERSDAT . . . . . . . . . . . . . . . . . . . . . . . . 32
TBReadUSERSSUP . . . . . . . . . . . . . . . . . . . . . . . . 32
TBSearchMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . . 33
TBSearchUSERSIDX . . . . . . . . . . . . . . . . . . . . . . . 33
TBStrCrc32 . . . . . . . . . . . . . . . . . . . . . . . . . . 33
TBStripNewline . . . . . . . . . . . . . . . . . . . . . . . . 33
TBStripSpaces . . . . . . . . . . . . . . . . . . . . . . . . 33
TBStrNCrc32 . . . . . . . . . . . . . . . . . . . . . . . . . 33
TBUncompress . . . . . . . . . . . . . . . . . . . . . . . . . 34
TBUpdateFromAndTo . . . . . . . . . . . . . . . . . . . . . . 34
TBWriteDOORSTMP . . . . . . . . . . . . . . . . . . . . . . . 34
TBWriteFAREADAT . . . . . . . . . . . . . . . . . . . . . . . 34
TBWriteMCONFDAT . . . . . . . . . . . . . . . . . . . . . . . 34
TBWriteMnnnnIDX . . . . . . . . . . . . . . . . . . . . . . . 34
TBWriteMnnnnPTR . . . . . . . . . . . . . . . . . . . . . . . 35
ii
TBWriteNODEDAT . . . . . . . . . . . . . . . . . . . . . . . . 35
TBWriteSYSDAT1DAT . . . . . . . . . . . . . . . . . . . . . . 35
TBWriteUSERSDAT . . . . . . . . . . . . . . . . . . . . . . . 35
TBWriteUSERSSUP . . . . . . . . . . . . . . . . . . . . . . . 35
MISCELLANEOUS IMPLEMENTATION NOTES . . . . . . . . . . . . . . . . 36
How Files Are Opened . . . . . . . . . . . . . . . . . . . . . 36
Record Numbers . . . . . . . . . . . . . . . . . . . . . . . . 36
Calculating CRCs . . . . . . . . . . . . . . . . . . . . . . . 36
DEMO PROGRAMS . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
iii
INTRODUCTION
The TriBBS API is intended to assist third-party C/C++ programmers in
creating doors and utilities that are specific to the TriBBS Bulletin
Board System. It contains all of the routines necessary to access the
system data files. Additionally, it provides all of the routines
necessary to access TriBBS's compressed message base.
The TriBBS API is provided as large memory model libraries for the
following C/C++ compilers:
======================================================================
COMPILER LIBRARY NAME
----------------------------------------------------------------------
Borland C++ TBAPIBC.LIB
Symantec C++ TBAPISC.LIB
Turbo C++ TBAPITC.LIB
======================================================================
Other C/C++ compilers may be supported with future versions of the
API.
IMPORTANT NOTE: The TriBBS data structures are all aligned on byte
boundaries. This is the default for both Borland C++ and Turbo C++.
However, Symantec C++'s default is to align data structures on word
boundaries. Therefore, it is vital that you compile any programs that
use the TriBBS API with Symantec C++'s -a1 command line switch. This
forces Symantec C++ to align data structures on byte boundaries.
1
FUNDAMENTAL DATA TYPES
Because 32-bit operating systems are finally starting to become
popular, programmers should strive to write their programs so that
they will be portable across platforms without having to worry about
the word size of the platform. Under a 16-bit operating system, such
as DOS, an int is a 16-bit value. Under a 32-bit operating system,
such as OS/2 2.x and Windows NT, an int is a 32-bit value.
Accordingly, the TriBBS API provides four fundamental data types that
are intended to ease the porting of TriBBS utilities and doors to 32-
bit versions of TriBBS that may become available in the future.
SHORT
The SHORT data type is used to define signed, 16-bit values. It is
defined in TBAPI.H as follows:
typedef short int SHORT;
USHORT
The USHORT data type is used to define unsigned, 16-bit values. It is
defined in TBAPI.H as follows:
typedef unsigned short int USHORT;
LONG
The LONG data type is used to define signed, 32-bit values. It is
defined in TBAPI.H as follows:
typedef long LONG;
ULONG
The ULONG data type is used to define unsigned, 32-bit values. It is
defined in TBAPI.H as follows:
typedef unsigned long ULONG;
2
COMPLEX DATA TYPES
Because TriBBS stores a diverse collection of data in its data file,
the TriBBS API defines several complex data types in TBAPI.H to make
accessing the TriBBS data files easier.
SYSDAT1DATA
The SYSDAT1DATA structure is defined in TBAPI.H as follows:
typedef struct _SYSDAT1DATA {
char BoardName[41];
char SysopName[41];
char BoardStartDate[9];
char DefaultArchiveExtension[4];
SHORT TotalNodes;
SHORT CallsToday;
SHORT MessagesToday;
SHORT UploadsToday;
SHORT DownloadsToday;
SHORT DefaultDailyTimeLimit;
SHORT DefaultDailyLogons;
SHORT DefaultTimePerLogon;
SHORT MinimumSysopSecurityLevel;
SHORT NewUserSecurityLevel;
SHORT NewUserTimeTimeLimit;
SHORT UploadTimeCompensationRatio;
SHORT MaximumKeyboardIdleTime;
LONG TotalCalls;
SHORT PhoneNumberFlag;
SHORT TestUploadsFlag;
SHORT AutoANSIDetectFlag;
SHORT CheckForWaitingMessagesFlag;
char SystemPassword[16];
SHORT ULDLRatioTypeFlag;
SHORT PhoneOnHookDuringMaintenanceFlag;
SHORT NoOneWordNamesFlag;
SHORT NoBulletinMenuAtLogonFlag;
SHORT AllowAliasesFlag;
SHORT ClearScreenBeforeMenusFlag;
SHORT ExactFileNameMatchingForDupesFlag;
SHORT DisableNewUserBirthdayPrompt;
SHORT DetailedCallerLogFlag;
SHORT MajorVersionNumber;
SHORT MinorVersionNumber;
SHORT EnableRIPScripEmulationFlag;
SHORT MinimumFileAttachmentSecurityLevel;
SHORT MinimumAtVariableSecurityLevel;
SHORT FastLogonSecurityLevel;
SHORT UseAliasOrRealNamesFlag;
3
SHORT ClearUploadsAndDownloadsFlag;
SHORT ClearPrivateMessageAreasFlag;
SHORT ClearPrivateFileAreasFlag;
char ReservedDataArea[69];
} SYSDAT1DATA;
The following table defines how the fields that make up SYSDAT1DATA
are used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
BoardName This field holds the BBS's name.
SysopName This field holds the sysop's name.
BoardStartDate This field holds the starting date of
the BBS using the format MM/DD/YY.
DefaultArchiveExtension This field holds the default archive
extension. It must be set to ZIP, ARJ,
LZH, PAK, SDN, or ARC.
TotalNodes This field holds the total number of
nodes.
CallsToday This field holds the number of calls for
the day.
MessagesToday This field holds the number of messages
posted for the day.
UploadsToday This field holds the number of files
uploaded for the day.
DownloadsToday This field holds the number of files
downloaded for the day.
DefaultDailyTimeLimit This field holds the default daily time
limit.
DefaultDailyLogons This field holds the default maximum
number of times a caller can call the
BBS in a single day.
DefaultTimePerLogon This field holds the default maximum
time a caller is allowed for each
individual call.
MinimumSysopSecurityLevel This field holds the minimum security
level a caller must have to be
considered a sysop-level user.
NewUserSecurityLevel This field holds the security level
assigned to all new callers.
NewUserTimeTimeLimit This field holds the maximum amount of
time a new user is allowed for his first
time on the BBS.
UploadTimeCompensationRatio This field holds the ratio that TriBBS
will use when compensating the caller's
time for uploads.
MaximumKeyboardIdleTime This field holds the number of minutes
that TriBBS will wait before logging the
caller off for no activity. This
feature can be disabled by setting this
4
field to 0.
TotalCalls This field holds the board's total
number of calls.
PhoneNumberFlag When this field is set to 0, TriBBS will
use US style phone number using the
format ###-###-####. When this field is
set to 1, TriBBS will not attempt to
format the phone number in anyway.
TestUploadsFlag When this field is set to 1, TriBBS will
check all uploads with its internal
archive checker. When this field is set
to 0, TriBBS will not check uploads with
its internal archive checker.
AutoANSIDetectFlag When this field is set to 1, TriBBS will
automatically check for ANSI terminal
emulation at logon. When this field is
set to 0, TriBBS will not try to detect
ANSI at logon.
CheckForWaitingMessagesFlag When this field is set to 1, TriBBS will
check for waiting messages when a caller
logs on. When this field is set to 0,
TriBBS will not check for waiting
messages.
SystemPassword This field holds the board's system
password.
ULDLRatioTypeFlag When this field is set to 0, TriBBS will
adjust the caller's security level
according to the board's upload/download
ratios. When this field is set to 1,
TriBBS will not allow a caller to
download if he has exceeded his
upload/download ratio.
PhoneOnHookDuringMaintenanceFlag When this field is set to 0, TriBBS
will take the phone off the hook
when calling maintenance routines
from the waiting for caller screen.
When this field is set to 1, TriBBS
will not take the phone off the
hook for maintenance routines.
NoOneWordNamesFlag When this field is set to 1, TriBBS will
not allow callers to log on using a one
word name. When this field is set to 0,
TriBBS will allow callers to log on
using a one word name.
NoBulletinMenuAtLogonFlag When this field is set to 1, TriBBS will
not display the bulletin menu to the
caller at logon. When this field is set
to 0, TriBBS will display the bulletin
menu to the caller at logon.
AllowAliasesFlag When this field is set to 1, TriBBS will
allow callers to optionally use an
alias. When the field is set to 0,
5
TriBBS will not allow callers to use
aliases.
ClearScreenBeforeMenusFlag When this field is set to 1, TriBBS will
clear the screen before it displays a
menu. When this field is set to 0,
TriBBS will not clear the screen before
it displays a menu.
ExactFileNameMatchingForDupesFlag When this field is set to 1, TriBBS
will check for exact matches when
checking for duplicate files. When
this field is set to 0, TriBBS will
ignore the file extensions when
checking for duplicate files.
Note: TriBBS will always do exact
file name checking for indexed file
areas.
DisableNewUserBirthdayPrompt When this field is set to 1, TriBBS will
not ask for the caller's birthday with
the other new user logon information.
When this field is set to 0, TriBBS will
ask for the caller's birthday with the
other new user log on information.
DetailedCallerLogFlag When this field is set to 1, TriBBS will
log all menu selections in the callers
log. When the field is set to 0, TriBBS
will not log menu selections in the
callers log.
MajorVersionNumber This field holds the major version
number for this version of TriBBS.
MinorVersionNumber This field holds the minor version
number for this version of TriBBS.
EnableRIPScripEmulationFlag When this field is set to 1, TriBBS will
check for RIPScrip terminal emulation at
log on and allow the use of RIPScrip
display screens throughout the system.
When this field is set to 0, TriBBS will
disable the use of RIPScrip.
MinimumFileAttachmentSecurityLevel This field holds the minimum
security level that a caller must
have to attach a file to a message.
MinimumAtVariableSecurityLevel This field holds the minimum
security level that a caller must
have to use @-variables in
messages.
FastLogonSecurityLevel This field holds the minimum security
level that a caller must have to use
TriBBS's quick logon feature.
UseAliasOrRealNamesFlag When this field is set to 1, TriBBS will
use the caller's real name in the who's
on list, in the TeleChat menu, and in
the list of the board's users. When
this field is set to 0, TriBBS will use
6
the caller's alias in the who's on list,
in the TeleChat menu, and in the list of
the board's users.
ClearUploadsAndDownloadsFlag When this field is set to 1, TriBBS will
clear the caller's number of files
uploaded, number of files downloaded,
number of bytes uploaded, and number of
bytes downloaded when the caller's
subscription expires. When this field
is set to 0, TriBBS retains all of the
caller's upload/download information
when the caller's subscription expires.
ClearPrivateMessageAreasFlag When this field is set to 1, TriBBS will
clear the caller's access to private
message conferences. When this field is
set to 0, TriBBS will retain all of the
caller's private message conference
access.
ClearPrivateFileAreasFlag When this field is set to 1, TriBBS will
clear the caller's access to private
file areas. When this field is set to
0, TriBBS will retain all of the
caller's private file area access.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
SYSDAT2DATA
The SYSDAT2DATA structure is defined in TBAPI.H as follows:
typedef struct _SYSDAT2DATA {
char Node1sMainDirectory[81];
char ReservedDataArea[175];
} SYSDAT2DATA;
The following table defines how the fields that make up SYSDAT2DATA
are used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
Node1sMainDirectory This field holds node 1's main
directory.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
NODEDATA
7
The NODEDATA structure is defined in TBAPI.H as follows:
typedef struct _NODEDATA {
char InitializationString[81];
char ErrorCorrectingConnectionMessage[5];
char DateOfLastCall[9];
SHORT NodeNumber;
USHORT MaximumBaudRate;
SHORT SerialPort;
SHORT No300BaudCallersFlag;
SHORT No1200BaudCallersFlag;
SHORT RTSCTSHandshakingFlag;
SHORT LockSerialPortFlag;
SHORT DirectScreenWriteFlag;
SHORT DelayBeforeATA;
SHORT NumberOfRings;
SHORT PageBellOnFlag;
SHORT UseNodeDISPLAYDirectoryFlag;
SHORT NodeSecurityLevel;
SHORT No2400BaudCallersFlag;
SHORT PhoneOffHookDuringEventsFlag;
SHORT NonStandardIRQNumber;
char ReservedDataArea[129];
} NODEDATA;
The following table defines how the fields that make up NODEDATA are
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
InitializationString This field holds the modem's
initialization string.
ErrorCorrectingConnectionMessage This field holds the modem's error
correcting connection.
DateOfLastCall This field holds the date of the last
call on this node.
NodeNumber This field holds the node's node number.
MaximumBaudRate This field holds the node's maximum baud
rate.
SerialPort This field holds the node's serial port
number.
No300BaudCallersFlag When this field is set to 1, TriBBS will
not allow 300 baud callers on this node.
When this field is set to 0, TriBBS will
allow 300 baud callers on this node.
No1200BaudCallersFlag When this field is set to 1, TriBBS will
not allow 1200 baud callers on this
node. When this field is set to 0,
TriBBS will allow 1200 baud callers on
this node.
8
RTSCTSHandshakingFlag When this field is set to 1, TriBBS will
use RTS/CTS handshaking. When this
field is set to 0, TriBBS will not use
RTS/CTS handshaking.
LockSerialPortFlag When this field is set to 1, TriBBS will
lock the serial port. When this field
is set to 0, TriBBS will not lock the
serial port.
DirectScreenWriteFlag When this field is set to 1, TriBBS will
use direct screen writes on a CGA
system. When this field is set to 0,
TriBBS will not use direct screen writes
on a CGA system.
DelayBeforeATA This field holds the tenths of a second
TriBBS will wait after it receives a
CONNECT message before sending the ATA
command to the modem to answer the call.
NumberOfRings This field holds the number of rings
that TriBBS will wait for before
answering the call.
PageBellOnFlag When this field is set to 1, the page
bell will be on. When this field is set
to 0, the page bell will be off.
UseNodeDISPLAYDirectoryFlag When this field is set to 1, TriBBS will
use the node's DISPLAY directory to
locate display screens. When this field
is set to 0, TriBBS will use node 1's
DISPLAY directory to locate display
screens.
NodeSecurityLevel This field holds the minimum security
level a caller must have to log onto a
node.
No2400BaudCallersFlag When this field is set to 1, TriBBS will
not allow 2400 baud callers. When this
field is set to 0, TriBBS will allow
2400 baud callers.
PhoneOffHookDuringEventsFlag When this field is set to 1, TriBBS will
take the phone off the hook when it runs
an event. When this field is set to 0,
TriBBS will not take the phone off the
hook during an event.
NonStandardIRQNumber When this field is a non-zero value,
TriBBS uses it for the serial port's
nonstandard IRQ setting. When this
field is set to 0, TriBBS will use the
standard IRQ setting for the serial
port.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
9
USERSDATA
The USERSDATA structure is defined in TBAPI.H as follows:
typedef struct _USERSDATA {
char Name[31];
char Password[16];
char CityAndState[31];
char PhoneNumber[13];
char Birthday[9];
char DateOfFirstCall[9];
char DateAndTimeOfLastCall[15];
char DateOfLastFileCheck[9];
SHORT SecurityLevel;
SHORT NumberOfCalls;
SHORT TimeLeftForToday;
SHORT LastMessageConference;
SHORT LastFileArea;
SHORT DefaultProtocol;
SHORT ExpertModeFlag;
SHORT LockedOutFlag;
SHORT MarkedForDeletionFlag;
SHORT NumberOfCallsToday;
SHORT IncludeLOGON1InQWKFlag;
SHORT IncludeGOODBYEInQWKFlag;
SHORT IncludeBulletinsInQWKFlag;
SHORT IncludeNewFilesInQWKFlag;
SHORT IncludeNewsletterInQWKFlag;
SHORT QWKNetworkNode;
LONG NumberOfFilesUploaded;
LONG NumberOfFilesDownloaded;
LONG NumberOfKBytesUploaded;
LONG NumberOfKBytesDownloaded;
LONG NumberOfMessagesPosted;
SHORT DefaultEditor;
SHORT InitialChatStatus;
SHORT CheckForWaitingMessagesFlag;
char SubscriptionExpirationDate[9];
char Alias[31];
SHORT NumberOfFilesDownloadedToday;
LONG NumberOfBytesDownloadedToday;
char ReservedDataArea[19];
} USERSDATA;
The following table defines how the fields that make up USERSDATA are
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
Name This field holds the user's name.
Password This field holds the user's password.
10
CityAndState This field holds the user's city and
state.
PhoneNumber This field holds the user's phone
number.
Birthday This field holds the caller's birthday
using the format MM/DD/YY.
DateOfFirstCall This field holds the date of the user's
first call using the format MM/DD/YY.
DateAndTimeOfLastCall This field holds the date and time of
the user's last call using the format
MM/DD/YY HH:MM.
DateOfLastFileCheck This field holds the date of the user's
last file check using the format
MM/DD/YY.
SecurityLevel This field holds the user's security
level.
NumberOfCalls This field holds the user's number of
calls.
TimeLeftForToday This field holds the user's number of
minutes remaining for the day.
LastMessageConference This field holds the user's last message
conference.
LastFileArea This field holds the user's last file
area.
DefaultProtocol This field holds the user's default
protocol.
ExpertModeFlag When this field is set to 0, the user is
in novice mode. When this field is set
to 1, the user is in expert mode. When
this field is set to 2, the user is in
super expert mode.
LockedOutFlag When this field is set to 1, the user is
locked out. When this field is set to
0, the user is not locked out.
MarkedForDeletionFlag When this field is set to 1, the user's
record will be deleted during the next
packing of the user file. When this
field is set to 0, the user's record
will be retained during the next packing
of the user file.
NumberOfCallsToday This field holds the user's number of
calls for the day.
IncludeLOGON1InQWKFlag When this field is set to 1,
LOGON1.BBS/ANS will be included in the
user's QWK packets.
IncludeGOODBYEInQWKFlag When this field is set to 1,
GOODBYE.BBS/ANS will be included in the
user's QWK packets.
IncludeBulletinsInQWKFlag When this field is set to 1, any new
bulletins will be included in the user's
QWK packets.
IncludeNewFilesInQWKFlag When this field is set to 1, a list of
11
new files will be included in the user's
QWK packets.
IncludeNewsletterInQWKFlag When this field is set to 1, the
newsletter will be included in the
user's QWK packet if it has been updated
since the user's last call.
QWKNetworkNode When this field is set to 1, the caller
has net status. When this field is set
to 0, the caller doesn't have net
status.
NumberOfFilesUploaded This field holds the number of files the
user has uploaded.
NumberOfFilesDownloaded This field holds the number of files the
user has downloaded.
NumberOfKBytesUploaded This field holds the number of Kbytes
the user has uploaded.
NumberOfKBytesDownloaded This field holds the number of Kbytes
the user has downloaded.
NumberOfMessagesPosted This field holds the number of messages
the user has posted.
DefaultEditor This field holds the user's default
editor.
InitialChatStatus This field holds the user's initial chat
status.
CheckForWaitingMessagesFlag This field holds the user's check for
waiting messages flag.
SubscriptionExpirationDate This field holds the user's subscription
expiration data using the format
MM/DD/YY. If the caller is not a
subscriber, this field is set to a null
string.
Alias This field holds the user's alias.
NumberOfFilesDownloadedToday This field holds the user's number of
files downloaded for the day.
NumberOfBytesDownloadedToday This field holds the user's number of
bytes downloaded for the day.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
USERSINDEX
The USERSINDEX structure is defined in TBAPI.H as follows:
typedef struct _USERSINDEX {
ULONG Crc;
SHORT RecordNumber;
} USERSINDEX;
The following table defines how the fields that make up USERSINDEX are
used:
12
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
Crc This field holds a CRC value that is
based on the user's name.
RecordNumber This field holds the user's record
number in USERS.DAT.
======================================================================
USERSSUPMESSAGES
The USERSSUPMESSAGES structure if defined in TBAPI.H as follows:
typedef struct _USERSSUPMESSAGES {
SHORT QueuedConferenceFlag;
SHORT PrivateConferenceFlag;
LONG LastMessageRead;
SHORT WaitingMessageCounter;
} USERSSUPMESSAGES;
The following table defines how the fields that make up
USERSSUPMESSAGES are used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
QueuedConferenceFlag When this field is set to 1, the user
has the conference queued. When this
field is set to 0, the user doesn't have
the conference queued.
PrivateConferenceFlag When this field is set to 1, the user
has access to the private conference.
When this field is set to 0, the user
doesn't have access to the private
conference.
LastMessageRead This field holds the number of the last
message the user read in this
conference.
WaitingMessageCounter This field holds the number of waiting
messages the user has in this
conference.
======================================================================
USERSSUPFILES
The USERSSUPFILES structure is defined in TBAPI.H as follows:
typedef struct _USERSSUPFILES {
SHORT PrivateAreaFlag;
} USERSSUPFILES;
13
The following table defines how the fields that make up USERSSUPFILES
are used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
PrivateAreaFlag When this field is set to 1, the user
has access to the private file area.
When this field is set to 0, the user
doesn't have access to the private file
area.
======================================================================
MCONFDATA
The MCONFDATA structure is defined in TBAPI.H as follows:
typedef struct _MCONFDATA{
SHORT ReadSecurityLevel;
SHORT NetworkedConferenceFlag;
SHORT UserDeleteFlag;
SHORT TriPackBackupFlag;
SHORT TriPackNumberOfDaysToSave;
SHORT PrivateConferenceFlag;
SHORT FidoStyleNetMailFlag;
SHORT AliasConferenceFlag;
SHORT PostSecurityLevel;
SHORT DisablePrivateMessagesFlag;
char ConferenceName[41];
char NetworkName[41];
LONG HighestMessageNumber;
SHORT DisablePublicMessagesFlag;
char ReservedDataArea[148];
} MCONFDATA;
The following table defines how the fields that make up MCONFDATA are
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
ReadSecurityLevel This field holds the security level that
the caller must have to read messages in
this conference.
NetworkedConferenceFlag When this field is set to 1, TriBBS
treats it as a networked conference.
When this field is set to 0, TriBBS
treats it as a local conference.
UserDeleteFlag When this field is set to 1, TriBBS will
allow callers to delete messages that
are addressed either from or to them.
14
When this field is set to 0, the caller
must have sysop level to delete
messages.
TriPackBackupFlag When this field is set to 1, TriPack
will create backup files for the
conference when it is packing the
message base. When this field is set to
0, TriPack will not create backup files
for the conference when it is packing
the message base.
TriPackNumberOfDaysToSave This field holds the number of days back
TriPack should save messages for in the
conference.
PrivateConferenceFlag When this flag is set to 1, the
conference is private. When this flag
is set to 0, the conference is public.
FidoStyleNetMailFlag When this flag is set to 1, TriBBS will
ask for a Fido-style netmail address
when the caller enters a message. When
this flag is set to 0, TriBBS will not
ask for a Fido-style netmail address.
AliasConferenceFlag When this flag is set to 1, TriBBS will
allow aliases to be used in this
conference. When this flag is set to 0,
TriBBS will not allow aliases to be used
in this conference.
PostSecurityLevel This field holds the minimum security
level a caller must have to post a
message in this conference.
DisablePrivateMessagesFlag When this flag is set to 1, TriBBS will
not allow private messages to be entered
in this conference.
ConferenceName This field holds the conference's name.
NetworkName This field holds the conference's
network name.
HighestMessageNumber This field holds the number of the last
message posted in this conference.
DisablePublicMessagesFlag When this flag is set to 1, TriBBS will
not allow public messages to be entered
in this conference.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
MPTRDATA
The MPTRDATA structure is defined in TBAPI.H as follows:
typedef struct MPTRDATA {
char DateAndTime[15];
char From[31];
15
char To[31];
char Subject[41];
SHORT EchoMessageFlag;
SHORT ThreadedMessageFlag;
SHORT PrivateMessageFlag;
SHORT DeletedMessageFlag;
SHORT ReceivedMessageFlag;
SHORT PermanentMessageFlag;
SHORT NetmailFromZone;
SHORT NetMailFromNet;
SHORT NetMailFromNode;
SHORT NetMailFromPoint;
SHORT NetMailToZone;
SHORT NetMailToNet;
SHORT NetMailToNode;
SHORT NetMailToPoint;
LONG OffsetIntoTextFile;
LONG Number;
LONG NumberOfMessageThisRepliesTo;
char NameOfAttachedFile[81];
} MPTRDATA;
The following table defines how the fields that make up MPTRDATA are
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
DateAndTime This field holds the date and time of
the message using the format MM/DD/YY
HH:MM.
From This field holds the name of the person
who posted the message.
To This field holds the name of the person
who the message is posted to.
Subject This field holds the message's subject.
EchoMessageFlag When this field is set to 1, the message
should be echoed. When this field is
set to 0, the message should not be
echoed.
ThreadedMessageFlag When this field is set to 1, the message
has replies. When this field is set to
0, the message doesn't have any replies.
PrivateMessageFlag When this field is set to 1, the
messages is a private message. When
this field is set to 0, the message is a
public message.
DeletedMessageFlag When this field is set to 1, the message
has been marked for deletion. When this
field is set to 0, the message has not
been marked for deletion.
ReceivedMessageFlag When this field is set to 1, the message
16
has been received by the person it is
addressed to. When this field is set to
0, the message has not been received by
the person it is addressed to.
PermanentMessageFlag When this field is set to 1, TriPack
will not delete it. When this field is
set to 0, TriPack can delete the
message.
NetmailFromZone This field holds the zone number the
message is from if it is in a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailFromNet This field holds the net number the
message is from if it is in a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailFromNode This field holds the node number the
message is from if it is in a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailFromPoint This field holds the point number the
message is from if it is in a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailToZone This field holds the zone number the
message is to if it is a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailToNet This field holds the net number the
message is to if it is a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailToNode This field holds the node number the
message is to if it is a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
NetMailToPoint This field holds the point number the
message is to if it is a Fido-style
netmail conference. Otherwise, this
field should be set to 0.
OffsetIntoTextFile This field holds the location of the
message's text in the Mnnnn.TXT file.
Number This field holds the message's number.
NumberOfMessageThisRepliesTo If this message is a response to a
previous message, this field will hold
the number of the original message.
Otherwise, this field should be set to
0.
NameOfAttachedFile Name of an attached file. Otherwise,
this field should be set to a null
string.
======================================================================
17
MIDXDATA
The MIDXDATA structure is defined in TBAPI.H as follows:
typedef struct _MIDXDATA {
ULONG FromCRC;
ULONG ToCRC;
LONG Number;
LONG NumberOfMessageThisRepliesTo;
} MIDXDATA;
The following table defines how the fields that make up MIDXDATA are
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
FromCRC This field holds the CRC of the name of
the caller who posted the message.
ToCRC This field holds the CRC of the name of
the caller the message is posted to.
Number This field holds the message's number.
NumberOfMessageThisRepliesTo If this message is a response to a
previous message, this field will hold
the number of the original message.
Otherwise, this field should be set to
0.
======================================================================
FAREADATA
The FAREADATA structure is defined in TBAPI.H as follows:
typedef struct _FAREADATA{
SHORT SecurityLevel;
SHORT SortType;
SHORT PrivateAreaFlag;
char Name[41];
char FileAreaPath[81];
char FileAreaUploadPath[81];
char FileAreaFileList[81];
char FileAreaUploadList[81];
SHORT CDROMFileAreaFlag;
SHORT AliasAreaFlag;
char FileAreaIndexFile[81];
char AdditionalFileAreaPaths[10][81];
char ReservedDataArea[14];
} FAREADATA;
The following table defines how the fields that make up FAREADATA are
18
used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
SecurityLevel This field holds the minimum security
level that a caller must have to access
the file area.
SortType When this field is set to 1, the file
area is sorted by file name. When this
field is set to 0, the file area is
sorted by date.
PrivateAreaFlag When this field is set to 1, the file
area is private. When this field is set
to 0, the file area is public.
Name This is the file area's name.
FileAreaPath This is the file area's directory.
FileAreaUploadPath This is the file area's upload
directory.
FileAreaFileList This is the name of the file area's file
list.
FileAreaUploadList This is the name of the file area's
upload file list.
CDROMFileAreaFlag When this field is set to 1, the file
area is considered a CD-ROM file area.
When this field is set to 0, the file
area is a regular file area.
AliasAreaFlag When this field is set to 1, the file
area is an alias file area. When this
field is set to 0, the file area is not
an alias file area.
FileAreaIndexFile This is the name of the file area's
index file.
AdditionalFileAreaPaths These are the file area's additional
directories.
ReservedDataArea This area is reserved for future use.
It must be always set to all zeros.
======================================================================
DOORSTMPDATA
The DOORSTMPDATA structure is defined in TBAPI.H as follows:
typedef struct _DOORSTMPDATA {
USHORT BaudRate;
SHORT ErrorCorrectingConnection;
SHORT UserRecordNumber;
SHORT TimeLeftAtLogon;
SHORT ANSIFlag;
SHORT CurrentFileArea;
SHORT CurrentMessageConference;
19
LONG TimeWhenUserLoggedOn;
SHORT FrontEnd;
USHORT FrontEndBaudRate;
SHORT FrontEndHangUpFlag;
SHORT UserWindowFlag;
SHORT FrontEndTime;
SHORT WhereTheDoorWasCalledFrom;
SHORT ChatRequested;
SHORT EventPendingFleg;
SHORT GoodbyeFromDoorFlag;
SHORT ForceBoardDownAfterCallFlag;
SHORT LanguageNumber;
SHORT RIPScripFlag;
SHORT NumberOfFilesFlagged;
SHORT DOORSYSFlag;
SHORT TimeInDOORSYS;
char ReservedDataArea[208];
} DOORSTMPDATA;
The following table defines how the fields that make up DOORSTMPDATA
are used:
======================================================================
FIELD DESCRIPTION
----------------------------------------------------------------------
BaudRate This field holds the caller's baud rate.
ErrorCorrectingConnection When this field is set to 1, the caller
achieved an error correcting connection.
When this field is set to 0, an error
correcting connection couldn't be
achieved.
UserRecordNumber This field holds the caller's record
number in USERS.DAT.
TimeLeftAtLogon This field holds the number of minutes
the caller had at log on.
ANSIFlag When this field is set to 1, the caller
has ANSI graphics enabled. When this
field is set to 0, the caller has ANSI
graphics disabled.
CurrentFileArea This field holds the number of the
caller's current file area.
CurrentMessageConference This field holds the number of the
caller's current message conference.
TimeWhenUserLoggedOn The field holds the time the caller
logged on at. This value is in seconds
elapsed since 00:00:00 GMT, January 1,
1970.
FrontEnd When this flag is set to 1, TriBBS was
called from a frontend program. When
this flag is set to 0, TriBBS wasn't
called from a frontend program.
FrontEndBaudRate This field holds the baud rate that the
20
frontend passed to TriBBS.
FrontEndHangUpFlag When this field is set to 1, TriBBS will
hang up before returning control to the
frontend. When this field is set to 0,
TriBBS will not hang up before returning
control to the frontend.
UserWindowFlag When this field is set to 1, the user
status window is being displayed at the
bottom of the display screen. When this
field is set to 0, the user status
window is not being displayed.
FrontEndTime This field holds the time in minutes
until the frontend's next event.
WhereTheDoorWasCalledFrom This field holds a value that tells
TriBBS where the door was called from
ChatRequested When this field is set to 1, the caller
has requested a chat. When this field
is set to 0, the caller hasn't requested
a chat.
EventPendingFlag When this field is set to 1, there is an
event pending. When this field is set
to 0, there isn't an event pending.
GoodbyeFromDoorFlag TriBBS always sets this field to 0. If
the door wants to force a goodbye, then
it should change this field to a 1.
ForceBoardDownAfterCallFlag When this field is set to 1, TriBBS will
force the board down after the current
caller logs off. When this field is set
to 0, TriBBS will continue operating as
normal.
LanguageNumber This field holds the number of the
language the user selected at logon.
RIPScripFlag When this field is set to 1, the caller
has RIPScrip terminal emulation enabled.
When this field is set to 0, the caller
doesn't have RIPScrip terminal emulation
enabled.
NumberOfFilesFlagged This field holds the number of files
flagged.
DOORSYSFlag When this field is set to 1, TriBBS
created DOOR.SYS before calling the
door. When this field is set to 0,
TriBBS didn't create DOOR.SYS before
calling the door.
TimeInDOORSYS This is the number of minutes the caller
had remaining when he entered a door and
TriBBS generated a DOOR.SYS file.
ReservedDataArea This area is reserved for future use.
It must always be set to all zeros.
======================================================================
21
GLOBAL VARIABLES
The TriBBS API features a number of useful global variables. These
global variables are mainly intended to make accessing the TriBBS data
files easier.
USERSINDEX *AliasIndex
The AliasIndex global variable is defined as a pointer to a structure
of type USERSINDEX. It is mainly used internally by the TriBBS API to
point to an array of USERSINDEX structures that make up the ALIAS.IDX
data file.
DOORSTMPDATA DoorsTmpData
The DoorsTmpData global variable is defined as a structure of type
DOORSTMPDATA. Its main purpose is to access data in the DOORS.TMP
data file.
FAREADATA FAreaData
The FAreaData global variable is defined as a structure of type
FAREADATA. Its main purpose is to access data in the FAREA.DAT data
file.
FILE *FAreaFile
The FAreaFile global variable is defined as a pointer to a structure
of type FILE. Its main purpose is to access the FAREA.DAT data file.
SHORT IsShare
The IsShare global variable is defined as a SHORT. IsShare is used to
indicate if SHARE.EXE is loaded. IsShare is initially set to 0, but
TBInitialize() calls the proper DOS function to detect if SHARE.EXE is
loaded. If SHARE.EXE is loaded, IsShare will be set to 1. Otherwise,
IsShare will be set to 0.
MCONFDATA MConfData
The MConfData global variable is defined as a structure of type
MCONFDATA. Its main purpose is to access data in the MCONF.DAT data
file.
FILE *MConfFile
22
The MConfFile global variable is defined as a pointer to a structure
of type FILE. Its main purpose is to access the MCONF.DAT data file.
MIDXDATA MIdxData
The MIdxData global variable is defined as a structure of type
MIDXDATA. Its main purpose is to access data in the Mnnnn.IDX data
files.
FILE *MIdxFile
The MIdxFile global variable is defined as a pointer to a structure of
type FILE. Its main purpose is to access the Mnnnn.IDX data files.
MPTRDATA MPtrData
The MPtrData global variable is defined as a structure of type
MPTRDATA. Its main purpose is to access data in Mnnnn.PTR data files.
FILE *MPtrFile
The MPtrFile global variable is defined as a pointer to a structure of
type FILE. Its main purpose is to access the Mnnnn.PTR data files.
FILE *MTxtFile
The MTxtFile global variable is defined as a pointer to a structure of
type FILE. Its main purpose is to access the Mnnnn.TXT data files.
NODEDATA NodeData
The NodeData global variable is defined as a structure of type
NODEDATA. Its main purpose is to access data in the NODE.DAT data
file.
char Node1sMainDirectory[81]
The Node1sMainDirectory global variable is defined as an array of char
with a length of 81. It is used by the application program to set the
location of node 1's main directory. This variable must be set before
the application program calls TBInitialize().
SHORT NumberOfFileAreas
23
The NumberOfFileAreas global variable is set to the board's number of
file areas by TBInitialize(). This variable's value is undefined
before TBInitialize() is called.
SHORT NumberOfMessageAreas
The NumberOfMessageAreas global variable is set to the board's number
of message areas by TBInitialize(). This variable's value is
undefined before TBInitialize() is called.
SHORT NumberOfUsers
The NumberOfUses global variable is set to the board's number of users
by TBInitialize(). This variable's value is undefined before
TBInitialize() is called.
SHORT SupplementalLength
The SupplementalLength global variable is set to the record length for
board's USERS.SUP file by TBInitialize(). This variable's value is
undefined before TBInitialize() is called.
SYSDAT1DATA SysDat1Data
The SysDat1Data global variable is defined as a structure of type
SYSDAT1DATA. Its main purpose is to access data in the SYSDAT1.DAT
data file.
SYSDAT2DATA SysDat2Data
The SysDat2Data global variable is defined as a structure of type
SYSDAT2DATA. Its main purpose is to access data in the SYSDAT2.DAT
data file.
void (*TBErrorRoutine)(char *f, ...)
The TBErrorRoutine global variable is a pointer to a function of type
void (*)(char *, ...). It is a hook into the API so that the
programmer can define a customized error routine for his application
program. By default, the TBErrorRoutine points to the following
function, which simply does a printf() and then aborts the program:
void TBDefaultErrorRoutine(char *f, ...)
{
va_list m;
char *s, *b;
24
s = b = (char *)malloc(1024);
va_start(m, f);
vsprintf(s, f, m);
printf(s);
free(b);
va_end(m);
exit(1)
}
USERSDATA UsersData
The UsersData global variable is defined as a structure of type
USERSDATA. Its main purpose is to access the data in the USERS.DAT
file.
FILE *UsersFile
The UsersFile global variable is defined as a pointer to a structure
of type FILE. Its main purpose is to access the USERS.DAT file.
USERSINDEX *UsersIndex
The UsersIndex global variable is defined as a pointer to a structure
of type USERSINDEX. It is mainly used internally by the TriBBS API to
point to an array of USERSINDEX structures that make up the USERS.IDX
data file.
FILE *UsersSupFile
The UsersSupFile global variable is defined as a pointer to a
structure of type FILE. Its main purpose is to access the USERS.SUP
data file.
USERSSUPFILES *UsersSupFiles
The UsersSupFiles global variable is defined as a pointer to a
structure of type USERSSUPFILES. It is mainly used internally by the
TriBBS API to access data in the USERS.SUP data file.
USERSSUPMESSAGES *UsersSupMessages
The UsersSupMessages global variable is defined as a pointer to a
structure of type USERSSUPMESSAGES. It is mainly used internally by
the TriBBS API to access data in the USERS.SUP data file.
25
THE TRIBBS API FUNCTIONS
This section describes each function that make up the TriBBS API.
int fsgetc(FILE *stream)
The fsgetc function is functionally equivalent to the normal fgetc C
runtime library function. However, fsgetc will lock and unlock the
file if file sharing is necessary.
char *fsgets(char *s, int n, FILE *stream)
The fsgets function if functionally equivalent to the normal fgets C
runtime library function. However, fsgets will lock and unlock the
file if file sharing is necessary.
char *fsgetstring(char *s, int n, FILE *stream)
The fsgetstring function is similar to the fsgets function. Instead
of stopping at the first newline character, the fsgetstring function
stops at the first null character (0x00).
FILE *fsopen(const char *filename, const char *mode, int shflg)
The fsopen function is similar to the normal fsopen C runtime library
function. However, the "shflg" parameter is used to specify the file
sharing that is allowed on the file. Once the file is opened, all
subsequent tasks much open the file in a compatible file sharing mode.
The shflg function can be any one of the following constants, which
are defined in share.h:
SH_COMPAT DOS compatibility mode. This is the way DOS
normally opens a file.
SH_DENYRW Denies read/write access.
SH_DENYWR Denies write access.
SH_DENYRD Denies read access.
SH_DENYNO Permits read/write access.
SH_DENYNONE Permits read/write access. (Not all compilers
define this in their share.h file, but it is the
same as SH_DENYNO.)
int fsprintf(FILE *stream, char *f, ...)
The fsprintf function is functionally equivalent to the normal C
runtime library fprintf function. However, the fsprintf function will
properly lock and unlock the file if file sharing is in use.
26
int fsputc(int c, FILE *stream)
The fsputc function is functionally equivalent to the normal C runtime
library fputc function. However, the fsputc function will lock and
unlock the file if file sharing is in use.
int fsputs(char *s, FILE *stream)
The fsputs function is functionally equivalent to the normal C runtime
library fputs function. However, the fsputs function will lock and
unlock the file if file sharing is in use.
size_t fsread(void *ptr, size_t size, size_t n, FILE *stream)
The fsread function is functionally equivalent to the normal C runtime
library fread function. However, the fsread function will lock and
unlock the file if file sharing is in use.
size_t fswrite(const void *ptr, size_t size, size_t n, FILE *stream)
The fswrite function is functionally equivalent to the normal C
runtime library fwrite function. However, the fswrite function will
lock and unlock the file if file sharing is in use.
double TBBasicSingleToDouble(BASICSINGLE OldNumber)
The TBBasicSingleToDouble function converts the Microsoft Basic single
precision number passed in the "Old Number" parameter to a double.
The converted value is returned by the TBBasicSingleToDouble function.
This function is primarily intended to help programmers who wish to
write QWK mail handlers for TriBBS.
SHORT TBCheckForShareExe(void)
The TBCheckForShareExe function checks with DOS to see if SHARE.EXE is
loaded. TBCheckForShareExe will set the IsShare global variable to
the appropriate value. You should note that TBCheckForShareExe is
called by TBInitialize so it is not usually used in an application
program.
LONG TBCompress(unsigned char *cib, SHORT cil,
unsigned char *cob, unsigned char *wb)
The TBCompress function compresses the message pointed to by the "cib"
parameter whose length is passed in the "cil" parameter. The result
27
is placed in the buffer pointed to by the "cob" parameter. The TriBBS
API's compression routine requires a work buffer pointed to by the
"wb" parameter. You should note that the "cib", "cob", and "wb" must
all be at least 40000 bytes in length. The length of the compressed
message is returned by the TBCompress function.
void TBDoubleToBasicSingle(BASICSINGLE *New, double Old)
The TBDoubleToBasicSingle function converts a double passed in the
"Old" parameter into a Microsoft Basic single precision number. The
converted value is returned in the variable location pointed to by
"New". This function is primarily intended to help programmers who
wish to write QWK mail handlers for TriBBS.
SHORT TBGetNextMnnnnIDX(LONG n)
The TBGetNextMnnnnIDX function performs a combination binary and
linear search of the currently opened Mnnnn.IDX file for the location
of the next message that is greater than or equal to the message
number passed in the "n" parameter. If the next message is found,
TBGetNextMnnnnIDX will return the location in the Mnnnn.IDX file of
its location. Otherwise, the TBGetNextMnnnnIDX function will return -
1 to indicate that there is no message greater than or equal to the
passed message number. The Mnnnn.IDX file must be opened with the
TBOpenMnnnnIDX function before the TBGetNextMnnnnIDX function is
called.
char *TBInitialCaps(char *s)
The TBInitialCaps function forces the first character of each word to
upper case and the remaining characters of each word to lower case in
the string pointed to by the "s" parameter. The TBInitialCaps
parameter returns the location passed by the "s" parameter.
void TBInitialize(void)
The TBInitialize function initializes the TriBBS API by performing the
following tasks:
1) Check for SHARE.EXE by calling TBCheckForShareExe.
2) Determine the number of message areas and set the
NumberOfMessageAreas global variable accordingly.
3) Determine the number of file areas and set the
NumberOfFileAreas global variable accordingly.
4) Figure the length of each record in USERS.SUP and set the
28
SupplementalLength global variable accordingly.
5) Allocate any necessary buffer space to read and write the
message area information of the USERS.SUP records.
6) Allocate any necessary buffer space to read and write the file
area information of the USERS.SUP records.
7) Open USERS.DAT.
7) Determine the number of users and set the NumberOfUsers global
variable accordingly.
8) Allocate buffer space and read USERS.IDX into memory.
9) If aliases are allowed, allocate buffer space and read
ALIAS.IDX into memory.
10) Open USERS.SUP.
IMPORTANT: The TBInitialize function should be just about the first
function you call. The behavior of the API functions is undefined if
you try to use them before calling TBInitialize.
IMPORTANT: You must set the value of the Node1sMainDirectory global
variable before calling TBInitialize. If the application program is
run from a directory that contains SYSDAT2.DAT, it is safe to call the
TBReadSYSDAT2DAT function to use SysDat2Dat.Node1sMainDirectory field
to set the Node1sMainDirectory.
IMPORTANT: The TBInitialize function leaves both USERS.DAT and
USERS.SUP in an open state. You should NOT reopen these files unless
you have closed them for some reason in your application program.
Many of the API functions require that these two files be in an open
state so behavior of the API is undefined if either of these files is
closed.
char *TBMakePathName(char *buffer, char *path, char *file)
The TBMakePathName function is used combine a directory, passed in the
the "path" parameter, and a file name, passed in the "file" parameter,
into a single path name. The resulting string will be placed in the
location pointed to by the "buffer" parameter. The TBMakePathName
returns the starting location of the string result.
SHORT TBNumberInFAREADAT(void)
The TBNumberInFAREADAT function returns the number of records in the
FAREA.DAT file. The FAREA.DAT file must already be open for this
function to return the proper value.
29
SHORT TBNumberInMCONFDAT(void)
The TBNumberInMCONFDAT function returns the number of records in the
MCONF.DAT file. The FAREA.DAT file must already be open for this
function to return the proper value.
SHORT TBNumberInMnnnnIDX(void)
The TBNumberInMnnnnIDX function returns the number of records in the
currently open Mnnnn.IDX file. As such, a Mnnnn.IDX file must already
be open for the function to return the proper value.
SHORT TBNumberInMnnnnPTR(void)
The TBNumberInMnnnnPTR function returns the number of records in the
currently open Mnnnn.PTR file. As such, a Mnnnn.PTR file must already
be open for the function to return the proper value.
SHORT TBNumberInUSERSDAT(void)
The TBNumberInUSERSDAT function returns the number of records in the
USERS.DAT file. The USERS.DAT function must already be open for this
function to return the proper value.
void TBOpenFAREADAT(void)
The TBOpenFAREADAT function opens the FAREA.DAT file and assigns the
file's FILE pointer to the FAreaFile global variable.
void TBOpenMCONFDAT(void)
The TBOpenMCONFDAT function opens the MCONF.DAT file and assigns the
file's FILE pointer to the MConfFile global variable.
void TBOpenMnnnnIDX(SHORT n)
The TBOpenMnnnnIDX function opens the Mnnnn.IDX file specified by the
"n" parameter and assigns the file's FILE pointer to the MIdxFile
global variable.
void TBOpenMnnnnPTR(SHORT n)
The TBOpenMnnnnPTR function opens the Mnnnn.PTR file specified by the
30
"n" parameter and assigns the file's FILE pointer to the MPtrFile
global variable.
void TBOpenMnnnnTXT(SHORT n)
The TBOpenMnnnnTXT function opens the Mnnnn.TXT file specified by the
"n" parameter and assigns the file's FILE pointer to the MTxtFile
global variable.
void TBOpenUSERSDAT(void)
The TBOpenUSERSDAT function opens the USERS.DAT file and assigns the
file's FILE pointer to the UsersFile global variable. You should note
that TBInitialize leaves the USERS.DAT file in an open state when it
returns; therefore, it is not normally necessary to reopen USERS.DAT.
void TBOpenUSERSSUP(void)
The TBOpenUSERSSUP function opens the USERS.SUP file and assigns the
file's FILE pointer to the UsersSupFile global variable. You should
note that TBInitialize leaves the USERS.SUP in a state when it
returns; therefore, it is not normally necessary to reopen USERS.SUP.
void TBReadDOORSTMP(char *s)
The TBReadDOORSTMP function opens, reads, and closes the DOORS.TMP
file located in the directory specified by the "s" parameter. The
contents of the DOORS.TMP file will be placed in the DoorsTmpData
global variable.
void TBReadFAREADAT(SHORT n)
The TBReadFAREADAT function reads the record for the file area
specified by the "n" parameter. The contents of the file area's
record will be placed in the FAreaData global variable. The FAREA.DAT
file must be open for this function to work properly.
void TBReadMCONFDAT(SHORT n)
The TBReadMCONFDAT function reads the record for the message
conference specified by the "n" parameter. The contents of the
message conference's record will be placed in the MConfData global
variable. The MCONF.DAT file must be open for this function to work
properly.
31
void TBReadMnnnnIDX(SHORT n)
The TBReadMnnnnIDX function reads the message index record specified
by the "n" parameter. The contents of the message index record will
be placed in the MIdxData global variable. The Mnnnn.IDX file must be
open for this function to work properly.
void TBReadMnnnnPTR(SHORT n)
The TBReadMnnnnPTR function reads the message pointer record specified
by the "n" parameter. The contents of the message pointer record will
be placed in the MPtrData global variable. The Mnnnn.PTR function
must be open for this function to work properly.
void TBReadNODEDAT(void)
The TBReadNODEDAT function opens, reads, and closes the NODE.DAT file
in the current directory. The contents of the NODE.DAT file will be
placed in the NodeData global variable.
void TBReadSYSDAT1DAT(void)
The TBReadSYSDAT1DAT function opens, reads, and closes the SYSDAT1.DAT
file located in the directory pointed to by the Node1sMainDirectory
global variable. The contents of the SYSDAT1.DAT file will be placed
in the SysDat1Data global variable.
void TBReadSYSDAT2DAT(void)
The TBReadSYSDATA2.DAT function opens, reads, and closes the
SYSDAT2.DAT file in the current directory. The contents of the
SYSDAT2.DAT file will be placed in the SysDat2Data global variable.
void TBReadUSERSDAT(SHORT n)
The TBReadUSERSDAT function reads the record for the user specified by
the "n" parameter. The contents of the user's record will be placed
in the UsersData global variable.
void TBReadUSERSSUP(SHORT n)
The TBReadUSERSSUP function reads the supplemental record for the user
specified by the "n" parameter. The contents of the message
conference portion of the user's supplemental record will be placed in
the buffer area pointed to by UsersSupMessages. You should note that
the buffer area pointed to by UsersSupMessages is allocated by
32
TBInitialize. The contents of the file area portion of the user's
supplemental record will be placed in the buffer area pointed to by
UsersSupFiles. You should note that the buffer area pointed to by
UsersSupFiles is allocated by TBInitialize.
SHORT TBSearchMnnnnIDX(LONG n)
The TBSearchMnnnnIDX function searches the currently open Mnnnn.IDX
file for the message whose number is specified by the "n" parameter.
If the TBSearchMnnnnIDX function successfully locates the specified
message, it will return the message's record number. Otherwise, the
TBSearchMnnnnIDX function return -1 to indicate that the specified
message wasn't found.
SHORT TBSearchUSERSIDX(ULONG n)
The TBSearchUSERSIDX function searches USERS.IDX for the CRC specified
by the "n" parameter. If the board allows aliases, the
TBSearchUSERSIDX function will search the ALIAS.IDX file for the
specified CRC if it wasn't found in the USERS.IDX file. If the
TBSearchUSERSIDX function locates the specified CRC, it will return
the user's record number. Otherwise, the TBSearchUSERSIDX function
returns -1 to indicate that the specified CRC wasn't found.
ULONG TBStrCrc32(char *s)
The TBStrCrc32 function calculates and returns the CRC for the string
specified by the "s" parameter.
void TBStripNewline(char *s)
The TBStripNewLine function will strip a newline character (\n), if
any, from the end of the string specified by "s". This function is
handy for stripping newline characters from text files.
void TBStripSpaces(char *s)
The TBStripSpaces function will strip any leading or trailing spaces
from the string specified by "s".
ULONG TBStrNCrc32(char *s, USHORT l)
The TBStrNCrc32 function calculates and returns the CRC for the string
of characters specified by "s" for the length specified by the "l"
function.
33
LONG TBUncompress(unsigned char *cib, SHORT cil,
unsigned char *cob, unsigned char *wb)
The TBUncompress function uncompresses the message pointed to by the
"cib" parameter whose length is passed in the "cil" parameter. The
result is placed in the buffer pointed to by the "cob" parameter. The
TriBBS API's uncompression routine requires a work buffer pointed to
by the "wp" parameter. You should note that the "cib", "cob", and
"wb" buffers must all be at least 40000 bytes in length. The length
of the compressed message is returned by the TBUncompress function.
void TBUpdateFromAndTo(ULONG f, ULONG t, SHORT c)
The TBUpdateFromAndTo function will increment a caller's number of
messages posted for the caller whose CRC is specified by the "f"
parameter. Additionally, this function will increment the waiting
message counter for the caller whose CRC is specified by the "t"
parameter in the message conference specified by the "c" parameter.
void TBWriteDOORSTMP(char *s)
The TBWriteDOORSTMP function opens, writes, and closes the DOORS.TMP
file located in the directory specified by the "s" parameter.
TBWriteDOORSTMP writes the contents of the DoorsTmpData global
variable to DOORS.TMP.
void TBWriteFAREADAT(SHORT n)
The TBWriteFAREADAT function writes the record for the file area
specified by the "n" parameter. TBWriteFAREADAT writes the contents
of the FAreaData global variable to the FAREA.DAT file. The FAREA.DAT
file must be open for this function to work properly.
void TBWriteMCONFDAT(SHORT n)
The TBWriteMCONFDAT function writes the record for the file area
specified by the "n" parameter. TBWriteMCONFDAT writes the contents
of the MConfData global variable to the MCONF.DAT file. The MCONF.DAT
file must be open for this function to work properly.
void TBWriteMnnnnIDX(SHORT n)
The TBWriteMnnnn.IDX function writes the message index record
specified by the "n" parameter. TBWriteMnnnnIDX writes the contents
of the MIdxData global variable to the Mnnnn.IDX file. The Mnnnn.IDX
34
file must be open for this function to work properly.
void TBWriteMnnnnPTR(SHORT n)
The TBWriteMnnnnPTR function writes the message pointer record
specified by the "n" parameter. TBWriteMnnnnPTR writes the contents
of the MPtrData global variable to the Mnnnn.PTR file. The Mnnnn.PTR
file must be open for this function to work properly.
void TBWriteNODEDAT(void)
The TBWriteNODEDAT function opens, writes, and closes the NODE.DAT
file in the current directory. TBWriteNODEDAT writes the contents of
the NodeData global variable to the NODE.DAT file.
void TBWriteSYSDAT1DAT(void)
The TBWriteSYSDATA1DAT function opens, writes, and closes the
SYSDAT1.DAT file located in the directory pointed to by the
Node1sMainDirectory global variable. TBWriteSYSDAT1DAT writes the
contents of the SysDat1Data global variable to the SYSDAT1.DAT file.
void TBWriteUSERSDAT(SHORT n)
The TBWriteUSERSDAT function writes the user record specified by the
"n" parameter. TBWriteUSERSDAT writes the contents of the UsersData
global variable to the USERS.DAT file.
void TBWriteUSERSSUP(SHORT n)
The TBWriteUSERSSUP function writes the supplemental record for the
user specified by the "n" parameter. The contents of the message
conference portion of the user's supplemental record is written from
the buffer area pointed to by UsersSupMessages. You should note that
the buffer area pointed to by UsersSupMessages is allocated by
TBInitialize. The contents of the file area portion of the user's
supplemental record is written from the buffer area pointed to by
UsersSupFiles. You should note that the buffer area pointed to by
UsersSupFiles is allocated by TBInitialize.
35
MISCELLANEOUS IMPLEMENTATION NOTES
How Files Are Opened
--------------------
The TriBBS API opens all files as binary files and for read/write
access. Additionally, if file sharing is detected, the TriBBS API
uses the SH_DENYNO sharing mode when opening the files.
Record Numbers
--------------
When passing a record number for any of the TriBBS API functions, you
should be aware that the TriBBS API numbers records from 1 to n, where
"n" is the total number of records in the file.
Calculating CRCs
----------------
TriBBS uses 32-bit CRCs for a number of user related functions. The
correct CRC can be calculated using the following method:
.
.
.
char s[81];
ULONG ucrc;
.
.
.
TBStripSpaces(s);
TBInitialCaps(s);
ucrc = TBStrCrc32(s);
.
.
.
The above examples assume the the user's name has been assigned to the
"s" string variable.
36
DEMO PROGRAMS
There are two demo programs supplied with the TriBBS API: demo1.c and
demo2.c. demo1.c is a simple program that allows the user to view the
messages in a specified message conference. It can be compiled with
one of the following command lines:
=====================================================================
Compiler Command Line
---------------------------------------------------------------------
Borland C++ bcc -ml demo1.c tbapibc.lib
Symantec C++ sc -ml -a1 demo1.c tbapisc.lib
Turbo C++ tcc -ml demo1.c tbapitc.lib
=====================================================================
demo2.c is a slightly more complex program that allows the user to
insert the contents of a text file as a message to a specified user.
It can be compiled with one of the following command lines:
=====================================================================
Compiler Command Line
---------------------------------------------------------------------
Borland C++ bcc -ml demo2.c tbapibc.lib
Symantec C++ sc -ml -a1 demo2.c tbapisc.lib
Turbo C++ tcc -ml demo2.c tbapitc.lib
=====================================================================
37
SUPPORT
Because the TriBBS API is written for the intermediate to advanced
C/C++ programmer, support will only be provided for questions that
related to the TriBBS API only. Support will not be given for general
C/C++ programming questions.
38
