README

$Id$

This is doorlib, a library to easy write native Unix bbs doors. This library
contains some general functions for doors.

Functions:

	unsigned char door_getch(void)

Get a character from the remote user. ANSI escaped keycodes are processed and
translated to codes like KEY_DOWN etc. The following table are the defined
keys:

#define KEY_BACKSPACE   8
#define KEY_LINEFEED    10
#define KEY_ENTER       13
#define KEY_ESCAPE      27
#define KEY_RUBOUT      127
#define KEY_UP          200
#define KEY_DOWN        201
#define KEY_LEFT        202
#define KEY_RIGHT       203
#define KEY_HOME        204
#define KEY_END         205
#define KEY_INS         206
#define KEY_DEL         207
#define KEY_PGUP        208
#define KEY_PGDN        209

All other keys return the normal values. While waiting for a key, there are
two timers running, a inactivity timer with a 10 minutes timeout, and a timer
that forces logoff when the users maximum login time is reached. These timers
are also running during the next string input functions.




	void door_getstrp(char *, int, int);

Get a string from the user. The first parameter is the string, the second is
the maximum string length and the third the initial cursor position.




	void door_getstr(char *, int);

Get a string from the user. The first parameter is the string and the second
is the maximum string length.




	void door_getname(char *, int);

Get a username from the user. The first parameter is the string and the second
is the maximum string length. Each first letter of a name part is forced to
uppercase, the rest to lowercase. When the user types JhOn SmITH this function
will return John Smith.




	void door_getnum(char *, int);

Get a number from the user. The first parameter is the string and the second
is the maximum input length. As you can see the number is returned in a string,
use the atoi() function to convert the string to a integer.



	void door_waitenter(char *);

Displays a message to the user and waits for the user to press the enter key.
The string to pass should be something like "Press ENTER to continue: "
If the string is NULL, then the English string "Press (Enter) to continue: "
is used. The string is displayed in White on Black and after the user has
pressed the enter key, the string is erased from the screen.



	void door_cout(int, int, char *);

Colored output, the first two parameters are the foreground and background
colors, the third is the string to send. The color is send to the user using
standard ANSI sequences. Foreground colors are in the range 0..15, background 
colors in the range 0..7. The following colors are defined in the door.h file:

#define BLACK           0
#define BLUE            1
#define GREEN           2
#define CYAN            3
#define RED             4
#define MAGENTA         5
#define BROWN           6
#define LIGHTGRAY       7
#define DARKGRAY        8
#define LIGHTBLUE       9
#define LIGHTGREEN      10
#define LIGHTCYAN       11
#define LIGHTRED        12
#define LIGHTMAGENTA    13
#define YELLOW          14
#define WHITE           15



	void door_color(int, int);

Set new colors. This is a smart function, only changed colors are send to the
users terminal.



	void door_center(char *);

Write a centered string to the users terminal.



	void door_clear(void);

Clear screen, or on a dumb tty, do a linefeed.



	void door_locate(int, int);

Move cursor to position Y, X. Works only if the remote terminal is ANSI 
capable.



	void door_line(int);

Advance a given number of linefeeds.



	void door_alarm_set(int);

Set the inactivity timer to the given number of seconds.



	void door_alarm_on(void);

Set the inactivity timer to the default 600 seconds.



	void door_alarm_off(void);

Turn off the inactivity timer.



	char *door_xmalloc(size_t);

Allocate string memory.



	char *door_xstrcpy(char *);

Allocate string memory and store the given string in memory.



	char *door_xstrcat(char *, char *);

Allocate string memory and store both strings together in memory.



	int door_load_doorsys(void);

Load door.sys file from current directory. This is the standard 52 lines
door.sys dropfile format. The filename may be DOOR.SYS or door.sys, but not
mixed case. If the file is not found, the door will terminate and set error
return code 100. If the load is successfull, this function returns TRUE.
The contents of the dropfile is loaded in the following structured variable:

