informis
/
textfiles
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
textfiles/computers/DOCUMENTATION/ckit.txt

4682 lines
182 KiB
Plaintext
Raw Normal View History

Initial commit
2021-04-15 11:31:59 -07:00
C-KIT DOOR building Toolkit Library
Version 2.50
Reference Manual
Distributed By
Data-Comp Information Systems
P.O. Box 5895
Maryville, Tenn. 37802-5895
(615) 982-6512 (USR HST Dual Standard V.32bis)
Copyright (c) 1989, 90, 91, 92 Rickie W. Belitz
Introduction
Introduction
C-KIT Library is an extensive library of C runtime routines that
allow easy door program implementation using PCBoard 12.0 through
14.x, WILDCAT! systems, (all versions), GAP BBS, SPITFIRE BBS 3.0
and other systems using standard DOOR.SYS file along with RBBS-PC,
QuickBBS, Remote Access and other systems using DORINFOx.DEF files.
C-KIT 2.01 will also work properly with MikeBBS (MBBS) v9.9 and above.
CKIT will automatically work with the above system. For systems
not listed above, CKIT can deal with them in one of two ways.
CKIT can utilize a file called GENERIC.SYS. This is for
creating a system file for a system CKIT does not support. See
section on GENERIC.SYS for more information. In addition,
CKIT will also accept a pointer to a structure that contains the
needed information for CKIT to operate. This could be the result
of your program reading ANY BBS's system file. This structure will
allow C-KIT to work on ANY BBS system, providing the door author
reads the BBS file himself.
Some other C-KIT Library's features include interrupt driven I/O,
16550AN UART support, FOSSIL support, Digiboard Support,provides
information available from the PCBoard .sys files, database files,
multi-node support (file sharing), multi-BBS support, local sysop
function keys and many more utilities are included for the door
author.
The C-KIT Library routines are written entirely in Assembly language
using SLR's Optasm. The routines make use of C library functions
when possible and are compatible with Microsoft C, Microsoft QuickC,
TURBO C, and TURBO C++.
C-KIT Library supports the small, medium and large models.
Microsoft is a registered trademark, and QuickC is a trademark of
the Microsoft Corporation.
TURBO C is a registered trademark of Borland International Inc.
TURBO C++ is a registered trademark of Borland International Inc.
PCBoard is a registered trademark of Clark Development Company.
WILDCAT! is a registered trademark of Mustang Software.
SPITFIRE is a registered trademark of Buffalo Creek Software
RBBS-PC is copyright (c) Tom Mack, Capital PC Software Exchange
QUICKBBS is copyright (c) Adam Hudson
REMOTE ACCESS is copyright (c) Andrew Milner, Continental Software
MBBS is copyright (c) Mike Anderson
DigiBoard is copyright (c) DigiBoard, Eden Prarie, MN
Registration
The unregistered library will display "Unregistered copy etc." as
part of the signoff message. The registered version eliminates this
signoff msg at the time the door is closed. Please see the
registration information below. A lot of effort has gone into C-KIT,
to make sure it would operate reliably and with little effort
on the part of the door author. If you find the program of use, please
register it and help support the Shareware method of program
distribution. Registering will also help fund further development
of the libraries.
C-KIT is being distributed as Shareware.
The registration includes:
<20> A disk with the latest version of C-KIT, registered to you.
. Some small utility programs for easy door testing w/source.
<20> Self-Registration program for future releases of C-KIT
<20> Technical support via electronic mail
. A LARGE memory model of C-KIT. (download from Data-Comp BBS)
(The LARGE model will also work as a HUGE model)
. Access to source code for reading other system files as they
become available. All PCBoard source files are now available.
For more information see the addresses, phone numbers listed
at the end of this document.
Global Variables
Global Functions/Variable Naming Conventions
The C-KIT Library defines a number of variables and functions
in the c-kit header file. These have to be made public for
the linker to be able to resolve references to them. Beginning
in C-KIT 2.0 ALL functions/variables available from the library
begin with the prefix "ck_". This will help prevent any naming
conflicts with other globals in your source code. Knowing that
all C-KIT's names begin with "ck_", you can prevent any collisions
with the public names contained in the library. If this is of
little concern to you or if you do not like the names used in
the library because of this, then you can simply re-define
the names to any name you desire. OLDCKIT.H does exactly this
for previous users of the library. OLDCKIT.H re-defines the
new names to the old names used in the library. If you included
OLDCKIT.H in your present source code, then the new library
names would work with no other changes to your present source code.
Example: Name desired Library Name
======= =========== ============
#define s_puts ck_s_puts
#define DUMP_USER ck_DUMP_USER
#define color ck_color
#define newline ck_newline
#define get_cmdline ck_get_cmdline
These would cause the compiler to reference the new name for all
references to old name.
do {
color(green);
s_puts("Command? ", NULL);
get_cmdline(); /* read input into 'cmdline' */
newline();
} while( (DUMP_USER != TRUE) && ( strlen(cmdline) == 0 ));
See OLDCKIT.H and CKITDEMO.C, CKITDEMO.H.
NOTE: The ONLY variable that does not have the "ck_" prefix is
the progname[]; array name in the CKIT.H file.
Global Variables
Global Variables used by all BBS systems
The C-KIT Library defines a number of variables in the ckit.h
header file. Through proper use, these variables allow the
programmer to customize the C-KIT Library functions to meet
particular application program's needs.
ck_DUMP_USER
-------------------------------------------------------------------
Defined As: short ck_DUMP_USER;
Description: This variable will be set if the user hangs up,
his/her time runs out, carrier is lost, or if the
sysop wants to return the user to the BBS system using
function key F8. You should check this flag in all
major loops in the door program.
ck_FORCEOFFHOOK
-------------------------------------------------------------------
Defined As: short ck_FORCEOFFHOOK
Description: This variable should be set to TRUE or FALSE in the
CKIT.H file. If this variable is TRUE, the modem
will be placed OFF-HOOK if carrier is dropped in the
door before returning to the system. If FORCEOFFHOOK
is false, the door will not take the modem off-hook.
See CKIT.H
ck_USERFILE
-------------------------------------------------------------------
Defined As: short ck_USERSFILE
Description: This variable should be set to TRUE or FALSE in the
CKIT.H file. If this variable is TRUE, C-KIT will
open the Users file and those variables will be
available. If not, only the PCBOARD.SYS file will be
opened and the user information will not be available.
See CKIT.H.
ck_option
------------------------------------------------------------------
Defined As: unsigned char ck_option;
Description: This variable is set to indicate how the user was
logged off the system. There are 5 macro's in the
CKIT header file that describes each.
#define EXITDOOR 0 Normal door exit
#define NOCARRIER 1 Dropped carrier*
#define TIMEOUT 2 Keyboard timeout*
#define SYSOP_O 3 Sysop request*
#define SYSTEMTIME 4 System time expired*
#define LOGOFF 5 User logged off
* These are normally handled internally by C-KIT
COMPATIBILITY Global Variables
ck_silent pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_silent;
Description: This variable when TRUE will prevent keyboard timeout
beeps from being sent to the local console.
It can be controlled via your program.
ck_NO_FKEYS pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_NO_FKEYS;
Description: This variable when TRUE will disable the local
sysop keyboard F-keys and ALT keys except for
ALT-H. Default is FALSE. (F-keys enabled)
ck_NOSYSTEM pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_NOSYSTEM;
Description: This variable when TRUE will tell open_door()
to not attempt a file open but to read it's
information from a data structure. Used for
supporting BBS's not supported by C-kit.
See open_door() for details.
ck_NO_STATUS pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: short ck_NO_STATUS;
Description: When TRUE, tells CKIT not to create a status line.
Must be set to desired state BEFORE open_door() is
called. Once open_door() is called, it cannot be
changed.
ck_logoff_color pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_logoff_color;
Description: This variable used to specifiy the color of the
exit_msg[] string. (See below).
See the ckit.h file for colors available.
Example: ck_logoff_color = (green).
NOTE: If not specified, the default color is violet.
ck_exit_msg pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_exit_msg[40];
Description: THIS VARIABLE IS NO LONGER AVAILABLE IN CKIT2.0
PLEASE SEE **ck_logoff_msgs.
ck_logoff_msg pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_logoff_msg[40];
Description: THIS VARIABLE IS NO LONGER AVAILABLE IN CKIT2.0
PLEASE SEE **ck_logoff_msgs.
COMPATIBILITY Global Variables
ck_display pcboard.sys
------------------------------------------------------------------
Defined As: short ck_display;
Description: This variable is set to indicate the status of the
local BBS display.
file. TRUE/FALSE 0 = No, 1 = yes.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_printer pcboard.sys
------------------------------------------------------------------
Defined As: short ck_printer;
Description: This variable is set to indicate the status of the
BBS printer.
TRUE/FALSE 0 = No, 1 = yes.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_pagebell pcboard.sys
------------------------------------------------------------------
Defined As: short ck_pagebell;
Description: This variable is set to indicate the status of the
BBS pagebell.
TRUE/FALSE 0 = No, 1 = yes.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_callalarm pcboard.sys
------------------------------------------------------------------
Defined As: short ck_callalarm;
Description: This variable is set to indicate the status of the
BBS caller alarm.
TRUE/FALSE 0 = No, 1 = yes.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_PCB door.sys pcboard.sys wildcat! dorinfx.def
------------------------------------------------------------------
Defined As: short ck_PCB;
Description: This variable is set to indicate whether C-KIT found
a PCBoard.sys file.
TRUE/FALSE 0 = No, 1 = yes.
ck_GAP door.sys pcboard.sys wildcat! dorinfx.def
------------------------------------------------------------------
Defined As: short ck_GAP;
Description: This variable is set to indicate whether C-KIT found
a door.sys file.
TRUE/FALSE 0 = No, 1 = yes.
ck_PCB12 door.sys pcboard.sys wildcat! dorinfx.def
------------------------------------------------------------------
Defined As: short ck_PCB12;
Description: This variable is set to indicate whether C-KIT found
a PCBoard version 12.0 pcboard.sys file or not.
TRUE/FALSE 0 = No, 1 = yes.
COMPATIBILITY Global Variables
ck_WILDCAT door.sys pcboard.sys wildcat! dorinfx.def
------------------------------------------------------------------
Defined As: short ck_WILDCAT;
Description: This variable is set to indicate whether C-KIT found
a WILDCAT callinfo.bbs file or not.
TRUE/FALSE 0 = No, 1 = yes.
ck_RBBS door.sys pcboard.sys wildcat! dorinfx.def
------------------------------------------------------------------
Defined As: short ck_RBBS;
Description: This variable is set to indicate whether C-KIT found
a RBBS type DORINFOx.DEF file or not.
TRUE/FALSE 0 = No, 1 = yes.
ck_GENERIC any BBS system
------------------------------------------------------------------
Defined As: short ck_GENERIC;
Description: This variable is set to indicate whether C-KIT found
a GENERIC.SYS file.
TRUE/FALSE 0 = No, 1 = yes.
If ck_GENERIC is TRUE you, the door author, should stop and
ask the user for his/herfirst and last name.
C-kit no longer does this for you.
if(GENERIC) {
sprintf("\nPlease enter first and last name (MAX 25) ->");
get_cmdline_raw(45);
strncpy(ck_fullname, cmdline, 25);
}
ck_FOSSIL any BBS system
------------------------------------------------------------------
Defined As: short ck_FOSSIL;
Description: This variable is set to indicate whether a FOSSIL
driver is in use.
TRUE/FALSE 0 = No, 1 = yes.
You can use this to test for conflicts with your door operations
that may not support a fossil driver. For instance in shelling
out to Zmodem for a file xfer.
ck_Digiboard any BBS system
------------------------------------------------------------------
Defined As: short ck_Digiboard;
Description: This variable is set to indicate whether the
Digiboard Intelligent Async driver is in use.
TRUE/FALSE 0 = No, 1 = yes.
You can use this to test for conflicts with your door operations
that may not support a Digiboard. For instance in shelling
out to Zmodem for a file xfer which doesn't support the Digiboard.
COMPATIBILITY Global Variables
ck_graphics pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_graphics;
Description: This variable is set to indicate the status of the
user graphics mode.
Supports ANSI X3.64 standard commands.
TRUE/FALSE 0 = No, 1 = yes.
ck_non_ibm pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_non_ibm;
Description: This variable is set to indicate whether the caller
is using 7 bits instead of 8 bits. Using 7 bits
doesn't allow for IBM graphic characters above
128 to be displayed correctly.
TRUE/FALSE 0 = No, 1 = yes.
ck_error_connection pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: short ck_error_connection;
Description: This variable is set to indicate the status of the
modem error_connection.
TRUE/FALSE 0 = No, 1 = yes.
COMPATIBILITY Global Variables
ck_local pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_local;
Description: This variable is set to indicate the status of the
local/remote operation of door.
TRUE/FALSE 0 = No, 1 = yes.
ck_expert pcboard.sys door.sys
------------------------------------------------------------------
Defined As: short ck_expert;
Description: This variable is set to indicate the status of the
expert/novice mode of user.
TRUE/FALSE 0 = No, 1 = yes.
ck_event_active pcboard.sys
------------------------------------------------------------------
Defined As: short ck_event_active;
Description: This variable is set to indicate the status of the
system event.
TRUE/FALSE 0 = No, 1 = yes.
Useful with 14.x pcboard.sys usage only
ck_event_slide pcboard.sys
------------------------------------------------------------------
Defined As: short ck_event_slide;
Description: This variable is set to indicate whether the system
event can be moved or not.
TRUE/FALSE 0 = No, 1 = yes.
Useful with 14.x pcboard.sys useage only
ck_sysop_next pcboard.sys
------------------------------------------------------------------
Defined As: char ck_sysop_next[2];
Description: This C string indicates the status of the
Sysop Next flag. N = sysop next, X = exit to system,
space = nothing pending.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_netchat pcboard.sys
------------------------------------------------------------------
Defined As: char ck_netchat[2];
Description: This C string indicates the status of the
the user's netchat. U = Unavailable,
A = available.
Useful with 12.0 - > 14.x pcboard.sys usage only
ck_mem_msg pcboard.sys 14.5
------------------------------------------------------------------
Defined As: long ck_mem_msg;
Description: Memorized message pointer. This is in it's raw
form. To use it, you will need to convert from
QBasic single (MKS$) to IEEE long. Conversion
routines are available on the support BBS.
COMPATIBILITY Global Variables
ck_aport pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_aport[2];
Description: This C string is an ASCII string of the com
port in use as determined. (if using a Digiboard
it will indicate the port found in the system file)
See also ck_port.
ck_bps_open pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_bps_open[6];
Description: This C string is an ASCII string of the
BBS's DTE to modem baud rate.
Not available with PCBoard 12.0
ck_baud_rate pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_baud_rate[6];
Description: This C string is an ASCII string of the
callers baud rate. (DCE rate)
ck_uart_base pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_uart_base;
Description: This contains the UART's base address that C-KIT is
currently using either as the default or passed
by the PORT command.
ck_irq pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_irq;
Description: This contains the IRQ that C-KIT is
currently using either as the default or
passed by the PORT command.
ck_firstname pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_firstname[16];
Description: This C string is an ASCII string of the
caller first name.
ck_password pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_password[13];
Description: This C string is an ASCII string of the
caller password.
ck_fullname pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
defined As: char ck_fullname[26];
Description: This C string is an ASCII string of the
caller fullname.
COMPATIBILITY Global Variables
ck_page_length pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: BYTE ck_page_length;
Description: Page length of user. This information is not
available with PCBoard 12.0 so there is a default
of 23. The door author can adjust as desired.
This is also used by display_file(). Setting to
0 equals continous. (NON-STOP).
ck_language pcboard.sys
------------------------------------------------------------------
defined As: char ck_language[5];
Description: This C string is an ASCII string of the
caller language.
Space = English
ck_time_logged pcboard.sys door.sys wildcat!
------------------------------------------------------------------
defined As: char ck_time_logged[6];
Description: This C string is an ASCII string of the time
caller logged onto the BBS.
ck_event_time pcboard.sys door.sys
------------------------------------------------------------------
defined As: char ck_event_time[6];
Description: This C string is an ASCII string of the
system event time of the BBS as HH:MM.
Not available with PCBoard 12.0
ck_time_on pcboard.sys
------------------------------------------------------------------
Defined As: short ck_time_on;
Description: This variable indicates the time in minutes
past midnight the user logged on.
ck_prev_used pcboard.sys
------------------------------------------------------------------
Defined As: short ck_prev_used; NOTE: N/A for PCBoard 12.0
Description: This variable indicates the time in minutes
used in previous calls today.
ck_user_record pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: unsigned ck_short user_record;
Description: This variable holds the user record number.
ck_dload_limit pcboard.sys
------------------------------------------------------------------
Defined As: short ck_dload_limit;
Description: This variable holds the user's allowed dload Kbytes
on the system.
COMPATIBILITY Global Variables
ck_time_limit pcboard.sys
------------------------------------------------------------------
Defined As: short ck_time_limit;
Description: This variable holds the user BBS system time limit
in minutes.
ck_time_credit pcboard.sys
------------------------------------------------------------------
Defined As: short ck_time_credit;
Description: This variable holds the time the user has been given
(pos or neg.) that will be added to pcboard.sys when
returned to the bulletin board.
ck_time_credit_old pcboard.sys
------------------------------------------------------------------
Defined As: short ck_time_credit_old;
Description: This variable holds the time credit in minutes
(pos or neg.) that was originally found in the
pcboard.sys when the door was opened. This will
be added with the time_credit when the door is
closed.
ck_time_added pcboard.sys
------------------------------------------------------------------
Defined As: short ck_time_added;
Description: This variable holds the area user time added so
far in minutes.
ck_min_left pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: short ck_min_left;
Description: This variable holds the user time left on system
at the time the door was opened. (static).
If you want the time remaining in the door, you
would need to call the mins_left_system() procedure.
ck_min_remaining door.sys
------------------------------------------------------------------
Defined As: char ck_min_remaining[6];
Description: This is the same thing as min_left. It is
available as a string only if door.sys is used.
See min_left above. (static)
ck_sec_remaining door.sys
------------------------------------------------------------------
Defined As: char ck_sec_remaining[6];
Description: This variable holds the seconds left on system
at the time the door was opened. (static).
If you want the time remaining in the door, you
would need to call the mins_left_system() procedure.
COMPATIBILITY Global Variables
ck_port pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: short ck_port;
Description: This variable holds the com port in use.
Equal to 0 if local mode. If using a Digiboard
it will indicate the Digiboard channel in use.
ck_node[] pcboard.sys door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_node[3]; NOTE: N/A for PCBoard 12.0
Description: This string holds the node in use.
Equal to space if no network active.
*ck_conferences door.sys wildcat!
------------------------------------------------------------------
Defined As: char *ck_conferences;
Description: This a pointer to a string of conferences/forums
the user is registered in.
ck_parity door.sys wildcat!
------------------------------------------------------------------
Defined As: short ck_parity;
Description: Represent the ASCII character of parity in use.
Note this NOT a string. It will either be ASCII
7 (0x37) or 8 (0x38).
ck_protocol pcboard.sys door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_protocol[15]
Description: String containing the users current protocol setting.
PCBoard/GAP/SPITFIRE will only list the 1st char. of the
protocol, WILDCAT! will give the entire protocol
name.
ck_security_level door.sys wildcat! dorinfox.def
------------------------------------------------------------------
Defined As: char ck_security_level[5]
Description: String containing the users security level.
See also ck_user.sec below
ck_current_conf door.sys
------------------------------------------------------------------
Defined As: short ck_current_conf;
Description: Conference number user just exited from to door.
ck_caller_bday door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_caller_bday[8];
Description: String containing the callers birthday.
as MM/DD/YY. Not available with PCBoard systems.
COMPATIBILITY Global Variables
ck_main_dir door.sys
------------------------------------------------------------------
Defined As: char ck_main_dir[80];
Description: String containing the path to the MAIN directory
wherever the users file is located.
ck_gen_dir door.sys
------------------------------------------------------------------
Defined As: char ck_gen_dir[80];
Description: String containing the path to the GEN directory.
ck_sysop_name door.sys dorinfox.def
------------------------------------------------------------------
Defined As: char ck_sysop_name[15];
Description: String containing the sysop's first name.
ck_sysop_alias door.sys
------------------------------------------------------------------
Defined As: char ck_sysop_alias[15];
Description: String containing the sysop's alias name.
ck_ansi_ng door.sys
------------------------------------------------------------------
Defined As: short ck_ansi_ng;
Description: ANSI supported and caller using NG mode.
TRUE/FALSE 0 = No, 1 = yes.
ck_record_lock door.sys
------------------------------------------------------------------
Defined As: short ck_record_lock;
Description: User record locking.
TRUE/FALSE 0 = No, 1 = yes.
ck_default_color door.sys
------------------------------------------------------------------
Defined As: char ck_default_color[2];
Description: String containing system's default color
ck_last_called door.sys
------------------------------------------------------------------
Defined As: char ck_last_called[6];
Description: String containing user last time called.
HH:MM.
ck_last_file_scan door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_last_file_scan[9];
Description: String containing user last new files scan as
MM/DD/YY.
COMPATIBILITY Global Variables
ck_daily_files door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_daily_files[4];
Description: String containing number of files user has download
so far today.
ck_daily_bytes door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_daily_bytes[4];
Description: String containing number of K bytes user downloaded
so far today.
ck_total_doors door.sys
------------------------------------------------------------------
Defined As: char ck_total_doors[4];
Description: String containing number of doors user has opened.
ck_msgs_left door.sys
------------------------------------------------------------------
Defined As: char ck_msgs_left[4];
Description: String containing total number of messages left by
user.
ck_max_files door.sys
------------------------------------------------------------------
Defined As: char ck_max_files[4];
Description: String containing Max. number of files allowed.
ck_upload_Kbytes door.sys
------------------------------------------------------------------
Defined As: char ck_upload_Kbyte[10];
Description: String containing total "K" bytes uploaded.
ck_download_Kbytes door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_download_Kbyte[10];
Description: String containing total "K" bytes downloaded.
ck_dload_total door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_dload_total[5];
Description: String containing total files downloaded.
ck_upload_total door.sys wildcat!
------------------------------------------------------------------
Defined As: char ck_upload_total[5];
Description: String containing total files uploaded.
COMPATIBILITY Global Variables
ck_monitor_type wildcat!
------------------------------------------------------------------
Defined As: char ck_monitor_type[5];
Description: String containing monitor type MONO/COLOR
NOTE: C-KIT will set graphics true/false
depending on this setting. see Graphics above.
ck_max_sec wildcat!
------------------------------------------------------------------
Defined As: char ck_max_sec[5];
Description: String containing a systems maximum user
security level for WILDCAT! systems.
ck_high_msg wildcat!
------------------------------------------------------------------
Defined As: char ck_high_msg[10]
Description: String containing the users highest message
read.
ck_name_in_use wildcat!
------------------------------------------------------------------
Defined As: BYTE ck_name_in_use
Description: Set to TRUE/FALSE. This is called already_connected
in the WILDCAT def. file.
ck_door_opened wildcat!
------------------------------------------------------------------
Defined As: short ck_door_opened
Description: Which door was opened to run your door.
ck_BBSname dorinfox.def
------------------------------------------------------------------
Defined As: char ck_BBSname[63];
Description: Name of the BBS system running the door.
ck_pcbsysbuf pcboard.sys
------------------------------------------------------------------
Defined As: BYTE *ck_pcbsysbuf;
Description: This is a pointer to the buffer holding the
pcboard.sys file read. This buffer will be
written back to pcboard.sys when close_door()
is called. It is provided so a door author
can manipulate any byte in the pcboard.sys
file and will in turn be written back to the
pcboard.sys file.
Global Variables
These are part of the structure "ck_user" as defined in the CKIT.H file.
All these user structure members are available only if the door author
specifies USERFILES True (see above) and the system is PCBoard version
14.x. Some but not all members are available if the author specifies
USERFILE True and used with Pcboard version 12.0. If the door author
does not specify USERFILE's file TRUE, then do not use this structure.
If you plan on using this structure and/or update_user(), you
must using WORD alignment when compiling your door program for
CKIT < version 2.0. For CKIT versions 2.0 and greater, you must
use BYTE alignment.
ck_user.name See also fullname
------------------------------------------------------------------
Defined As: char ck_user.name[26];
Description: This C string is an ASCII string of the
caller's fullname.
ck_user.city
------------------------------------------------------------------
Defined As: char ck_user.city[25];
Description: This C string is an ASCII string of the
caller's city, state.
ck_user.pwrd
------------------------------------------------------------------
Defined As: char ck_user.pwrd[13];
Description: This C string is an ASCII string of the
caller's password.
ck_user.bphone
------------------------------------------------------------------
Defined As: char ck_user.bphone[14];
Description: This C string is an ASCII string of the caller's
business phone number.
ck_user.phone
------------------------------------------------------------------
Defined As: char ck_user.phone[14];
Description: This C string is an ASCII string of the caller's
home phone number.
ck_user.last_date
------------------------------------------------------------------
Defined As: char ck_user.last_date[7];
Description: This C string is an ASCII string of the caller's
last date on system.
Format is YYMMDD
Global Variables
These are part of the structure "ck_user" as defined in the
CKIT.H file. Information available from user file.
ck_user.last_time
------------------------------------------------------------------
Defined As: char ck_user.last_time[6];
Description: This C string is an ASCII string of the caller's
last time on system.
Format is HH:MM
ck_user.expert See also expert above
------------------------------------------------------------------
Defined As: char user.expert[2];
Description: This C string is an ASCII string of the caller
expert mode ( Y or N )
ck_user.protocol
------------------------------------------------------------------
Defined As: char ck_user.protocol[2];
Description: This C string is an ASCII string of the caller
protocol type in effect.
ck_user.packed_byte
------------------------------------------------------------------
Defined As: BYTE ck_user.packed_byte;
Description: This holds the PCBoard packed byte to indicate
various user options in the user file.
ck_user.filedate see also _last_file_scan
------------------------------------------------------------------
Defined As: char ck_user.filedate[7];
Description: This C string is an ASCII string of the caller
last DIR scan. in YYMMDD format
ck_user.security
------------------------------------------------------------------
Defined As: BYTE ck_user.security;
Description: This variable holds the user security level as
determined from USER file.
ck_user.total_calls
------------------------------------------------------------------
Defined As: short ck_user.total_calls;
Description: This variable holds the user total calls on system.
ck_user.page_length see also page_length
------------------------------------------------------------------
Defined As: BYTE ck_user.page_length;
Description: This variable holds the user page setting.
ck_user.uploads see also upload_total
------------------------------------------------------------------
Defined As: short ck_user.uploads;
Description: This variable holds the user total uploads.
Global Variables
These are part of the structure "ck_user" as defined in the
CKIT.H file. Information available from user file.
ck_user.downloads see also dload_total
------------------------------------------------------------------
Defined As: short ck_user.downloads;
Description: This variable holds the user total downloads.
ck_user.dload_bytes see also dload_total
------------------------------------------------------------------
Defined As: double ck_user.dload_bytes;
Description: This variable holds the user total DAILY
downloaded bytes determined from USER file.
This variable is in it's raw Qbasic MKD$.
To be of use to C, it needs to be converted
from QBASIC real to C's IEEE float.
The conversion routines/examples are available from
the support BBS. Before changing this variable
it should also be converted back to a QBASIC real.
ck_user.comment1
------------------------------------------------------------------
Defined As: char ck_user.comment1[31];
Description: This C string is an ASCII string of the caller
user maintained comment.
ck_user.comment2
------------------------------------------------------------------
Defined As: char ck_user.comment2[32];
Description: This C string is an ASCII string of the caller
sysop maintained comment.
ck_user.time_used
------------------------------------------------------------------
Defined As: short ck_user.time_used;
Description: Elapsed time on system. (minutes)
ck_user.expire_date
------------------------------------------------------------------
Defined As: char ck_user.expire_date[7];
Description: This C string is an ASCII string of the caller
expiration date in YYMMDD format.
ck_user.expire_level
------------------------------------------------------------------
Defined As: BYTE ck_user.expire_level;
Description: This is the users expired security level read
from pcboard users file.
Global Variables
These are part of the structure "ck_user" as defined in the
CKIT.H file. Information available from user file.
ck_user.current_conf
------------------------------------------------------------------
Defined As: BYTE ck_user.current_conf;
Description: This is the last conference user was in read
from pcboard users file.
ck_user.conferences
------------------------------------------------------------------
Defined As: BYTE ck_user.conferences[6]
Description: This is 5 bytes containing the Bitmaps of the
conferences the user is registered in.
They are in their "raw" form and will have to
be decoded before used and encoded before
storing. Routines are available from the
support BBS.
ck_user.expire_conf
------------------------------------------------------------------
Defined As: BYTE ck_user.expire_conf[6]
Description: This is 5 bytes containing the Bitmaps of the
conferences the user is registered in after
his/her expiration date.
They are in their "raw" form and will have to
be decoded before used and encoded before
storing. Routines are available from the
support BBS.
ck_user.scan_conf
------------------------------------------------------------------
Defined As: BYTE ck_user.scan_conf[6]
Description: This is 5 bytes containing the Bitmaps of the
conferences the user is registered in and
desires a mail scan.
They are in their "raw" form and will have to
be decoded before used and encoded before
storing. Routines are available from the
support BBS.
ck_user.dload_total see also dload_total
------------------------------------------------------------------
Defined As: double ck_user.dload_total
Description: This variable holds the user total downloaded
bytes determined from USER file. This variable
is in it's raw Qbasic MKD$. To be of use to
C, it needs to be converted from QBASIC real
to C's IEEE float. The conversion/example routines
are available from the support BBS. Before changing
this variable it should also be converted back to a
QBASIC real.
Global Variables
These are part of the structure "ck_user" as defined in the
CKIT.H file. Information available from user file.
ck_user.upload_total see also dload_total
------------------------------------------------------------------
Defined As: double ck_user.upload_total;
Description: This variable holds the user total uploaded
bytes determined from USER file. This variable
is in it's raw Qbasic MKD$. To be of use to
C, it needs to be converted from QBASIC real
to C's IEEE float. The conversion/example routines
are available from the support BBS. Before changing
this variable it should also be converted back to a
QBASIC real.
ck_user.delete_user
------------------------------------------------------------------
Defined As: char ck_user.delete_user[2];
Description: This C string is an ASCII string of delete
user flag. (Y or N)
ck_user.last_msg_read see also dload_total
------------------------------------------------------------------
Defined As: long ck_user.last_msg_read;
Description: This variable holds the user last message read
in the main conference. This variable
is in it's raw Qbasic MKS$. To be of use to
C, it needs to be converted from QBASIC real
to C's IEEE float. The conversion/example routines
are available from the support BBS. Before changing
this variable it should also be converted back to a
QBASIC real.
ck_user.last_read see also dload_total
------------------------------------------------------------------
Defined As: long ck_user.last_read[39]
Description: This variable array contains the last
read message pointers for conferences 0-39.
They are in raw Qbasic MKS$. To be of use to
C, it needs to be converted from QBASIC real
to C's IEEE float. The conversion/example routines
are available from the support BBS. Before changing
this variable it should also be converted back to a
QBASIC real.
System Global Variables
These variables are available with any BBS system. Some are used
for customization of your door program and MUST be defined.
Others using are meant to be read only variables available globally.
Some are are used in conjuction with high level functions as noted.
char progname[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char progname[21];
Description: Set this to your Door program name. It will be
display on the status line on the sysop screen.
MAXIMUM length is 20 characters! Do not exceed this!
NOTE: THIS IS NOT AN OPTION. You must define progname[] even if
you do not plan on using it.
ck_cmdline[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: BYTE ck_cmdline[128]
Description: This is used by get_cmdline(), to read the user
keyboard input to.
Please see the CKITDEMO.C for usage.
See Also: ck_get_cmdline();
ck_par[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char ck_par[128];
Description: This is used by get_nextpar(), to parse stacked
commands to.
Please see CKITDEMO.C for usage.
See Also: ck_get_cmdline(), ck_get_nextpar();
ck_scan_code pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: size_t ck_scan_code;
Description: This variable will if NONZERO contain the key_code
of any NON-STANDARD keys on the IBM keyboard.
(F1-F10, PgDn, PgUp etc). The remote user must be
in some type of terminal program that will allow
passing the keycodes. Qmodem in "DOORWAY" mode
is one example.
Please see ck_input(), ck_get_cmdline() and
ckitdemo.c for examples.
See Also: ck_get_cmdline();
ck_key_source pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: short ck_key_source;
Description: This variable will a 1 if the input from get_cmdline()
came from the LOCAL console or a 2 if it came from
a REMOTE console.
See Also: ck_get_cmdline(), ck_input()
System Global Variables
ck_linenum pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: short ck_linenum;
Description: This variable be will incremented each time a call
to newline() is made.
See Also: ck_page_length, ck_newline()
ck_logoff_msgs pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char **ck_logoff_msgs;
Description:
This is pointer to an array of pointers that will be printed at the
time the door is closed. The array of pointers has a length of 6
elements. Which message is printed depends on the value of ck_option.
The code looks for an array of pointers to the exit messages and uses
the ck_option variable to pick which one to print. This pointer to
the array of pointers allows you to define your own array of pointers
to the 6 exit messages. This allows the messages to be of any length
and which message printed will be based on the value of ck_option (0-5)
respectfully. See also the variable ck_option.
They must be in this order.
Example to create your own log off messages of ANY size.
In your source code:
char option0[] = "New Returning to system msg, any size\n";
char option1[] = "New CARRIER DROPPED! msg, any size\n";
char option2[] = "New Keyboard Timeout! msg, any size\n";
char option3[] = "New Sysop requests return to BBS msg, any size\n";
char option4[] = "New System time has expired! msg, any size\n";
char option5[] = "New Thanks for calling! msg, any size";
static char *logoffs[6] = { /* create array of ptrs */
option0,
option1,
option2,
option3,
option4,
option5,
};
ck_logoff_msgs = &logoffs[0]; /* Set C-KIT's pointer to custom messages*/
System Global Variables
ck_logoff_msgs <cont.>
------------------------------------------------------------------
You do NOT have to define your own log off messages. C-KIT has
it's own internal defaults. If you want to change just one individual
log off message and leave the rest alone, then you can use the pointer
that is initially contained in **ck_logoff_msgs and index to the one
you want to change. Doing this will limit the size to the max.
indicated for that message. The limits on changing individual logoff
internal library messages are:
MAX SIZE!
========
option0[40] /* internal "returning to board" msg */
option1[16] /* internal "NO CARRIER!!" msg */
option2[40] /* internal "keyboard timeout" msg */
option3[48] /* internal "sysop request" msg */
option4[36] /* internal "time expired" msg */
option5[40] /* internal "goodbye" msg */
To change only one internal logoff library message, use the pointer
that is originally contained in **ck_logoff_msgs. Indexing from it,
you can use strcpy() to change it. EXAMPLE:
To change only the "returning to board" msg.
IN YOUR source code:
char exit_msg[40] = "Returning to system\n"; /* Max 40 allocated in lib */
strcpy(*(ck_logoff_msgs), exit_msg); /* Using the orignal pointer,
copy new string */
To change only the "goodbye" msg.
IN YOUR source code:
char logoff_msg[40] = "Thanks for calling\n"; /* Max 40 allocated in lib */
strcpy(*(ck_logoff_msgs + 5), logoff_msg); /* Use the original pointer */
Again, you can provide your own array of pointers and change all
the messages to any size desired. Look at the ckitdemo.c, ckitdemo.h.
System Global Variables
ck_gen_msgs pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
defined as: char **ck_gen_msgs;
Description:
This is pointer to an array of pointers that are C-KIT's internal
messages. The array of pointers has a length of 12 elements.
The code looks for an array of pointers to index which message to
print. This pointer to the general array of pointers allows you to
define your own array of pointers to the 12 internal messages. The
messages can be of any length and which message printed will be based
their position in the array.
The ordering of the array is -
0 - Screen display on message
1 - Event pending warning, time adjusted
2 - Press enter to continue message, used with FORCE_ENTER.
3 - Sysop chat active msg
4 - Sysop chat end msg
5 - Sysop exited to DOS msg
6 - Sysop back from DOS msg
7 - (Enter=none)? msg used in get_defn() and get_defen()
8 - (Enter=yes) msg used in get_defyn()
9 - (Enter=no) msg used in get_defyn()
10 - (Enter) or (Y)es, (N)o, (NS)nonstop? msg used in no_more & display_file
11 - More: - msg used in no_more and display_file
ck_gen_msgs = &ckitmsgs[0]; /* Set pointer to custom message ptrs */
You do NOT have to define these messages. C-KIT has it's own internal
defaults. If you want to change just one individual message and
leave the rest alone, then you can use the pointer that is initially
contained in **ck_gen_msgs and index to the one you want to change.
Doing this will limit the size to the max. indicated for that message.
The limits on changing individual general internal library messages are:
MAX SIZE!
========
msg0[18] /* internal "Screen on" msg */
msg1[44] /* internal "Event pending" msg */
msg2[28] /* internal "Enter to cont." msg */
msg3[48] /* internal "Sysop Chat" msg */
msg4[18] /* internal "Chat end" msg */
msg5[42] /* internal "Exit to DOS" msg */
msg6[40] /* internal "Return from DOS" msg */
msg7[14] /* internal "prompt1" msg */
msg8[12] /* internal "prompt2" msg */
msg9[10] /* internal "prompt3" msg */
msg10[38] /* internal "prompt4" msg */
msg11[6] /* internal "More: " msg */
System Global Variables
ck_gen_msgs <cont.>
------------------------------------------------------------------
To change only one internal general library message, use the pointer
that is originally contained in **ck_gen_msgs. Indexing from it,
you can use strcpy() to change it. EXAMPLE:
To change only the "Screen display on" msg.
IN YOUR source code:
char display_msg[18] = "<Screen ON>"; /* Max 18 allocated in lib */
strcpy(*(ck_gen_msgs), display_msg); /* Using the orignal pointer,
copy new string */
To change only the "Exited to DOS" msg.
IN YOUR source code:
char dos_ret_msg[42] = "Sysop exited to DOS\n"; /* Max 42 allocated in lib */
strcpy(*(ck_gen_msgs + 6), dos_ret_msg); /* Use the original pointer */
Again, you can provide your own array of pointers and change all
the messages to any size desired. Look at the ckitdemo.c, ckitdemo.h.
ck_system_time_HHMMSS[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char ck_system_time_HHMMSS[9];
Description: This string will contain the current system time
in the form HH:MM:SS and is available for general use.
ck_todays_date_MMDDYY[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char ck_todays_date_MMDDYY[9];
Description: This string will contain the current system date
in the form MM:DD:YY and is available for general use.
ck_error_msg11[] pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: char ck_error_msg11[40];
Description: Error message used by display_file. If you do not
define this, C-KIT will default to it's standard
error message. MAX. 40 chars. (not including NULL).
ck_chatmode pcboard.sys door.sys wildcat! generic
------------------------------------------------------------------
Defined as: short ck_chatmode;
Description: This variable will a 1 (TRUE) if chat mode or a
sysop drop to DOS has been active. Use this to
re-fresh your screen if needed. It is YOUR responsiblity
to de-assert the variable after you have used it.
(set to FALSE)
System Global Variables
ck_DOTS
------------------------------------------------------------------
Defined as: BYTE ck_DOTS;
Description: This variable when set to a non-zero value will
echo that value (character) to the to the remote/
local screens when using input() or get_cmdline().
For instance, setting ck_DOTS to a '.' will cause
dots to be echoed to the screen. Handy for using
with passwords etc. Resetting back to a NULL will
resume normal operations.
Standard Data Types
Standard Data Types
CKIT.H defines a number of useful data types.
BYTE
-------------------------------------------------------------------
Defined As: typedef unsigned char BYTE;
Description: The BYTE data type is useful in serial communications
since it provides an easier and more logical way of
handling 8 bit data from UART's used in serial
communications.
Functions
Functions
The C-KIT Library contains a variety of functions.
They are described as follows:
Summary: Presents an exact syntactic model for each of the
C-KIT Library functions.
Description: Describes a function's purpose and how it is used in
an application program.
Return Value: Explains any of the possible return values for a
C-KIT Library function.
See Also: Lists any similar or related C-KIT Library function.
Example: Illustrates how a C-KIT Library function could
actually be used in an application program.
Most function listed in the examples will be simply
listed as function(). This may not indicate how
they are called. To see how they are prototyped and
called go to that function's page.
I.E. If open_door is used in an example (other than
it's own example) it may be simply refered to as
open_door().
In reality open_door is really open_door(char * ...);
The library functions are classified as 3 different types.
High level, intermediate and low level. Normally a door would
not need to make use of any of the functions except the high
level functions. These handle and watch all the system
timeouts, carrier detects, keyboard timeouts etc.
If you need more control, there are other functions available.
I will warn you. The lower level function you use, the less
it will check for you automatically. Do not use these unless
you have to.
Functions
ck_open_door
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_open_door();
Description: The open door function initializes vectors, reads bbs
system information. THIS MUST BE CALLED FIRST!
The first pointer should be be the path/name to the
system file. The second pointer should be the path/name
to the users file, if you designated USERSFILE=TRUE.
open_door() will also accept a pointer to a data
structure if ck_NOSYSTEM is TRUE.
(for pcboard systems only). As long as you have defined
USERSFILE = FALSE, C-KIT will not attempt to use the
second pointer. Which ever you specify, the PORT:AAAA:X
(if used) must be the last parameter passed to
open_door();.
Close_door MUST be called before exiting program after a
call to open_door. See the CKITDEMO.C for more examples.
Return Value: Will return NULL is successful, otherwise it will return
an error code listed below.
See Also: ck_close_door
Example: This example assumes the path\filenames passed on the command
line. i.e program_name path\filename path\filename port
#include "ckit.h"
short result;
main(int argc, char **argv) {
if (argc > 0) {
if(!ck_open_door(argv[1], argv[2], argv[3])); <--- NOTE:
display_info(); argv[2] and
your_main_program(); argv[3] are
} else { optional.
printf("Error opening door!"); see below.
}
ck_close_door();
exit(0);
}
}
open_door() returns these codes:
0 ;Successful
1 ;Unable to open BBS system file (pcboard.sys,door.sys etc)
2 ;Problem reading BBS system file
3 ;Unrecognized BBS file type
4 ;Unable to open pcboard USERS file
5 ;Invalid User record or problem seeking to user record
6 ;Problem reading USER record
7 ;PORT command syntax error
8 ;Fossil driver specified but no Fossil driver installed
;or Digiboard driver not installed
9 ;Memory allocation problem
Functions
ck_open_door <cont.>
-------------------------------------------------------------------
NOTE: Both PORT and USERSFILE are optional. If a user of your door needed to
specify a non-standard port address and IRQ, then the syntax is PORT:AAAA:X
where AAAA is the base address and X is the IRQ. It doesn't matter whether
PORT:AAAA:X is the second or third parameter (depending on if you were
opening the user file) passed to open_door() as long as it is the LAST
parameter passed.
Note also it does not matter which order on the cmd line the arguments are
listed. The only thing that matters is which order they are passed to the
open_door() function itself. You could also have the system path as part of
a config file for your door. Then you would read your config file and pass
the path read from it to open_door() as a string ptr.
PORT is optional, and C-KIT will default to standard addresses and irq's
if PORT is not used based on the port number read from the BBS file.
C-KIT will assume COM1 = 03F8 IRQ 4, COM2 = 02E8 IRQ3, COM3 = 03E8 IRQ4
and COM4 = 02E8 IRQ 3. If the sysop had a different non-standard
port address and irq, he could then use the PORT cmd to change the
defaults. For this reason, you should include the usage of PORT in
your door program and documenation.
Below is some examples of how your program would/could be called up
and how the open_door() function would be called. Notice PORT is always
the second or third (last) argument to be passed if a user of your door
program wanted to use it.
C-KIT will also support the use of FOSSIL drivers. The syntax for a FOSSIL
driver is: PORT:F:P. The 'F' tells C-KIT to use a Fossil driver for it's
communications. The 'P' following it tells it which port to use for the
Fossil. Example - PORT:F:1, tells C-KIT to use a fossil driver for port 1.
Digiboard Intelligent Async boards are supported thru the Universal
DOS driver for Digiboard. The syntax is the same as the Fossil driver
except you replace the F with D and give the channel number to use.
Example - PORT:D:6 tells C-KIT (your door) that it is connected to a
Digiboard and to use channel 6 on the Digiboard.
YOU AS A DOOR AUTHOR SHOULD ALSO INCLUDE THIS INFORMATION IN YOUR DOOR
DOCUMENTATION FILES AND INCLUDE IT IN YOUR CALL TO OPEN_DOOR().
open_door() works like this. It will expect the first pointer to
be a string pointer to the BBS system file, always. Next, it checks
to see if USERSFILE = TRUE. If so, it will expect the second pointer
to be a string pointer to a PCBoard users file. If USERSFILE is
FALSE it will not look for a users file. Either case, open_door()
will search the stack frame pointers for the word "PORT" for the
2nd and 3rd string pointers passed. If it finds it, it will utilize
it. If not, it will use the default port addresses/irq's defined
above for the COM port read from the system file. For this reason,
open_door() will work whether there is actually a port command being
passed or not. You as the door author should provide the users of your
door the ability to pass the port command if they are using NON-STANDARD
ports.
Functions
ck_open_door (cont.)
-------------------------------------------------------------------
EXAMPLES: Assume door.cfg below is a config file that your door programs reads.
This all depends on how or what is desired for your door program. You would
need to document in your door documentation what order the cmd line should
be for your door program, OR read your config file and pass the system name
and path to open_door(). You should also include info about the PORT:AAAA:X
in your docs and include that argument to open_door() as well.
Here is a short example of reading a config file and passing the system
name and path.
(Assuming the 1st line in the config file has the system path\name)
main(int argc, char **argv) {
short handle, bytes_read;
char bbssyspath[81];
handle = open(argv[1], O_RDONLY); /* Open config file */
bytes_read = read(handle, bbssyspath, 80); /* Read system path\name */
bbssyspath[bytes_read - 1] = '\0'; /* Null terminate */
close(handle); /* Close config file */
ck_open_door(bbssyspath, argv[2]); /* include arg2 for the PORT cmd */
ck_close_door();
}
Your program's cmd line for the above could be any one of the following:
doorprgm config.cfg ;Using standard ports
doorprgm config.cfg PORT:03E8:5 ;Using non-standard port
doorprgm config.cfg PORT:F:1 ;Using a fossil driver on port 1
doorprgm config.cfg PORT:D:5 ;Using Digiboard channel 5
You may not need or want a config file for your door program so you could
just simply have the sysop pass the system infomation on the command line.
If this is the case, your program's cmd line could be any of the following:
doorprgm c:\wc\callinfo.bbs ;Using standard ports
doorprgm c:\wc\callinfo.bbs PORT:03F8:5 ;Using non-standard port
doorprgm c:\wc\callinfo.bbs PORT:F:1 ;Using a fossil driver on port 1
doorprgm config.cfg PORT:D:7 ;Using Digiboard channel 7
Again, you as the door author would explain in your documentation how the
sysop would set your door program up depending on how you decide to handle
reading the system files. Just be sure and include information about the
PORT:AAAA:X, PORT:F:x, and the PORT:D:x commands as well.
Functions
ck_open_door (cont.)
-------------------------------------------------------------------
HIGHLY RECOMMEDED!:
You should include in your door source code C's atexit() function.
Then have it call a function that will test if door_open() has been called
or if close_door() has already been called. Then if your program has a
runtime error, you will call close_door() so all interrupts vectors can be
restored and prevent a system crash. Take a look at ckitdemo.c.
EXAMPLE:
short OPENED; /* Flag to know if open_door has been called */
short CLOSED; /* Flag to know if close_door has beeb called */
void shut_down(void); /* Shuts door down if normal or error occurs. */
main(int argc, char **argv) {
open_door(argv[1], argv[2]);
OPENED = TRUE; /* Door has been opened */
atexit(shut_down);
.
.
.
}
/****************************************************************************
* Close door, reset vectors etc. *
* Need in case of a run time error occurs in door *
* and to check if a call to close_door needs to be made. *
****************************************************************************/
void shut_down(void) {
if(OPENED && !CLOSED) {
close_door();
CLOSED = TRUE;
}
}
Functions
ck_open_door (cont.)
-------------------------------------------------------------------
Another way open_door() can be used is thru the use of a data structure
defined as:
typedef struct ckitgeneric {
char port[6]; /* COM:? */
short min_left; /* minutes left */
};
This allows you to support BBS programs in your door program that are not
supported directly by Ckit. To do this, you would read the BBS system
file yourself. Obtain the necassary information for the data structure,
set ck_NOSYSTEM = TRUE, then call open_door(). Below is a short example
of reading a WWIV file. (WWIV is not directly supported by CKIT).
typedef struct ckitgeneric {
char port[6]; /* COM:x (COM0: is local) */
short min_left; /* minutes left */
};
struct ckitgeneric ck_gen; /* You can name this whatever you want */
char *ptr;
if(WWIV) {
open_file(bbs_system_file);
read_file(bbs_system_file);
setup_ck_gen(); /* set up data structure */
ck_NOSYSTEM = TRUE;
ptr = &bbs_system_file);
} else {
ptr = &bbs_system_file;
ck_NOSYSTEM = FALSE;
}
open_door(ptr, argv[2]); (2nd arg is for passing the PORT:AAAA:X cmd)
Take a look at the ckitdemo.c file for a complete example.
Functions
ck_close_door high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_close_door(void);
Description: The close door function resets vectors, closes
files opened and prints the log off message.
THIS MUST BE CALLED LAST and ONLY after open_door().
Close_door MUST be called before exiting program
after a call has been made to open_door.
Not doing so will certainly cause a system lock up.
See above for using C's atexit() function.
Version 2.0 and above, close_door will check if
open_door has been called or if close_door() has
already been called to help further prevent any
system hangups.
Return Value: No value is returned.
See Also: ck_open_door.
Example:
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 0) {
ck_open_door("d:\wc\callinfo.bbs");
.
.
.
. your door program
.
.
ck_close_door();
};
};
Functions
ck_update_user PCBOARD 14.5 only high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_update_user();
Description: The update user will accept a POINTER to the
user structure member to update. See the
user structure above. This function will only
work for PCBoard 14.5 and USERSFILE must be set
TRUE. C-KIT will update the user file when the
door is closed. If you do not want C-KIT to update
the user record after a change has been made
set USERSFILE = FALSE before calling close_door();
If you use this function you should set the compiler
to use WORD alignment for C-kit v.2.01 and below.
NOTE: IN VERSION 2.08 AND ABOVE, YOU NEED TO USE
BYTE ALIGNMENT!
Return Value: No value is returned.
See Also: ck_user structure
Example: Change user security and comment1 field.
MOTICE THE & BELOW!. You MUST pass the address of the
member to update in the user structure.
#include "ckit.h"
main(int argc, char **argv) {
USERSFILE = TRUE;
static char new_comment[] = "ckit_user";
if (argc > 1) {
ck_open_door(argv[1], argv[2]); (pass system file and PORT cmd)
.
.
.
ck_usersecurity = 50;
ck_update_user(&ck_usersecurity);
strcpy(ck_usercomment1, new_comment);
ck_update_user(&ck_usercomment1);
.
.
.
ck_close_door();
};
};
Functions
ck_s_puts high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_s_puts(char *);
Description: The s_puts function displays a single NULL termintated
(C string) to the local and remote console. It expects
a pointer to the string of type BYTE or char
to be displayed. It will not handle ANSI. See
ck_s_putstd() for ANSI and other usage.
Return Value: No value is returned.
See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putsn
Example:
#include "ckit.h"
static BYTE string[] = "This is a test";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]); /* pass system file(s) */
.
.
.
ck_s_puts(string);
ck_s_puts("This is also a test");
.
.
.
ck_close_door();
};
};
Functions
ck_s_putstd high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_s_putstd(char *);
Description: The s_putstd function displays a single NULL termintated
(C string) to the local and remote console. It expects
a pointer to the string of type BYTE or char
to be displayed. This function is identical to s_puts
except it uses std output.
This function should be used when ANSI code, or CTRL
chars are needed to be sent to the local and remote
consoles.
Return Value: No value is returned.
See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putsn
Example: Use s_putstd() to change background/foreground colors
#include "ckit.h"
#define cyanblue 0
#define yellowbrown 1
#define redgreen 2
#define redcyan 3
#define cyanred 4
#define cyanmagenta 5
#define bluegrey 6
static char *ansi_color[8] = {
"\33[0;1;36;44mCyan on Blue\33[40m"
"\33[44m\33[33;43mYellow on Brown\33[40m"
"\33[43m\33[0;31;42mRed on Green\33[40m"
"\33[42m\33[46mRed on Cyan\33[40m"
"\33[46m\33[1;36;41mCyan on Red\33[40m"
"\33[41m\33[45mCyan on Magenta\33[40m"
"\33[45m\33[0;34;47mBlue on Grey\33[0m"
};
main(int argc, char **argv) {
if (argc > 0) {
ck_open_door(argv[1]); /* pass system file(s) */
.
.
.
ck_s_putstd(ansi_color[cyanblue]);
ck_s_putstd(ansi_color[yellowbrown]);
ck_s_putstd(ansi_color[redgreen]);
ck_s_putstd(ansi_color[redcyan]);
ck_s_putstd(ansi_color[cyanred]);
ck_s_putstd(ansi_color[cyanmagenta]);
ck_s_putstd(ansi_color[bluegrey]);
.
.
.
ck_close_door();
};
};
Functions
ck_s_putv high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_s_putv();
Description: The s_putv function displays a single NULL terminated
(C string) to the local and remote console. It expects
a variable argument of pointer(s) to the string(s)
of type BYTE or char to be displayed. The list of
pointers MUST end with a NULL pointer!. Not doing
so will most likely either cause garbage to printed
or even a hang-up.
Return Value: No value is returned.
See Also: s_printf, ck_s_puts, ck_s_putc, ck_s_putsn
Example: This example prints 2 strings with the pointer list
terminated with a NULL pointer.
#include "ckit.h"
static BYTE string[] = "This is a test";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]); /* pass system file(s) */
.
.
.
static BYTE string[] = "This is a test";
ck_s_putv(string, "This is also a test", NULL);
.
.
.
ck_close_door();
};
};
NOTE: an alternative to using s_putv would be to include the function
s_printf() below in your source code. You could use this function
the same as you would printf(); This function has already been protyped
in CKIT.H
Functions
s_printf high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void s_printf(char *,...);
Description: The s_printf function is used to format an output
to be sent to the local and remote console. It is
exactly the same as the cprintf() function in C.
To use it, you must include the source code listed
below in your door program since s_printf() is NOT an
actual part of the C-KIT librarys.
NOTE: if you want to send ANSI strings, change the
s_puts in the s_printf function to s_putstd or create
another std_printf function using s_putstd as the
output.
Return Value: No value is returned.
See Also: s_printf, s_puts, s_putv
INCLUDE THIS SOURCE CODE IN YOUR DOOR PROGRAM TO USE S_PRINTF!
THE FUNCTION HAS ALREADY BEEN PROTOTYPED IN CKIT.H
MODIFY AS YOU NEED.
/****************************************************************************
* Printf() function for sending output to port *
****************************************************************************/
void s_printf(char *s_format,...) {
va_list arg_pointer;
char buffer[82]; /* string buffer for 81 chars */
va_start(arg_pointer, s_format);
vsprintf(buffer, s_format, arg_pointer);
s_putstd(buffer); /* change to s_putstd() for ANSI */
va_end(arg_pointer);
}
Example:
/****************************************************************************
* sending a string out the port using s_printf() *
****************************************************************************/
#include "ckit.h"
short number 34;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door("c:\rbbs\dorinfo1.def", argv[1]);
.
.
.
s_printf("Hello, %s. The number is %d.", firstname, number);
.
.
.
ck_close_door();
};
};
Functions
ck_s_putsn high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_s_putsn(char *);
Description: The s_putsn function displays a single NULL terminated
(C string) to the local console only. It expects
a pointer to the string of type BYTE or char
to be displayed.
Return Value: No value is returned.
See Also: s_printf, ck_s_putv, ck_s_putc, ck_s_putstd
Example:
#include "ckit.h"
static BYTE string[] = "This is a test";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1], argv[2]); (include arg2 for the PORT cmd)
.
.
.
static BYTE string[] = "This is a test";
ck_s_putsn(string);
ck_s_putsn("This is also a test");
.
.
.
ck_close_door();
};
};
Functions
ck_s_putc high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_s_putc(BYTE);
Description: The s_putc function displays a single BYTE or char
to the local and remote console.
Return Value: No value is returned.
See Also: s_printf, ck_s_puts, ck_s_putc.
Example: This example prints a single BYTE (ASCII A) to local
and remote console.
#include "ckit.h"
BYTE byte_to_send = 0x41;
short handle, bytes_read;
char pcbsyspath[81];
main(int argc, char **argv) {
if (argc > 1) {
handle = open(argv[1], O_RDONLY);
bytes_read = read(handle, pcbsyspath, 80);
pcbsyspath[bytes_read - 1] = '\0';
close(handle);
open_door(pcbsyspath, argv[2]); (include arg2 for the PORT cmd)
ck_s_putc(byte_to_send);
ck_close_door();
};
};
Functions
ck_newline high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_newline(void);
Description: The newline function sends a Carriage Return/
Line Feed to the local and remote console.
Increments ck_linenum.
Return Value: No value is returned.
See Also: s_printf, ck_s_puts, ck_s_putc, ck_linenum
Example: This example prints single CR/LF to local
and remote console.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]), argv[2]);
.
.
.
ck_newline();
.
.
.
ck_close_door();
};
};
Functions
ck_clear_row high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_clear_row(short);
Description: The clear_row function clears a given row on screen
of the local and remote console. (row = 1 - 24).
Used only if caller is in GRAPHICS or ansi_ng mode.
Return Value: No value is returned.
See Also: ck_clear_eol, ck_clr_screen.
Example: This example prints a string on a line, then
erases the string.
#include ckit.h
char prompt1 = "Enter filename to view: ";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1], argv[2]); (pass system file and port cmd)
ck_pos_cursor(10, 1);
ck_s_puts(prompt1);
ck_pos_cursor(11, 1);
ck_s_puts("Ready to clear above row, press a key");
while(!(wait_keypress())) {
};
ck_clear_row(10); /* clear row 10 */
ck_newline();
ck_close_door();
};
Functions
ck_clear_eol high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_clear_eol(void);
Description: The clear_eol function clears to the end of line
from current cursor position.
Used only if caller is in GRAPHICS or ansi_ng mode.
Return Value: No value is returned.
See Also: ck_clear_eol, ck_clr_screen.
Example: This example clears to end of line on screen of
local and remote console.
#include ckit.h
char prompt1 = "Enter filename to view: ";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door("c:\wildcat\callinfo.bbs", "PORT:03E8:5");
ck_newline();
ck_s_puts("Press a key to clear end of line below");
ck_newline();
ck_s_putv(prompt1, "\r", NULL);
while(!(wait_keypress())) {
};
ck_clear_eol();
ck_newline();
ck_close_door();
};
};
Functions
ck_clr_screen high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_clr_screen(void);
Description: The clr_screen function clears entire screen of local
and remote console in either ASCII, GRAPHIC, or
ansi_ng mode.
Return Value: No value is returned.
See Also: ck_clear_screen.
Example: This example clears screen of local/remote console.
#include ckit.h
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_clr_screen();
.
.
.
ck_close_door();
};
};
Functions
ck_clear_screen high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_clear_screen(void);
Description: The clear_screen function clears entire screen of
local console including status line.
Return Value: No value is returned.
See Also: ck_clr_screen.
Example: This example clears screen of local console.
#include ckit.h
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_clear_screen();
.
.
.
ck_close_door();
};
};
Functions
ck_pos_cursor high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_pos_cursor(short, short);
Description: The pos_cursor function positions cursor at
row, column using ANSI. Caller must be in GRAPHICS,
or ansi_ng mode. If not no action will take place.
row = 1 to 25, column = 1 to 80. C-KIT will not
let the local screen position cursor in status
line area.
Return Value: No value is returned.
Example: This example positions cursor at row 10, column 15
on the local/remote consoles.
#include "ckit.h"
short row = 10;
short column = 15;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_pos_cursor(row, column);
.
.
.
ck_close_door();
};
};
Functions
ck_set_r_c high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_set_r_c(short, short);
Description: The set_r_c function positions cursor at
row, column using BIOS on the local screen.
row = 1 to 25 (23), column = 1 to 80.
C-KIT will not let the cursor be placed in the
status line area of local screen.
Return Value: No value is returned.
Example: This example positions cursor at row 5, column 1
on the local console.
#include "ckit.h"
short row = 5;
short column = 1;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_set_r_c(row, column);
.
.
.
ck_close_door();
};
};
Functions
ck_back_space high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_back_space(short);
Description: The back_space function backspaces cursor short number
of spaces or to the 1st char in row, whichever is 1st.
This is a destrutive backspace.
Return Value: No value is returned.
Example: This example backspaces cursor over the prompt and
on the user's input local/remote consoles.
#include ckit.h
char prompt1 = "Enter filename to view: ";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door("c:\pcb\pcboard.sys", "PORT:02E8:4");
ck_s_puts("\r\nReady to test back_space()");
ck_s_puts("Press a key when ready");
ck_newline();
while(!(wait_keypress())) {
};
ck_color(yellow);
ck_s_puts(prompt1);
ck_color(red);
ck_get_cmdline();
ck_back_space(strlen(prompt1) + strlen(cmdline));
ck_close_door();
};
Functions
ck_color high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_color(short);
Description: The color function selects color to use using ANSI.
Caller must be in GRAPHICS mode. If not, no action
is taken. ck_color will only set the forground color
and leave the background color as it was.
Return Value: No value is returned.
See Also: Color macros above in macro section used with C-KIT
Example: This example sets color to red on the local/remote
consoles.(see color macros in ckit.h)
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_color(red);
.
.
.
ck_close_door();
};
};
Functions
ck_set_ANSI high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_set_ANSI(short)
Description: Allows manual program changing of ANSI capability.
Excepts either TRUE/FALSE. Normally when C-kit
first opens a system file it determines from the file
whether the user wants ANSI control, (ansi_NG will
be set, GRAPHICS FALSE) OR if they wanted ANSI control
with graphics (ansi_NG false, GRAPHICS TRUE). This
information is not available for generic.sys.
ck_set_ANSI allows people using the generic.sys file
to select ANSI control and/or ANSI control with
graphics.
Return Value: Returns whatever is passed to it.
See Also: ck_graphics, ck_ansi_ng
Example: This example turns on ANSI capability without
graphics.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ansi_ng |= TRUE; /* Set ansi_ng */
graphics &= FALSE;
.
.
.
ck_set_ANSI(ansi_ng | graphics);
.
.
.
ck_close_door();
};
};
Functions
ck_get_cmdline high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_cmdline(void);
Description: Read a line of input (max 128 bytes). Echo to
screen, leave cursor after the last key typed before
C/R. Automatically checks for time_left, carrier.
Calls ck_input() and reads into array *cmdline,
automatically maps input to Uppercase.
Will also set key_source to source of input.
*defined in CKIT.H. This function is the one
you would normally use for ALL user input.
ALL other input functions are intermediate or low
level functions. Setting ck_DOTS = char will cause
char to be echoed to the remote/local console.
Filters all ASCII control charactors below 31 dec. out.
Return Value: No value is returned.
See Also: ck_input, ck_get_nextpar, ck_key_source, ck_wait_keypress
Example: This example reads keyboard from local/remote
console into array get_cmdline[]. It also checks
for any scan_codes receieved. See Ckitdemo.c also.
#include "ckit.h"
main(int argc, char **argv) {
ck_open_door(argv[1]);
do {
ck_newline();
display_time();
ck_color(green);
ck_s_puts("Command? ");
ck_get_cmdline(); /* read input into 'cmdline' */
} while((ck_DUMP_USER != TRUE) && (strlen(ck_cmdline) == 0) \
&& (ck_scan_code == 0));
}
if (ck_DUMP_USER == TRUE) {
ck_close_door();
exit(1);
}
if (ck_scan_code != NULL) {
ck_color(white);
read_scancode();
ck_newline();
}
if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */
ck_newline();
/* process commands */
switch ( par[0] ) {
case 'A':
ansi_demo();
break;
default:
ck_color(magenta);
ck_s_putv("(",par,") is not allowed! Try again:", NULL);
*ck_cmdline = NULL;
}
}
Functions
ck_wait_keypress high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_wait_keypress(void);
Description: Waits for any keypress. Does not wait for a C/R.
Autochecks for CARRIER, TIMEOUTS etc.
Returns ASCII code of key pressed or TRUE if
ck_DUMP_USER goes TRUE otherwise it will return FALSE.
Will also return TRUE if extended key is pressed.
Will not do so if a sysop function key is pressed.
Useful for "hot_key" applications. Will also set
key_source to proper value.
Return Value: ASCII code of keypressed or TRUE, FALSE
See also: ck_check_CR, ck_check_keypress, ck_input, ck_get_cmdline
Example: This example will wait until a keypress or ck_DUMP_USER.
#include "ckit.h"
prompt2 = ""Press any key to continue";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_color(yellow);
ck_newline();
ck_s_puts(prompt2);
while(!(ck_wait_keypress())) {
};
ck_back_space(strlen(prompt2) + 1);
.
.
.
ck_close_door();
};
};
Functions
ck_force_enter high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_force_enter(void);
Description: Prompts " Press Enter to continue: ", wait for C/R,
automatic carrier, time_left and sysop checks.
Return Value: NONE
Example: This example displays a string then prompts and
forces user to press C/R to continue.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_color(yellow);
ck_s_puts("Display this string\r\n");
ck_force_enter();
.
.
.
ck_close_door();
};
};
Functions
display_time high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void display_time(void);
Description: Displays (xxxx used, xxx left).
In CKIT2.0 and above, this function is not in
the library. Instead, using the source code
below will do the same thing as previous
display_time().
Return Value: NONE
See Also: mins_left_system(), system_time_used()
Example: See CKITDEMO.C also
#include "ckit.h"
main(int argc, char **argv) {
ck_open_door(argv[1]);
if (argc > 1) {
ck_open_door(system_ptr, port_cmd_ptr);
.
.
.
display_time();
.
.
.
};
void display_time(void) {
color(yellow);
ck_s_puts("(");
ck_color(green);
s_printf("%d used, ", system_time_used()+prev_used);
ck_color(red);
s_printf("%d left", mins_left_system()+time_credit);
ck_color(yellow);
ck_s_puts(") ");
}
Functions
ck_get_cmdline_raw high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_cmdlinaw(short);
Description: Same as get_cmdline() above but erases prompt of
after input and user input also. Expects length
of prompt to be passed to it.
Return Value: No value is returned.
See Also: ck_get_cmdline, ck_get_nextpar, ck_get_cmdline, ck_input
Example: This example reads keyboard from local/remote
console into array cmdline[], (filename), then
displays file.
#include "ckit.h"
char prompt1 = "Enter filename to display: ";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
ck_s_puts(prompt1);
ck_get_cmdline_raw(strlen(prompt1));
ck_newline();
ck_display_file(cmdline);
ck_close_door();
};
};
Functions
ck_get_nextpar high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
char ck_get_nextpar(void);
Description: Scans next stacked command from cmdline[] array
into "par[]". par defined in CKIT.H
Return Value: Returns 0 if none available, non-zero if cmd available
See Also: input, get_cmdline, cmdline and par in GLOBAL section.
Example: This example reads keyboard from local/remote
console into array get_cmdline[], then calls
get_nextpar to scan for cmds entered.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
do {
ck_get_cmdline(); /* read input into 'cmdline' */
} while( (ck_DUMP_USER != TRUE) && ( strlen(cmdline) == 0 ));
if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */
/* process commands */
switch ( ck_par[0] ) {
case 'A':
ansi_demo();
break;
default:
break;
};
};
};
ck_close_door();
};
Functions
ck_nomore high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_nomore(void);
Description: Displays prompt:
"More: (Enter) or (Y)es, (N)o, (NS)nonstop? ".
Returns 0 = Non_stop
1 = Yes
2 = No
Also checks for CTRL K.
The "More:" prompt will be yellow,
the rest will be green.
Return Value: short value, meaning described above/
See Also: ck_get_def, ck_get_defyn, ck_get_defen
Example: This example loops 3 times to show what each
keypress (N,Y or NS) returns.
#include "ckit.h"
short result, i;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
for(i=0; i <= 2; i++) {
ck_s_puts("\r\nReady to test NOMORE 3 times");
ck_newline();
while(!(ck_wait_keypress())) {
};
result = ck_nomore();
printf("Nomore() returned %d", result);
ck_newline();
};
ck_close_door();
};
Functions
ck_get_defyn high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_defyn(char *, short)
Description: Displays prompt string and either
"Enter=yes " or "Enter=no" based on short value.
1st prompt will be yellow, default will be green.
If short is Non_zero it will display "Enter=Yes".
If short is Zero (NULL) it will display "Enter=No".
Calls get_cmdline for user input.
Return Value: None
See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen
Example: This example loops 2 times to show what each
value or i displays.
#include "ckit.h"
short i;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
for(i=0; i <= 1; i++) {
ck_s_puts("\r\nReady to test get_defyn()");
ck_newline();
ck_get_defyn("Continue? ", i);
ck_s_putv("You entered ", cmdline, NULL);
ck_newline();
};
ck_close_door();
};
Functions
ck_get_defen high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_defen(char *)
Description: Same as get_defyn except the default string
"(Enter=none?) " will be appended.
1st prompt will be yellow, default will be green.
Calls get_cmdline for user input.
Return Value: None
See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen
Example:
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
ck_s_puts("\r\nReady to test get_defne()");
ck_newline();
ck_get_defne("Enter filename? ");
ck_s_putv("You entered ", cmdline, NULL);
ck_newline();
ck_close_door();
};
Functions
ck_getdef high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_def(char *, char *)
Description: Same as get_defen except both colored prompts
are user defineable. The 1st prompt will be
yellow, the 2nd one green.
Calls get_cmdline for user input.
Return Value: None
See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen
Example: Print 2 prompts, and print user input.
static char prompt1 = "Enter filename? "
static char prompt2 = "(Enter = quit)";
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
ck_s_puts("\r\nReady to test get_def()");
ck_newline();
ck_get_def(prompt1, prompt2);
ck_s_putv("You entered ", cmdline, NULL);
ck_newline();
ck_close_door();
};
Functions
ck_prompt_def high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_prompt_def(char *, char *)
Description: Same as get_def except it does not call
get_cmdline. 1st prompt will be yellow,
2nd prompt green.
Return Value: None
See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen
Example: Print 2 prompts.
static char prompt1 = "Enter filename? "
static char prompt2 = "(Enter = quit)";
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
ck_s_puts("\r\nReady to test prompt_def()");
ck_newline();
ck_prompt_def(prompt1, prompt2);
ck_get_cmdline();
ck_newline();
ck_close_door();
};
Functions
ck_getdefn high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_get_defn(char *, char *)
Description: Same as get_def except appends "Enter=none" to end.
Calls get_cmdline for user input.
Return Value: None
See Also: ck_cmd_line, ck_get_def, ck_get_defyn, ck_get_defen
Functions
ck_dos_shell high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_dos_shell(char *, char *);
Description: Will execute program pointed arg1, arg2 is passed
as command line arguments to the program.
arg2 must be < 128 chars. (DOS limit).
This function uses spawnlp() to execute the program.
If you plan on doing any shells, you need to use this
function since it will disable the keyboard timer
while the shell is taking place and perform some other
clean up's upon re-entry. This call uses C's
spawnlp() function, as P_WAIT.
Return Value: -1 = error (check 'C's GLOBAL _errno), NULL = NO error
See also: F5 local shell to DOS, and CKITDEMO.C
Example: Download a file using Zmodem taken from CKITDEMO.C
#include "ckit.h"
char zmodem_cmds[128]; /* Buffer to build Zmodem command */
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
color(green);
s_printf("\nReady to send %s. Press <ENTER> to begin.",doc_filename);
while(DUMP_USER != TRUE) {
if( check_CR() ) {
break;
}
}
sprintf(zmodem_cmds, "portx %X,%X pB4096 pa3000 handshake cts sz %s", \
uart_base, irq, doc_filename);
if(dos_shell("dsz", zmodem_cmds)) {
s_puts("\n\aTransfer aborted");
} else {
s_puts("\nTransfer complete");
}
.
.
.
ck_close_door();
};
};
Functions
ck_display_file high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_display_file(char *);
Description: Displays file to local/remote consoles. Automatic
use of page_length, control K checks, MORE? prompting,
closes file when done. Expects a pointer to name/path
of file to display. If page_length is 0, the
MORE? prompting will be disabled. You can use this
to your advantage for files that you do not want
MORE? prompting by setting ck_userpage_length to 0 before
calling display_file(). Just make sure you save the
original value of ck_userpage_length if you need it later
on. This function will not automatically attempt to
display a graphic file if the user is in graphics.
For display non-interruptable menus, set page_length
to NULL before calling this function.
It is up to the door author to decide how he wants
to handle it. see below. This call is done to
the Borland _open() or MSC _dos_open() libraries as
_open(filename, O_RDONLY | O_DENYNONE);
(share compatible mode)
Return Value: Returns non-zero if error. If desired, you can then
check the C global _errno for the cause of the problem.
See Also: NONE
Example: This example displays the file ckit.m, then forces
user to press enter when done.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
strcpy(filename, "ckit.m")
if(!ck_graphics) {
(ck_display_file(filename);
} else {
strcat(filename,"g");
(ck_display_file(filename);
}
ck_force_enter();
.
.
.
};
ck_close_door();
};
Functions
ck_debug_on high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_debug_on(void); alias ck_carrier_on();
Description: A call to this function while debugging your door
will disable the keyboard timer among other things
while you are trying to debug your door. Make
sure you remove this call before releasing your door
or the keyboard timeout will not function! It should
only be called after open_door();. This can also
be used if needed to use transmit_modem() while the
door is opened. This will disable ck_DUMP_USER from
going true. Make sure you turn debug back on!
using debug_off();
Return Value: NONE
Example:
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_debug_on();
ck_lower_dtr(); /* Drop user off */
ck_raise_dtr();
ck_wait(1); /* wait for modem to reset */
ck_flush_RQUEUE(); /* Flush receive queue */
ck_transmit_modem("ATDT6159826537");
ck_debug_off();
while(ck_tqueue_len()); /* wait on modem */
ck_newline();
delay(1);
while(ck_DUMP_USER != TRUE) { /* wait for modem */
ck_get_cmdline();
ck_newline();
ck_s_putv("Modem returned -> ",cmdline, NULL);
break;
};
.
.
.
};
ck_close_door();
};
Functions
ck_debug_off high level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_debug_on(void); alias ck_carrier_off();
Description: After a call to debug_on(), this will re-enable
keyboard timer, etc.
It should only be called after open_door();
Return Value: NONE
Example:
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
ck_debug_on(); /* while debugging door */
.
.
.
};
ck_debug_off();
ck_close_door();
};
Functions
ck_input intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_input(BYTE *, short);
Description: Read a line of input with specified length. Echo to
screen, leave cursor after the last key typed before
C/R. Automatically checks for time_left, carrier.
Expects a char array pointer to store input and max.
length of input to read. NOTE: Each call to input()
will purge the buffer in use to NULLS. MAX length
must not exceed the size of your array and it must
not include the NULL char. (sizeof(array) - 1).
It will also set key_source = 1 or 2. Setting
ck_DOTS = char will cause char to be echoed to the
local/remote consoles.
Return Value: No value is returned.
See Also: ck_get_cmdline(), ck_inkey(), ck_getkey(), ck_key_source
ck_wait_keypress(), ck_check_CTRL_K
Example: This example reads keyboard input from local/remote
console into array usr_input[] with max. bytes to
read equal to 100 bytes. Will set key_source
equal to source of input.
NOTE: This a "intermediate" level function. You would not
normally need to use this function. get_cmdline();
would normally be used and will handle all input
for you.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_input(&usr_input[0], sizeof(usr_input) - 1);
.
.
.
ck_close_door();
};
};
Functions
ck_check_time_left intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_check_time_left(void);
Description: Checks time left on system, automatically sets
ck_DUMP_USER if time expired. Should be included
in all major program loops if you are going to use it.
Return Value: NONE
See Also: display_time, ck_get_cmdline
Example: This function is normally handled by get_cmdline()
and input(). You do not normally need to use it.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_check_time_left();
if(ck_DUMP_USER == TRUE) {
ck_close_door();
};
.
.
.
ck_close_door();
};
};
ck_mins_left_system intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_mins_left_system(void);
Description: Returns the time left in the door, not including
any time_credit given. Does not set ck_DUMP_USER.
If expired, the time returned will be 0 or
negative minutes. Does not include any time
credit given in door.
Return Value: short value - minutes remaining in door
See Also: display_time, ck_get_cmdline, time_credit
Example:
#include "ckit.h"
minutes_left;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
color(yellow);
s_puts("(");
color(green);
s_printf("%d used, ", system_time_used()+prev_used);
color(red);
s_printf("%d left", mins_left_system()+time_credit);
color(yellow);
s_puts(") ");
.
.
.
ck_close_door();
};
};
ck_system_time_used intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_system_time_used(void);
Description: Returns the time used in minutes since the
door was opened. Does not set ck_DUMP_USER.
Does not include time prev used in door.
Return Value: short value - minutes used since door opened.
See Also: display_time, prev_used
Example:
#include "ckit.h"
minutes_left;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
color(yellow);
s_puts("(");
color(green);
s_printf("%d used, ", system_time_used()+prev_used);
color(red);
s_printf("%d left", mins_left_system()+time_credit);
color(yellow);
s_puts(") ");
.
.
.
ck_close_door();
};
};
Functions
ck_adjust_time_allowed intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_adjust_time_allowed(short);
Description: Adjust user time left on system. Automatically
updates PCBoard.sys to reflect change.
This function will only be effective on systems
using pcboard.sys.
Return Value: NONE
See Also:
Example: For complete example see CKITDEMO.C included
if (ck_get_nextpar()) { /* scan next parameter from cmdline into par */
if (!strcmpi(thinking_of, par)) {
ck_color(green);
ck_s_puts("That's right! You get a 10 minute bonus!");
ck_adjust_time_allowed(10);
} else {
ck_color(blue);
ck_s_putv("Wrong! You lose 2 minutes! \
I was thinking of ", thinking_of,".",NULL);
adjust_time_allowed(-2);
}
}
Functions
ck_check_event intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_check_event(void);
Description: Checks if time left will conflict with event.
Return Value: 0 if no conflict, otherwise it will return the
minutes left before event.
See Also: ck_event_minutes, ck_mins_before_event.
EXAMPLE: C-KIT will automatically check for event conflicts.
This function would normally not be used.
Functions
ck_event_minutes intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_event_minutes(void);
Description: Checks minutes past midnight event is scheduled.
This function is normally handled by C-KIT.
This function would normally not be used.
Return Value: Number of minutes past midnight event is scheduled
to run.
See Also: ck_check_event, ck_mins_before_event.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_short event_mins;
ck_event_mins = event_minutes();
.
.
.
ck_close_door();
};
};
Functions
ck_mins_before_event intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_mins_before_event(void);
Description: Check minutes left before event from current time.
Return Value: Minutes before event from current time.
See Also: ck_check_event, ck_event_minutes.
Example:
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
short mins_before_event;
mins_before_event = ck_mins_before_event();
.
.
.
ck_close_door();
};
};
Functions
ck_delay intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_delay(short);
Description: General purpose delay in milliseconds
Minumum of 55 ms. (short must be >= 1)
This function is good only on the MSC librarys.
The TURBO librarys use Borland's DELAY() function.
See also: ck_wait
Return Value: NONE
Functions
ck_wait intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_wait(short);
Description: General purpose delay in seconds
Minumum of 1 sec. for now (short must be >= 1)
less than one will result in 1/2 second delay.
Use ck_delay above
Return Value: NONE
See also: ck_delay
Functions
ck_purge_buffer intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_purge_buffer(BYTE *, short);
Description: purge_buffer will purge any buffer to NULLS by
passing a pointer to the buffer and the size of the
buffer. i.e purge_buffer(buffer, 0x80).
This may or may not be useful but is available.
NOTE: There is a seperate purge function for the serial port
input buffer if you wish to purge it before calling input.
See flush_RQUEUE.
Return Value: NONE
See also: flush_RQUEUE
Example:
#include "ckit.h"
static BYTE buff[256] = "This is purge buffer test";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_purge_buffer(buff, 255);
.
.
.
ck_close_door();
};
};
Functions
ck_check_CR intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void short ck_check_CR(void);
Description: Check for a carriage return, does not wait, does
not display any prompts.
Returns TRUE or FALSE
Return Value: TRUE, FALSE
See also: ck_force_enter(), ck_get_cmdline(), ck_check_keypress()
Functions
ck_check_CTRL_K intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_check_CTRL_K(void);
Description: Check if a CONTROL K (ASCII 11) has been entered.
Returns TRUE or FALSE
Return Value: TRUE, FALSE
See also: ck_CtrlK_OFF, ck_CtrlK_ON
Functions
ck_CtrlK_ON intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void CtrlK_ON(void);
Description: Enables CONTROL K (ASCII 11) checking.
This is normally off since most menu types are
non_interruptable. If turned on, CTRL K will
be recognized. Once on, you must call CtrlK_OFF()
(see below) to disable it. CTRL K's are also NOT
put into the input buffer. You have to use the
check_CTRL_K() function (see above) to determine
if a CTRL K has been pressed.
See also: ck_CtrlK_OFF, ck_check_CTRL_K()
Functions
ck_CtrlK_OFF intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_CtrlK_OFF(void);
Description: Disables CONTROL K (ASCII 11) checking.
See also: ck_CtrlK_ON, ck_check_CTRL_K()
ck_set_kybd_time intermediate level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_set_kybd_time(BYTE, BYTE);
Description: Sets keyboard timer to desired values.
Default is 2 minutes beep and 5 minute timeout.
This allows the door author to set the keyboard timer. The
time has a resolution in minutes, with a minimum of 1 minute
and a maximum of 255. The routine expects two numbers. The
first number is the BEEP time. This sets how many minutes
should pass before the keyboard timer gives a warning beep.
It will continue to beep afterwards at one minute intervals.
The second number is the actual keyboard timeout value. It
should normally be set to some number higher than the BEEP time.
NOTE: Each call to ck_set_kybd_time() will reset the current
keyboard timer to zero.
Example: Set the BEEP time to 2 minutes and timeout to 6 minutes.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_set_kybd_time(2, 6);
.
.
.
ck_close_door();
};
};
Functions
NOTE: ALL the low level functions below are not normally
needed and are handled automatically by C-KIT in a
higher level function. Most of these functions
do NO carrier detects, etc. They are only provided
in special cases that may need them. Use with caution.
ck_inkey low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
BYTE ck_inkey(void);
Description: Read character (if available) from local/remote
console. Does not wait for input. Also sets
key_source equal to SYSOP or USER_KEY. Inkey
will also keep track of time left and set ck_DUMP_USER
if time expires.
Return Value: Returns 0 if none available, otherwise returns key
pressed
See Also: input, sio_getbyte, key_source above in globals,
check_CTRL_K
Example: This example checks for A at the keyboard,
from local/remote console, returns TRUE or FALSE
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
if ( ck_inkey() != 'A') {
return(FALSE);
} else {
return(TRUE);
}
.
.
.
ck_close_door();
};
};
Functions
ck_keystat low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_keystat(void);
Description: Check if character is available from local console.
Does not wait for input.
Return Value: Returns 0 if none available. None-zero if available.
See Also: ck_input, ck_r_count, ck_key_source.
Example: This example checks for keypress at the keyboard
local console, returns TRUE or FALSE
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
if ( ck_keystat() ) {
return(FALSE);
} else {
return(TRUE);
}
.
.
.
ck_close_door();
};
};
Functions
ck_r_count low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_r_count(void);
Description: Returns number of characters in receive queue.
Does not wait for input.
Return Value: Returns NULL if none available else returns number
of characters in the recieve queue.
See Also: ck_input, ck_r_count, ck_keystat.
Example: See ck_flush_rqueue below
Functions
ck_getkey low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
size_t ck_getkey(void);
Description: Read character (if available) from local console.
Does not wait for input.
Return Value: Returns FALSE if none available.
See Also: ck_input, ck_getkey, ck_keystat, ck_check_CTRL_K
Example: This example read key from local console buffer and
print to screen.
#include "ckit.h"
size_t ch;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ch = getkey();
ck_s_putc(ch);
.
.
.
ck_close_door();
};
};
Functions
ck_sio_getbyte low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
BYTE ck_sio_getbyte(void);
Description: Read character (if available) from remote console.
Does not wait for input.
Return Value: Returns NULL if none available else returns
character read.
See Also: ck_input, ck_sio_getbyte, ck_keystat, ck_check_CTRL_K
Example: This example reads byte from remote console buffer
and displays it, if one was available.
#include "ckit.h"
BYTE ch;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ch = ck_sio_getbyte();
if(ch) {
ck_s_putc(ch);
};
.
.
.
ck_close_door();
};
};
ck_lower_dtr low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_lower_dtr(void);
Description: Drops DTR on com port, causing modem to hang up.
Return Value: NONE
See Also: ck_raise_dtr, ck_transmit_modem, ck_transmit_data
Example:
see ck_transmit_modem below
Functions
ck_raise_dtr low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_raise_dtr(void);
Description: Raises DTR on com port, causing modem to hang up.
Return Value: NONE
See Also: ck_lower_dtr, ck_transmit_modem, ck_transmit_data
Example:
see ck_transmit_modem below
Functions
ck_force_offhook low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_force_offhook(void);
Description: Drops DTR on com port, causing modem to hang up,
tells modem to go back offhook.
This function will wait 1 second after dropping
dtr and 2 seconds after raising DTR before
telling modem to go offhook. This is normally
handled automatically by C-KIT depeding on the
ck_FORCEOFFHOOK setting.
Return Value: NONE
See Also: ck_FORCEOFFHOOK above.
Example: Send a string to reset the modem if carrier
is lost.
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_force_offhook(); /* Dump user offline */
.
.
.
};
ck_close_door();
};
Functions
ck_transmit_data low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_transmit_data(BYTE *);
Description: Send C string to remote console.
No echo to local console. Expects a pointer to either
a NULL terminate C string of type BYTE or char.
Check for carrier included. To send a single byte
use the sample code below.
Return Value: NONE
See Also: ck_transmit_modem
Example:
#include "ckit.h"
#define BEEP 0x07
static char remote_msg[] = "HELLO";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_transmit_data(remote_msg);
send_byte(BELL);
.
.
.
};
ck_close_door();
};
/* To send a single byte to the remote only use this code: */
void send_byte(BYTE data) {
BYTE byte_out[2];
*byte_out = data;
*(byte_out+1) = 0x00; /* Make a 'C' string */
transmit_data(byte_out);
}
ck_transmit_modem low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_transmit_modem(BYTE *);
Description: Send C string to modem/remote.
No echo to local console. Expects a pointer to either
a NULL terminate C string of type BYTE or char.
NO carrier checking is included. If it returns
Non-Zero if error occured, otherwise it returns NULL.
Return Value: NONE
See Also: ck_transmit_data
Example:
#include "ckit.h"
static char dialnumber[] = "ATDT6159707418";
#include "ckit.h"
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_debug_on();
ck_lower_dtr(); /* Drop user off */
ck_raise_dtr();
ck_wait(1); /* wait for modem to reset */
ck_flush_RQUEUE(); /* Flush receive queue */
ck_transmit_modem(dialnumber);
ck_debug_off();
while(ck_tqueue_len()); /* wait on modem */
ck_get_cmdline();
strcmp(ck_cmdline, "CARRIER");
.
.
.
};
ck_close_door();
};
Functions
ck_tqueue_len low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_tqueue_len(void);
Description: Check number of bytes left in Transmit RQUEUE.
Normally this routine is not needed but is available
if needed.
Return Value: Bytes left in XMIT QUEUE
See Also:
Example:
#include "ckit.h"
static char modem_msg[] = "ATX4";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_debug_on();
ck_transmit_modem(message);
while(ck_tqueue_len());
ck_debug_off();
.
.
.
};
ck_close_door();
};
Functions
ck_flush_RQUEUE low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
BYTE * ck_flush_RQUEUE(void);
Description: Flush bytes from Receive QUEUE buffer.
Also returns a near pointer to the receive queue buffer.
Return Value: NONE
See Also: r_count, tqueue_len
Example:
#include "ckit.h"
static char message[] = "ATH1";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_flush_RQUEUE(); /* flush buffer */
ck_transmit_modem(message);
while (ck_r_count()); /* wait for response back */
.
.
.
};
ck_close_door();
};
Functions
ck_flush_TQUEUE low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
void ck_flush_TQUEUE(void);
Description: Flush bytes from Transmit QUEUE buffer.
Return Value: NONE
See Also: tqueue_len
Example:
#include "ckit.h"
static char message[] = "ATH1";
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
ck_flush_RQUEUE(); /* flush buffer */
ck_transmit_modem(message);
while (ck_r_count()); /* wait for response back */
.
.
ck_flush_TQUEUE(); /* flush buffer */
.
};
ck_close_door();
};
Functions
ck_check_cd low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
BYTE ck_check_cd(void);
Description: Checks if carrier present. If present, returns
NON-zero. Zero (NULL) means no carrier present.
Return Value: BYTE indicator of carrier present.
See Also: ck_DUMP_USER, ck_transmit_data, ck_transmit_modem
Functions
ck_check_keypress low level
-------------------------------------------------------------------
Summary: #include "ckit.h"
short ck_check_keypress(BYTE);
Description: Check for any specific ASCII character entered.
Does not wait for a character.
This function may or may not be useful
but is available if needed for a "hot_key"
function in a door. Does no carrier checking!
Return Value: TRUE, FALSE
See also: ck_check_CR, ck_input(), ck_getkey()
ck_wait_keypress, ck_check_CTRL_K
Example:
#include "ckit.h"
BYTE result;
main(int argc, char **argv) {
if (argc > 1) {
ck_open_door(argv[1]);
.
.
.
while {
!(result = ck_check_keypress(0x41));
};
printf("Keypress returned %d", result);
.
.
.
};
ck_close_door();
};
C-KIT based DOOR programs have many of the feature available for the
door author, and for the sysop using standard function keys such as:
Function key
------------
F5 Shell to DOS
F8 Return user to system
F9 Toggle display on/off
F10 Chat mode (use the ESCAPE key to exit)
* F3 Toggle printer on/off
* F4 Toggle pagebell on/off
* F7 Toggle caller alarm on/off
Alternate key
-------------
ALT-H Toggle between different status lines
* ALT-N Toggle sysop on next
* ALT-X Toggle exit to dos after call
and help lines
Alternately pressing the ALT-H key will bring up
the next status line screen. The 1st screen is a help screen,
the second second screen shows your COM port status.
* The function keys marked with an "*" will only be of use to systems
using pcboard.sys. The rest are functional with any system.
Command stacking is also available and can be easily disabled if desired.
See the CKITDEMO.C for example of disabling command stacking.
ATTENTION TURBO C USERS: In versions 2.01 and below you should use
WORD alignment, in C-kit 2.08 and above you should use BYTE alignment.
This applies if you are planning to use the ck_users structure AND/OR
the ck_update_user() function. The default on BORLAND is BYTE alignment.
This will not work correctly for these two items. If you are not
using either the ck_users file structure or ck_update_user();
function, then you don't have to use WORD alignment, BYTE alignment
will work OK.
See the file TCREAD.ME in the CKIT_TC.ZIP file.
In addition, TURBO C++/BC++ users should also select standard stack
frame alignment.
Make a dir to work from. Copy the CKITDEMO.C, CKITDEMO.H, CKIT.H,
the CKIT_T?.LIB's, and the TCPPCKIT.PRJ or CKITS.PRJ into the
same dir. Bring up the TURBO C IDE and select the proper project
file and you can test the CKITDEMO.C. Have it create an .exe file.
This should get you started. You can take it from here...
This package can be freely distributed so long as it is not modified
or sold for profit. If you find that this program is valuable, you
can send me a donation for what you think it is worth. I suggest
at least $25.00 (USA exchange). You will receive a program CKITREG.EXE.
This will register all future copies of C-KIT with your registration
number. This means you would only have to download the new versions
from your favorite board, saving you long distance charges!
For registration over $25.00, full access to all Nodes on Data-Comp will
be made available. Source code modules are available to registered users
for reading other system files that you may want to include in your
door program. (as they become available). There is now a complete
set of PCBoard source code modules. (users.sys, pcboard.dat etc)
Send your contributions to:
Rickie W. Belitz
P.O. Box 5895
Maryville, TN 37802-5895
SUPPORT
-----------
If you have any questions, suggestions, or bug reports, contact me at:
Data-Comp BBS
(615) 982-6512 (USR HST Dual Standard V.32bis)
I can also be reached via mail networks thru INTELEC's BBS_DOORS conference
and RIME's (Relaynet) DOORS conference.
ACKNOWLEDGEMENTS
--------------------
I would like to give special thanks to my Co-sysop, Dean McGuire,
who has patiently tested the door routines and for help preparing the
documentation.
GENERIC.SYS
--------------------------
For maximum compatibility, C-KIT will also read a file called
GENERIC.SYS. This file can be created by the sysop desiring to run
the door and allow C-KIT to operate. This would allow your door to
operate on ANY BBS system. (see compatibilty issues below). The
GENERIC.SYS file is a standard ASCII file and contains 3 lines, each
followed by a carriage return, line feed. The format is:
line 1 - The BBS operator's name.
line 2 - The COM port in use.
line 3 - Time allowed in door.
Below is an example GENERIC.SYS file with a sysop name of Rickie,
using Com port 1, and allowing 50 minutes in the door.
Rickie
COM1:
50
Each line is followed by a C/R, L/F and the com port follows the same
format as the standard door.sys. COM0: = Local Mode (same as door.sys)
See the compatibilty issues below for more information.
NOTE: You should include this information in your door documentation also.
COMPATIBILITY ISSUES
--------------------------
Although C-KIT makes a lot information available to the user, the author
has to decide on what particular information his or her door will require.
Here are some general guidelines that may help. Decide on exactly what
information your door will need to operate. Keeping this to a minimum
increases your chances of maintaining compatibility thruout the different
BBS's systems and versions thereof which C-KIT supports.
For example, let's assume you are designing a standard BBS game. C-KIT
handles all the detailed information such as time left, carrier detect etc.
All you would really need is some basic information. Perhaps just the
user's name and sysop name. By keeping this type of information to the
minimum, your door would work regardless of whether the sysop running your
door used pcboard.sys, door.sys, callinfo.bbs or GENERIC.SYS on the command
line..i.e, game.exe c:\pcb\pcboard.sys OR game.exe c:\pcb\door.sys OR
game.exe c:\wc\callinfo.bbs, OR game.exe c:\GENERIC.SYS OR
game.exe c:\rbbs\DORINFOx.DEF;, ANY of these would work. (If the sysop
was running PCBoard 12.0, he would only be able to use pcboard.sys.
In this case, C-KIT would not only take care of deciding if it was a
pcboard.sys file, door.sys file, WILDCAT! callinfo.bbs or DORINFOx.DEF, but
also if it *is* a pcboard.sys file, whether it is a PCBoard 12.0 sys file
or later, and then would read it properly!). This would make your door
compatible with the full spectrum of PCBoard 12.0-14.5, WILDCAT!, GAP,
SPITFIRE 3.0, other systems using the standard door.sys file, RBBS and
others using DORINFO1.DEF and ANY BBS using GENERIC.SYS with minimum effort
on the part of the sysop running your door. Once you've written this
fantastic new door, if it's a snap for a Sysop to install it, this might
make him a bit more inclined to register it, right?
Another senario would be if your door needs somewhat more than the basic
information. I would recommend using the variables available in door.sys
and WILDCAT! info file in this case. This would give you the broadest
coverage for your door. If you will notice in the variables descriptions
in this manual, there is a compatibility list to the right of each variable.
This tells you which and what type of information is available to you
depending on whether your door found a door.sys, pcboard.sys (and which
version of PCBoard), WILDCAT! info file and DORINFOx.DEF file. Below
is a summary and quick guide to each pcboard.sys version, door.sys,
WILDCAT!, DORINFOx.DEF info file and which information variables are
available with each.
If you need EVEN more information, then you can tell C-KIT to open the
users file and read information. Doing so will limit your door to PCBoard
systems only. C-KIT will NOT record any information to the user's file
unless a call to update_user has been made. It will also not record anything
to sysop record.
Compatible with...
----------------------------------------------------------
"ck_" PCBoard.sys
Variables 12.0 14.0-14.5 DOOR.SYS WILDCAT! DORINFOx.DEF GENERIC.SYS
-------------- ---- -------- -------- ------- ----------- -----------
*conferences X X
aport X X X X X X
ansi_ng X
BBSname X
bps_open X X X
baud_rate X X X X X
callalarm X X X
current_conf X X X
caller_bday X X
display X X X X X
default_color X
daily_bytes X X
daily_files X X
download_Kbytes X X
door_opened X
DOTS X X X X X X
dload_total X X X
error_connection X X X X
expert X X X X
event_active X
event_slide X
event_time X X X
firstname X X X X X X
fullname X X X X X X
graphics X X X X X
gen_dir X
high_msg X
key_source X X X X X
local X X X X X
logoff_color X X X X
exit_msg X X X X X
language X X
last_file_scan X X X X
min_left X X X X X X
main_dir X
max_files X
max_sec X
monitor_type X
msgs_left X
name_in_use X
netchat X X
node X X X X
NO_FKEYS X X X X X X
NOSYSTEM X X X X X X
printer X X X
protocol X X X X
pagebell X X X
password X X X X
page_length X X X X X
PCB X X X X X
PCB12 X X X X X
prev_used X
port X X X X X
parity X X
RBBS X X X X X X
record_lock X
scan_code X X X X X
security_level X X X
silent X X X X X X
sysop_next X X
sysop_name X X X
sysop_alias X
time_logged X X X X X
time_on X X
time_limit X X
time_added X X
total_doors X
user_record X X X X
upload_Kbytes X
upload_total X X X
ck_usercomment1 X
WILDCAT X X X X X
One last note - There are four variables PCB12, PCB, WILDCAT and GAP. When
C-KIT reads a pcboard.sys file, it will set the PCB variable TRUE. If the
pcboard.sys file it read was a 12.0 file, it will set the PCB12 variable true.
If C-KIT finds a WILDCAT system, it will set the variable WILDCAT true. This
may be useful in making adjustments to your program depending on which system
file was read (PCB, DOOR.SYS, PCB12, WILDCAT) and/or if a sysop was running
PCBoard 12.0 and you normally expected door.sys or wildcat info file.
If C-KIT finds a door.sys file, GAP will be set true.
Also, see the users file information earlier in the doc file. Some of the
users structure information is available even if you are just using door.sys.
If you do tell C-KIT to open the users file, all the users file information
above will be available, if C-KIT finds a version 14.x pcboard.sys. If it
finds a PCBoard 12.0 pcboard.sys file, some, but not all, of the users
structure information will be available. Each member of the users structure
is marked to indicate what is available and what is not depending on the
things just mentioned.
Warranty
Warranty
------------
I make no warranty of any kind, express or implied, including
without limitation, any warranties of merchantability and/or
fitness for a particular purpose. I shall not be held liable for
any damages, whether direct, indirect, special or consequential
arising from a failure of this program to operate in the manner
desired by the user. I shall not be held liable for any damage to
data or property which may be caused directly or indirectly by the
use of this program.
In no event will I be held liable for any damages, including (but
not limited to) any lost profits, lost savings or other incidental
or consequential damages arising out of the use or inability to
use this program, or for any claim by any other party.
This warranty is governed by the laws of the State of Tennessee.
ORDER.FRM v2.5
-------------
Return to: Rickie Belitz
P.O. Box 5895
Maryville, TN 37802-5895
Name ______________________________________________________________
Company ___________________________________________________________
Address ___________________________________________________________
___________________________________________________________
Phone _____________________________________________________________
Register C-KIT to: Name____________________________________________
Diskette size: ____ 5.25" acceptable ____ 3.5" required*
Orders outside the USA add $4.00 _________
*Add $2.00 for 3.5" _________
Please find enclosed a check or money order for USA $_________
($30.00 suggested) payable to Rickie Belitz. This shows my support
of Shareware products and the Shareware concept. It also shows my
encouragement to help further development of C-KIT.
I understand that C-KIT is provided as-is and no warranties of
any kind, expressed or otherwise, are included and that I am using
it at my own risk.
Signed: _________________________________________ Date: _________
RELEASE HISTORY
-------------------
see history file
SOME COMMON PROBLEMS/QUESTIONS
------------------------------
Q. How can a test my door in "local" mode?
A. There is a door.sys file included with the C-KIT libraries.
The first line in the door.sys file is COM0:. With accordance
to doorsys specs., this specifies "local" mode. Use this file
for testing your doors. You can modify the door.sys
file to also use a com port for online testing. See the
doorsys.txt for more information. You could also make up a
GENERIC.SYS file and use COM0: as the port. See the section
on GENERIC.SYS.
Q. When linking my code with the library I get a linker error -
Unresolved external _progname in CKIT3.ASM.
A. C-KIT will look for a C string array called progname[21];. This the
name of your door program and will appear at the bottom of the local
line. This is not an option. You must declare some kind of name
for C-KIT to use even if it just a space char if you don't want your
progname at the bottom. See the CKIDEMO.H file for example and
the variable progname[] in the doc file.
Q. When linking your ckitdemo program, I get an error -
Unresolved external _random in ckitdemo.c
A. The Ckitdemo.c door was written to be compiled with either Microsoft C
or Turbo C. As such, there are compiler directives in the CKITDEMO.C
file that will take appropriate action depending on the compiler.
Therefore, when compiling the CKITDEMO.C program, you must have the
statement -DCOMPILER=MICROSOFT or -DCOMPILER=TURBOC on the command
line. This is needed only when compiling the CKITDEMO.C program.
It is NOT needed when you are compiling your own door program.
Q. Do I have to include the -DCOMPILER-MICROSOFT or -DCOMPILER=TURBOC
on the command line every time I compile my door program?
A. No, this was only needed for the CKITDEMO.C source code. You can
also modify the ckitdemo.c and ckitdemo.h file and take the compiler
directives out if you like. Then you would not have to use it when
compiling the ckitdemo.c. (Just make sure you take the right ones
out for whichever compiler you are using). Matter fact, the way
the defaults are defined in CKITDEMO.C, and CKITDEMO.H you don't
need to have the -DCOMPILER=TURBOC when using TURBO C to compile
the ckitdemo.c file or using Turbo C's IDE.
Q. My F4, F3, F7, ALT X, ALT N keys do not do have any effect when
returning to the BBS.
A. These keys are valid only on doors or sysops using the pcboard.sys
file. When the code finds a door.sys or Wildcat! info files, it
will make no attempt to update a pcboard.sys file.
F5 shell to DOS, F8 return to BBS, F9 screen on/off will work
with any system. Try and write your door so that the sysop
can use pcboard.sys if he is a PCBoard sysop but will also run
on other systems as well. Future updates will take into consideration
other systems as permitted. See the compatibility chart above.
Q. Why all the formfeeds in the documentation?
A. This is so that people with access to a copier can print them out,
run the printed sheets thru the copier and duplex (print on both
sides) the sheets into a manual. If you do not want the form
feeds, just do a global replacement with your favorite editor
and get rid of them.
Q. I thought C-KIT required that the users file path be listed also?
A. NO. This was used for the CKITDEMO file only. C-KIT
library does not care one way or another about the users
file being open. CKITDEMO is also written to work with ANY
system. Ckitdemo is a demostration of how a door can be
written to accept any command line given and make adjustments
accordingly. Ckitdemo will accept either:
ckitdemo.exe c:\pcb\pcboard.sys c:\pcb\main\users
ckitdemo.exe c:\pcb\door.sys
ckitdemo.exe c:\wc\callinfo.bbs PORT:03e8:5
See the open_door() function for more information.
Q. Will C-KIT work with any systems users file?
A. NO. If you require information from the user file it must be
be PCBoard 14.x or PCBoard 12.0. However, by doing so
you will be limiting your door to the number of systems
it can be ran on. I would not recommend using user file
info unless your door is being written specifically for
PCBoard. Other system files (pcboard.dat, msgs and
other systems users file) will be included in the form of
source code at a later date. This will allow you to
link those with the existing C-KIT library functions.
Q. What baud rates can C-KIT can handle?
A. C-KIT can handle ANY baud rate from 50 baud to 230K baud.
(these are the baud rates it has been used with). The highest
baud any standard IBM compt. system can produce is 115K
baud. The 230K baud was done on a modified IBM AT by changing
the UART's xtal and using 16550A UARTs.
Q. I'm using MSC 6.0 and when I compile my program I get a message
"warning 'NULL' : macro redefinition"?
A. This is not a problem. It is actually a carry over from MSC5.1.
If you wish, you can remove the line #define NULL = 0 in the CKIT.H
header file. MSC 6.0 redefined their NULL assignment in the stdlib.h
file which causes this. You will not get the warning with MSC 5.1
or lower and TURBO C.
Q. I'm using TURBOC and when I compile the small model demo program
it works fine. But when I re-compile using medium model I get
stack overflow fixup errors from the linker.
A. TurboC does not delete and re-compile the CKITDEMO.C module.
So when it attempts to link the older small model .obj file you created
earlier with the medium library, you will get this error. When
you switch memory models, you must delete the previous .obj file
created using the small memory model. If this happened to be
CKITDEMO.C, you would need to delete CKITDEMO.OBJ before changing
memory models.
Q. Some function keys are not trapped locally.
A. Some keys are reserved on the local keyboard for sysop functions.
Try to design your door without using the F3, F4, F5, F7, F8, F9
ALT-H, ALT-N, ALT-X. If you have to use these keys, they can
be used by the remote keyboard but just be aware, you would not
be able to use them on your local keyboard.
Q. When linking my program, I get an error -
Unresolved external _wait.
A. This function was renamed to ck_wait in v1.7. You need to
be using the CKIT.h header file. There was a conflict with
one of Borland's library names.
Q. Why does the user security level somtimes show on the status line
and sometimes it doesn't?
A. PCBoard.sys file does not provide that information. The security
level will only show if you are using door.sys, callinfo.bbs (WILDCAT!)
or you are using pcboard.sys and open the users file.
The status line indicators for pagebell, printer and caller alarm
will also not show up if you are using door.sys or callinfo.bbs
but will if you are using any version of pcboard.sys from 12.0 up.
Q. Will there be any kind of sign off message from C-KIT after the program
is registered?
A. After C-KIT is registered, the only message displayed when closing the
door will be the one you defined using the *ck_logoff_msgs or the
default "Returning to system ...".