home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / DOORL093.ZIP / doorlib-0.9.3.tar.bz2 / doorlib-0.9.3.tar / doorlib-0.9.3 / README < prev   
Text File  |  2003-08-31  |  12KB  |  381 lines
  1. $Id: README,v 1.2 2003/08/31 13:27:32 mbroek Exp $
  2.  
  3. This is doorlib, a library to easy write native Unix bbs doors. This library
  4. contains some general functions for doors.
  5.  
  6. Functions:
  7.  
  8.     unsigned char door_getch(void)
  9.  
  10. Get a character from the remote user. ANSI escaped keycodes are processed and
  11. translated to codes like KEY_DOWN etc. The following table are the defined
  12. keys:
  13.  
  14. #define KEY_BACKSPACE   8
  15. #define KEY_LINEFEED    10
  16. #define KEY_ENTER       13
  17. #define KEY_ESCAPE      27
  18. #define KEY_RUBOUT      127
  19. #define KEY_UP          200
  20. #define KEY_DOWN        201
  21. #define KEY_LEFT        202
  22. #define KEY_RIGHT       203
  23. #define KEY_HOME        204
  24. #define KEY_END         205
  25. #define KEY_INS         206
  26. #define KEY_DEL         207
  27. #define KEY_PGUP        208
  28. #define KEY_PGDN        209
  29.  
  30. All other keys return the normal values. While waiting for a key, there are
  31. two timers running, a inactivity timer with a 10 minutes timeout, and a timer
  32. that forces logoff when the users maximum login time is reached. These timers
  33. are also running during the next string input functions.
  34.  
  35.  
  36.  
  37.  
  38.     void door_getstrp(char *, int, int);
  39.  
  40. Get a string from the user. The first parameter is the string, the second is
  41. the maximum string length and the third the initial cursor position.
  42.  
  43.  
  44.  
  45.  
  46.     void door_getstr(char *, int);
  47.  
  48. Get a string from the user. The first parameter is the string and the second
  49. is the maximum string length.
  50.  
  51.  
  52.  
  53.  
  54.     void door_getname(char *, int);
  55.  
  56. Get a username from the user. The first parameter is the string and the second
  57. is the maximum string length. Each first letter of a name part is forced to
  58. uppercase, the rest to lowercase. When the user types JhOn SmITH this function
  59. will return John Smith.
  60.  
  61.  
  62.  
  63.  
  64.     void door_getnum(char *, int);
  65.  
  66. Get a number from the user. The first parameter is the string and the second
  67. is the maximum input length. As you can see the number is returned in a string,
  68. use the atoi() function to convert the string to a integer.
  69.  
  70.  
  71.  
  72.     void door_waitenter(char *);
  73.  
  74. Displays a message to the user and waits for the user to press the enter key.
  75. The string to pass should be something like "Press ENTER to continue: "
  76. If the string is NULL, then the English string "Press (Enter) to continue: "
  77. is used. The string is displayed in White on Black and after the user has
  78. pressed the enter key, the string is erased from the screen.
  79.  
  80.  
  81.  
  82.     void door_cout(int, int, char *);
  83.  
  84. Colored output, the first two parameters are the foreground and background
  85. colors, the third is the string to send. The color is send to the user using
  86. standard ANSI sequences. Foreground colors are in the range 0..15, background 
  87. colors in the range 0..7. The following colors are defined in the door.h file:
  88.  
  89. #define BLACK           0
  90. #define BLUE            1
  91. #define GREEN           2
  92. #define CYAN            3
  93. #define RED             4
  94. #define MAGENTA         5
  95. #define BROWN           6
  96. #define LIGHTGRAY       7
  97. #define DARKGRAY        8
  98. #define LIGHTBLUE       9
  99. #define LIGHTGREEN      10
  100. #define LIGHTCYAN       11
  101. #define LIGHTRED        12
  102. #define LIGHTMAGENTA    13
  103. #define YELLOW          14
  104. #define WHITE           15
  105.  
  106.  
  107.  
  108.     void door_color(int, int);
  109.  
  110. Set new colors. This is a smart function, only changed colors are send to the
  111. users terminal.
  112.  
  113.  
  114.  
  115.     void door_center(char *);
  116.  
  117. Write a centered string to the users terminal.
  118.  
  119.  
  120.  
  121.     void door_clear(void);
  122.  
  123. Clear screen, or on a dumb tty, do a linefeed.
  124.  
  125.  
  126.  
  127.     void door_locate(int, int);
  128.  
  129. Move cursor to position Y, X. Works only if the remote terminal is ANSI 
  130. capable.
  131.  
  132.  
  133.  
  134.     void door_line(int);
  135.  
  136. Advance a given number of linefeeds.
  137.  
  138.  
  139.  
  140.     void door_alarm_set(int);
  141.  
  142. Set the inactivity timer to the given number of seconds.
  143.  
  144.  
  145.  
  146.     void door_alarm_on(void);
  147.  
  148. Set the inactivity timer to the default 600 seconds.
  149.  
  150.  
  151.  
  152.     void door_alarm_off(void);
  153.  
  154. Turn off the inactivity timer.
  155.  
  156.  
  157.  
  158.     char *door_xmalloc(size_t);
  159.  
  160. Allocate string memory.
  161.  
  162.  
  163.  
  164.     char *door_xstrcpy(char *);
  165.  
  166. Allocate string memory and store the given string in memory.
  167.  
  168.  
  169.  
  170.     char *door_xstrcat(char *, char *);
  171.  
  172. Allocate string memory and store both strings together in memory.
  173.  
  174.  
  175.  
  176.     int door_load_doorsys(void);
  177.  
  178. Load door.sys file from current directory. This is the standard 52 lines
  179. door.sys dropfile format. The filename may be DOOR.SYS or door.sys, but not
  180. mixed case. If the file is not found, the door will terminate and set error
  181. return code 100. If the load is successfull, this function returns TRUE.
  182. The contents of the dropfile is loaded in the following structured variable:
  183.  
  184. typedef struct  _doorsys {          /* 52 lines door.sys file       */
  185.     char        *comport;           /* DOS style COM port           */
  186.     int         ebaud;              /* Effective baudrate           */
  187.     int         databits;           /* Databits                     */
  188.     int         nodenumber;         /* Multiline nodenumber         */
  189.     int         lbaud;              /* Locked baudrate              */
  190.     char        *screen_display;    /* Screen display Y/N           */
  191.     char        *printer_on;        /* Printer on Y/N               */
  192.     char        *page_bell;         /* Paging bell Y/N              */
  193.     char        *caller_alarm;      /* Caller alarm Y/N             */
  194.     char        *username;          /* User name                    */
  195.     char        *location;          /* User's location              */
  196.     char        *voice_phone;       /* User's voice phone           */
  197.     char        *data_phone;        /* User's data phone            */
  198.     char        *password;          /* User's password              */
  199.     int         seclevel;           /* User's security level        */
  200.     int         totalcalls;         /* User's total calls           */
  201.     char        *last_login;        /* last login date MM-DD-YYYY   */
  202.     int         sec_timeleft;       /* Seconds time left            */
  203.     int         min_timeleft;       /* Minutes time left            */
  204.     char        *graphics;          /* Graphics GR or NG            */
  205.     int         screenlen;          /* User's screen length         */
  206.     char        *usermode;          /* Always Y ??                  */
  207.     char        *extra1;
  208.     char        *extra2;
  209.     char        *expiry_date;       /* User's expiry date           */
  210.     int         grecno;             /* User's record number         */
  211.     char        *protocol;          /* Transfer protocol            */
  212.     int         uploads;            /* Total uploads                */
  213.     int         downloads;          /* Total downloads              */
  214.     int         lim_downk;          /* Download limit in Kb.        */
  215.     int         lim_downk2;         /* Download limit in Kb.        */
  216.     char        *date_of_birth;     /* Date of birth                */
  217.     char        *userbase;          /* Path to userbase             */
  218.     char        *msgbase;           /* Path to msgbase              */
  219.     char        *sysopname;         /* Sysop name                   */
  220.     char        *handle;            /* User's alias                 */
  221.     char        *nextevent;         /* Next event time or none      */
  222.     char        *errorfree;         /* Error free connection        */
  223.     char        *allwaysN;
  224.     char        *allwaysY;
  225.     int         defcolor;           /* Default textcolor            */
  226.     int         allways0;
  227.     char        *last_login2;       /* Last login date              */
  228.     char        *time_login;        /* Login time                   */
  229.     char        *last_login_time;   /* Last login time              */
  230.     int         maxinteger;         /* DOS maxint value             */
  231.     int         downs_today;        /* Downloads today              */
  232.     int         uploadK;            /* Uploads in Kb                */
  233.     int         downloadK;          /* Downloads in Kb              */
  234.     char        *comment;           /* User's comment               */
  235.     int         allways0_2;
  236.     int         posted;             /* Messages posted              */
  237. } doorsys_t;
  238.  
  239.  
  240.  
  241.     int door_loginit(char *, char *, int);
  242.  
  243. Initialize the logfile for the door. The first parameter is the full path and
  244. filename of the logfile, the second parameter is the short program name and
  245. the last parameter is <> 0 for debugging. Example:
  246. door_loginit((char *)"/usr/local/log/mydoor.log", (char *)"mydoor", 0);
  247.  
  248.  
  249.  
  250.     void door_log(int, const char *, ...);
  251.  
  252. Log a message to the logfile. If the logfile is not initialize, the message
  253. will disapear. The first character denotes the log level, ie: '+', '-' etc.
  254. If letters are used, the message is only logged if the debug value was set
  255. with door_loginit().
  256.  
  257.  
  258.  
  259.     int door_parse_getstr(char **);
  260.  
  261. Used by the configuration file parser. Get a string value.
  262.  
  263.  
  264.  
  265.     int door_parse_getlong(char **);
  266.  
  267. Used by the configuration file parser. Get a long integer value.
  268.  
  269.  
  270.  
  271.     int door_parse_config(char *, keytab_t[]);
  272.  
  273. Parse a configuration file. The first string is the full path and filename to
  274. the configuration file, the second parameter is a table about how to parse the
  275. configuration file. The following is an example, first the config file:
  276.  
  277. #
  278. # Logfile location
  279. #
  280. logfile         /opt/mbse/log/nextuser.log
  281. #
  282. # Name of the bbs
  283. #
  284. bbsname         BBS/Infobank IJmuiden
  285. #
  286.  
  287. Next the table needed to process this file:
  288.  
  289. keytab_t keytab[] = {
  290.     {(char *)"logfile",     door_parse_getstr,      (char **)&logfile},
  291.     {(char *)"bbsname",     door_parse_getstr,      (char **)&bbsname},
  292.     {NULL,                  NULL,                   NULL}
  293. };
  294.  
  295.  
  296. The following piece of code will process the configuration and initialize the
  297. door:
  298.  
  299. int main(int argc, char **argv)
  300. {
  301.     /*
  302.      * Initialize and load configuration.
  303.      */
  304.     if (argc != 2) {
  305.         fprintf(stderr, "Usage: %s /path/to/configfile", argv[0]);
  306.         exit(1);
  307.     }
  308.     if (door_parse_config(argv[1], keytab)) {
  309.         fprintf(stderr, "Parsing configuration failed");
  310.         exit(1);
  311.     }
  312.     if ((door_loginit(logfile, (char *)"mydoor", FALSE)) == FALSE) {
  313.         exit(2);
  314.     }
  315.  
  316.     /*
  317.      * Now basic stuff is setup and logging is available.
  318.      */
  319.     if (door_load_doorsys() == FALSE) {
  320.         exit(1);
  321.     }
  322.   ......
  323.  
  324.     /* Do the door code here */
  325. }
  326.  
  327.  
  328.  
  329.     int door_dispfile(char *);
  330.  
  331. Display a textfile to the user. The paramater is the full path and filename of
  332. the file to display, but without the extension. The prefered file to display
  333. has a .ans extension, if this is not present or the user doesn't support ANSI
  334. a file with .asc extension will be displayed. Control codes are processed and
  335. translated. The following codes are processed:
  336.  
  337.  
  338. ^A    Wait for a character from the user.
  339. ^F    Intro to control-F codes.
  340. ^F!    Print protocol name.
  341. ^FA    Print number of uploads.
  342. ^FB    Print number of downloads.
  343. ^FC    Print downloads in Kilobytes.
  344. ^FD    Print uploads in Kilobytes.
  345. ^FE    Print uploads + downloads in Kilobytes.
  346. ^FF    Print download limit in Kilobytes.
  347. ^FG    Print number of downloads of today.
  348. ^K    Intro to control-K codes.
  349. ^KA    Print current date.
  350. ^KB    Print current time.
  351. ^KC    Print COM port.
  352. ^KD    Print locked baudrate.
  353. ^KE    Print effective baudrate.
  354. ^KF    Print node (line) number.
  355. ^KG    Print errorfree connection.
  356. ^L    Clear screen
  357. ^P    Wait one second.
  358. ^U    Intro to control-U codes.
  359. ^UA    Print users full name.
  360. ^UB    Print users location.
  361. ^UC    Print users voice phone.
  362. ^UD    Print users data phone.
  363. ^UE    Print users last login date.
  364. ^UF    Print users comment line.
  365. ^UG    Print users last login time.
  366. ^UH    Print users security level.
  367. ^UI    Print users total calls.
  368. ^UJ    Print users expiry date.
  369. ^UK    Print users time left in seconds.
  370. ^UL    Print users time left in minutes.
  371. ^UM    Print users screenlength.
  372. ^UN    Print users first name.
  373. ^UO    Print users last name.
  374. ^UP    Print Yes for ANSI, No for dumb terminal.
  375. ^UQ    Print default color number.
  376. ^UT    Print users date of birth.
  377. ^UU    Print users number of posted messages.
  378. ^UY    Print users handle.
  379.  
  380.  
  381.