typedef struct  _doorsys {          /* 52 lines door.sys file       */
    char        *comport;           /* DOS style COM port           */
    int         ebaud;              /* Effective baudrate           */
    int         databits;           /* Databits                     */
    int         nodenumber;         /* Multiline nodenumber         */
    int         lbaud;              /* Locked baudrate              */
    char        *screen_display;    /* Screen display Y/N           */
    char        *printer_on;        /* Printer on Y/N               */
    char        *page_bell;         /* Paging bell Y/N              */
    char        *caller_alarm;      /* Caller alarm Y/N             */
    char        *username;          /* User name                    */
    char        *location;          /* User's location              */
    char        *voice_phone;       /* User's voice phone           */
    char        *data_phone;        /* User's data phone            */
    char        *password;          /* User's password              */
    int         seclevel;           /* User's security level        */
    int         totalcalls;         /* User's total calls           */
    char        *last_login;        /* last login date MM-DD-YYYY   */
    int         sec_timeleft;       /* Seconds time left            */
    int         min_timeleft;       /* Minutes time left            */
    char        *graphics;          /* Graphics GR or NG            */
    int         screenlen;          /* User's screen length         */
    char        *usermode;          /* Always Y ??                  */
    char        *extra1;
    char        *extra2;
    char        *expiry_date;       /* User's expiry date           */
    int         grecno;             /* User's record number         */
    char        *protocol;          /* Transfer protocol            */
    int         uploads;            /* Total uploads                */
    int         downloads;          /* Total downloads              */
    int         lim_downk;          /* Download limit in Kb.        */
    int         lim_downk2;         /* Download limit in Kb.        */
    char        *date_of_birth;     /* Date of birth                */
    char        *userbase;          /* Path to userbase             */
    char        *msgbase;           /* Path to msgbase              */
    char        *sysopname;         /* Sysop name                   */
    char        *handle;            /* User's alias                 */
    char        *nextevent;         /* Next event time or none      */
    char        *errorfree;         /* Error free connection        */
    char        *allwaysN;
    char        *allwaysY;
    int         defcolor;           /* Default textcolor            */
    int         allways0;
    char        *last_login2;       /* Last login date              */
    char        *time_login;        /* Login time                   */
    char        *last_login_time;   /* Last login time              */
    int         maxinteger;         /* DOS maxint value             */
    int         downs_today;        /* Downloads today              */
    int         uploadK;            /* Uploads in Kb                */
    int         downloadK;          /* Downloads in Kb              */
    char        *comment;           /* User's comment               */
    int         allways0_2;
    int         posted;             /* Messages posted              */
} doorsys_t;



	int door_loginit(char *, char *, int);

Initialize the logfile for the door. The first parameter is the full path and
filename of the logfile, the second parameter is the short program name and
the last parameter is <> 0 for debugging. Example:
door_loginit((char *)"/usr/local/log/mydoor.log", (char *)"mydoor", 0);



	void door_log(int, const char *, ...);

Log a message to the logfile. If the logfile is not initialize, the message
will disapear. The first character denotes the log level, ie: '+', '-' etc.
If letters are used, the message is only logged if the debug value was set
with door_loginit().



	int door_parse_getstr(char **);

Used by the configuration file parser. Get a string value.



	int door_parse_getlong(char **);

Used by the configuration file parser. Get a long integer value.



	int door_parse_config(char *, keytab_t[]);

Parse a configuration file. The first string is the full path and filename to
the configuration file, the second parameter is a table about how to parse the
configuration file. The following is an example, first the config file:

#
# Logfile location
#
logfile         /opt/mbse/log/nextuser.log
#
# Name of the bbs
#
bbsname         BBS/Infobank IJmuiden
#

Next the table needed to process this file:

keytab_t keytab[] = {
    {(char *)"logfile",     door_parse_getstr,      (char **)&logfile},
    {(char *)"bbsname",     door_parse_getstr,      (char **)&bbsname},
    {NULL,                  NULL,                   NULL}
};


The following piece of code will process the configuration and initialize the
door:

int main(int argc, char **argv)
{
    /*
     * Initialize and load configuration.
     */
    if (argc != 2) {
        fprintf(stderr, "Usage: %s /path/to/configfile", argv[0]);
        exit(1);
    }
    if (door_parse_config(argv[1], keytab)) {
        fprintf(stderr, "Parsing configuration failed");
        exit(1);
    }
    if ((door_loginit(logfile, (char *)"mydoor", FALSE)) == FALSE) {
        exit(2);
    }

    /*
     * Now basic stuff is setup and logging is available.
     */
    if (door_load_doorsys() == FALSE) {
        exit(1);
    }
  ......

    /* Do the door code here */
}



	int door_dispfile(char *);

Display a textfile to the user. The paramater is the full path and filename of
the file to display, but without the extension. The prefered file to display
has a .ans extension, if this is not present or the user doesn't support ANSI
a file with .asc extension will be displayed. Control codes are processed and
translated. The following codes are processed:


^A	Wait for a character from the user.
^F	Intro to control-F codes.
^F!	Print protocol name.
^FA	Print number of uploads.
^FB	Print number of downloads.
^FC	Print downloads in Kilobytes.
^FD	Print uploads in Kilobytes.
^FE	Print uploads + downloads in Kilobytes.
^FF	Print download limit in Kilobytes.
^FG	Print number of downloads of today.
^K	Intro to control-K codes.
^KA	Print current date.
^KB	Print current time.
^KC	Print COM port.
^KD	Print locked baudrate.
^KE	Print effective baudrate.
^KF	Print node (line) number.
^KG	Print errorfree connection.
^L	Clear screen
^P	Wait one second.
^U	Intro to control-U codes.
^UA	Print users full name.
^UB	Print users location.
^UC	Print users voice phone.
^UD	Print users data phone.
^UE	Print users last login date.
^UF	Print users comment line.
^UG	Print users last login time.
^UH	Print users security level.
^UI	Print users total calls.
^UJ	Print users expiry date.
^UK	Print users time left in seconds.
^UL	Print users time left in minutes.
^UM	Print users screenlength.
^UN	Print users first name.
^UO	Print users last name.
^UP	Print Yes for ANSI, No for dumb terminal.
^UQ	Print default color number.
^UT	Print users date of birth.
^UU	Print users number of posted messages.
^UY	Print users handle.