home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / drsk.zip / doorskel.doc next >
Text File  |  1994-06-18  |  35KB  |  1,080 lines
  1.  
  2.        DOORSKEL C BBS Door-building kit for OS/2 and MS-DOS
  3.     copyright (c) 1990-1993 by M. Kimes -- all rights reserved
  4.     ==========================================================
  5.  
  6.  
  7. Doorskel is a simple way to build Doors (external programs called by BBS
  8. programs to provide additional functionality to online users) that can
  9. be compiled for either OS/2 or MS-DOS from the same C source code.
  10.  
  11. Doorskel provides portable replacements for some OS and
  12. compiler-specific functions, and provides a communications i/o API that
  13. functions similarly under both DOS and OS/2.  It provides a windowed
  14. ANSI interpreter and protected status lines, and special local keys to
  15. give you a ready-made local interface, and several custom menu
  16. functions, a paged/TTY file reader, and integral dumb/ANSI split screen
  17. chat to give you ready-made remote interfaces.  You should find Doorskel
  18. full-featured enough that you could add database and protocol functions
  19. and create a custom BBS.
  20.  
  21. Doorskel Doors for MS-DOS require a FOSSIL (Fido/Opus/Seadog Standard
  22. Interface Layer) driver to be installed.  Most DOS BBSes already use
  23. FOSSIL drivers, and several FOSSIL drivers are freely available, so this
  24. is no large hardship.
  25.  
  26. Doorskel Doors may take all parameters from the command line, and will
  27. optionally read a DORINFO?.DEF drop file (the most popular format) for
  28. parameters.  Command line parameters can override those in the drop
  29. file.
  30.  
  31.  
  32. License:
  33. =======
  34.  
  35. You may use Doorskel to create FREE Doors (Doors for which you charge no
  36. registration fee and do not sell) without charge or obligation.  You may
  37. not use it otherwise, period.
  38.  
  39. Rights to distribute are granted only to services which do not charge
  40. for the distribution.
  41.  
  42.  
  43. Disclaimer:
  44. ==========
  45.  
  46. There is no warranty whatsoever associated with Doorskel.  There is no
  47. support.  There will be no upgrades.  Doorskel was created to make it
  48. possible for people to create FREE Doors that work identically under
  49. OS/2 or MS-DOS (to promote the writing of Doors for OS/2), not to make
  50. money.
  51.  
  52.  
  53. How to use it:
  54. =============
  55.  
  56. Here's how you'd build an extremely simple "Hello World" Door:
  57.  
  58. /* start file main.c: */
  59.  
  60.   #include "doorskel.h"
  61.  
  62.   int main (int argc,char *argv[]) {
  63.  
  64.     if(DoorInit(argc,argv)) /* initialize Door driver */
  65.       return 1;             /* initialization failed */
  66.     DoorCLS();              /* clear the screen */
  67.     DoorPuts("\r\nHello, world!\r\n");
  68.     DoorInkey(5000L);       /* so it stays up long enough to read */
  69.     return 0;
  70.   }
  71.  
  72. /* end file main.c */
  73.  
  74. Compile to an OBJ, link with the appropriate library above, and you're
  75. done.  When this "Door" is run, you'll get a screen with a single status
  76. line and "Hello, world!" printed on the first line (the cursor will be
  77. on the line below that).  After five seconds the Door will end (or
  78. sooner, if you press a key).
  79.  
  80. See the code in SAMPLE.LZH for a more complex (beginner to intermediate)
  81. example.  Obtain the Fundy or Library Doors for more complicated
  82. (intermediate to advanced) examples.  See the API list below for more
  83. information on what's available and how it's used.
  84.  
  85.  
  86. File list:
  87. =========
  88.  
  89. Here's what should have been in the archive DRSK_200.LZH:
  90.  
  91.   DOORSKEL.DOC          This file
  92.   DOORSKEL.H            Include file for Doorskel Doors
  93.   HYDRA.H               Include file for Doorskel's Hydra* implementation
  94.   XMODEM.C              X/YModem using Doorskel library calls
  95.   LIBS.LZH              Doorskel libraries
  96.     TCLIBD.LIB:             Turbo     C 2.01 library, large model, MS-DOS
  97.     MSCLIBD.LIB:            Microsoft C 6.0a library, large model, MS-DOS
  98.     MSCLIB2.LIB:            Microsoft C 6.0a library, large model, OS/2
  99.   SAMPLE.LZH            Sample Door code
  100.       SAMPLE.C              main module
  101.       SAMPLE.MAK            MSC 6.0a make file (MS-DOS)
  102.       SAMPOS2.MAK           MSC 6.0a make file (OS/2)
  103.       DOORCHAT.HLP          Help file for chat mode
  104.       SAMPLE.HLP            Sample help file for pulldown menu demo
  105.       SAMPLE.TC             Turbo C 2.01 settings file
  106.       SAMPLE.PRJ            Turbo C 2.01 project file (for IDE)
  107.       SAMPTC.BAT            Turbo C 2.01 build file (for command line)
  108.       SAMPLE.EXE            Sample Door compiled with MSC 6.0a for MS-DOS
  109.  
  110.     *Hydra protocol designed by Arjen Lentz and Joaquim Homrighausen
  111.      Portions of the Hydra source in Doorskel were originally written
  112.      by Arjen Lentz.
  113.  
  114.  
  115. The API:  (follow along in DOORSKEL.H for additional nitty-gritty detail):
  116. =======
  117.  
  118. int DoorGetDrive(void);
  119.  
  120.     returns the current disk drive identifier as a number (1 == A, 2 == B,
  121.     etc.).
  122.  
  123. DoorSetDrive(int);
  124.  
  125.     sets the current disk drive to number (1 == A, 2 == B, etc.).
  126.  
  127. DOORFINDBUF
  128.  
  129.     typedef for the buffer required for DoorFindfirst/next/close
  130.     functions which should be used for portability.  this buffer is
  131.     filled in by those functions.
  132.  
  133.     Universally accessible members:
  134.       attrFile          Attributes of the file
  135.       ftimeLastWrite    FTIME structure (hours, minutes, twosecs members)
  136.       fdateLastWrite    FDATE structure (year, month, day members)
  137.       cbFile            Size of the file
  138.       achName           Name of the file
  139.  
  140. int DoorFindFirst (int *handle,char *spec,DOORFINDBUF *buf,int attr);
  141.  
  142.     handle is pre-set to either HDIR_SYSTEM or HDIR_CREATE (normally,
  143.     use HDIR_CREATE).  spec is the mask to use in the find (for example,
  144.     "*.*").  buf is a buffer of type DOORFINDBUF.  attr is an integer
  145.     describing the attributes of files to find.  Attributes can be
  146.     FILE_NORMAL, FILE_READONLY, FILE_HIDDEN, FILE_SYSTEM, FILE_DIRECTORY
  147.     and/or FILE_ARCHIVED.  You can combine these by ORing the constants
  148.     (i.e. FILE_NORMAL | FILE_ARCHIVED).  Returns non-zero on error
  149.     (usually no matching files).
  150.  
  151. int DoorFindNext(int h,DOORFINDBUF *buf);
  152.  
  153.     handle is the handle obtained from a DoorFindFirst call.  buf is the
  154.     DOORFINDBUF buffer returned from a DoorFindFirst call.  Returns
  155.     non-zero on error (usually no more matching files).
  156.  
  157. void DoorFindClose(int h);
  158.  
  159.     close the handle obtained from a DoorFindFirst call.  Don't forget
  160.     to call this, or, under OS/2, you'll run out of search handles.
  161.  
  162. BACKSPACE
  163.  
  164.     a destructive backspace string.  #defined to "\b \b".  Normal
  165.     backspaces ("\b") are considered non-destructive by Doorskel display
  166.     routines.
  167.  
  168. DoorComCSendByte(char x);
  169.  
  170.     send a byte out the commport with carrier check if someone's online.
  171.  
  172. DoorComCNSendByte(char x);
  173.  
  174.     send a byte out the commport with carrier check.
  175.  
  176. DoorComSendByte(char x);
  177.  
  178.     send a byte out the commport.
  179.  
  180. DoorComWriteByte(char x);
  181.  
  182.     send a byte out the commport.
  183.  
  184. DoorComDTROn(void);
  185.  
  186.     raise DTR.
  187.  
  188. DoorComDTROff(void);
  189.  
  190.     drop DTR; usually hangs up.
  191.  
  192. DoorComLDTROff(void);
  193.  
  194.     drop DTR after a one second pause.
  195.  
  196. int DoorComIsByte(void);
  197.  
  198.     returns non-zero if there is a character waiting to be read from the
  199.     commport.
  200.  
  201. DoorInitComm(void);
  202.  
  203.     internal; initialize communications functions.  Called by
  204.     DoorInit().
  205.  
  206. DoorDeinitComm(void);
  207.  
  208.     internal; deinitialize communications functions.  Called by
  209.     Doorskel's deinitialization function which runs just before program
  210.     termination (via atexit()).
  211.  
  212. DoorComFlushOut(void);
  213.  
  214.     flushes the commport's outbound buffers.  Waits up to about 3
  215.     seconds for everything pending to be transmitted, if necessary.
  216.  
  217. DoorComPurgeIn(void);
  218.  
  219.     purge the commport's inbound buffer.
  220.  
  221. DoorComPurgeOut(void);
  222.  
  223.     purge the commport's outbound buffer.
  224.  
  225. DoorModemPuts(char *s);
  226.  
  227.     print a null-terminated string out the commport.  note this prints
  228.     remotely only, and only if someone's online.
  229.  
  230. DoorRemoteBell(void);
  231.  
  232.     rings a bell on the remote (or local console, if no one's online).
  233.     equivalent to:
  234.       if(DoorGetBaudVar()) DoorModemPuts("\07");else DoorANSIPuts("\07");
  235.  
  236. long DoorMinsLeft(void);
  237.  
  238.     returns number of minutes remaining to current user.  You can get
  239.     the exact number of seconds left with DoorGetTime().  You can change
  240.     the user's time remaining with DoorSetTimeOff().
  241.  
  242. DoorANSISetPos(int x,int y);
  243.  
  244.     position cursor to x,y on local and remote.  Remote must have ANSI
  245.     graphics capability, obviously.
  246.  
  247. DoorANSISavePos(void);
  248.  
  249.     cause the local and remote terminals to save their position for
  250.     subsequent recall.  only one position at a time may be saved (ANSI
  251.     limitation).
  252.  
  253. DoorANSIRstrPos(void);
  254.  
  255.     restores the last saved (via DoorANSISavePos()) local and remote
  256.     position.
  257.  
  258. int DoorIsANSI(void);
  259.  
  260.     returns non-zero if the user has ANSI turned on.  DoorGetGraphics()
  261.     could also be used.
  262.  
  263. int DoorIsLocal(void);
  264.  
  265.     returns non-zero if there is no one online.  DoorGetBaudVar() could
  266.     also be used.
  267.  
  268. DoorPrintGraphics(char *s);
  269.  
  270.     display the null-terminated string if the user has ANSI turned on.
  271.  
  272. DoorPurgeInLocal(void);
  273.  
  274.     flush the local keyboard.
  275.  
  276. DoorFlushOutLocal(void);
  277.  
  278.     flush the local screen.  not needed under normal circumstances.
  279.  
  280. word
  281.  
  282.     typedef for "unsigned short" which under MS-DOS and OS/2 1.x is the
  283.     same thing as an unsigned int (a 16-bit integer with no sign).
  284.  
  285. CLOCKS_PER_SEC
  286.  
  287.     under Turbo C 2.01, equal to CLK_TK.  under other compilers, has
  288.     pre-defined value.  it's the number of clock ticks per second.
  289.  
  290. clock_t DoorTimerSet(long milliseconds);
  291.  
  292.     set a timer.  the functions DoorTimerSet, DoorTimeUp and
  293.     DoorTimeLeft are used together to manipulate and inspect timers.
  294.  
  295. int DoorTimeUp(clock_t timer);
  296.  
  297.     test a timer.  return non-zero if timer has expired.
  298.  
  299. clock_t DoorTimeLeft(clock_t timer);
  300.  
  301.     return milliseconds left on timer (0L if expired).
  302.  
  303. void DosSleep (clock_t millisecs);
  304.  
  305.     sleep a number of milliseconds.  This is the same as the OS/2 API.
  306.     In fact, under OS/2, it IS to the OS/2 API.  Under MS-DOS it gives
  307.     up timeslices during the snooze.  The minimum useful call would be
  308.     DosSleep(1L), which would give up one full timeslice under OS/2,
  309.     Windows, DV, Topview, etc.
  310.  
  311. int DoorANSIPuts (char *buf);
  312.  
  313.     display a null-terminated string through the ANSI interpreter.
  314.     status line(s) is/are protected.  Returns length of string printed.
  315.     note this prints locally only.
  316.  
  317. void DoorANSIPutc (char c);
  318.  
  319.     display a single character through the ANSI interpreter. status
  320.     line(s) is/are protected.  note this prints locally only, and is
  321.     less efficient for strings than DoorANSIPuts above.
  322.  
  323. void DoorSetScreensize (int reservedlines);
  324.  
  325.     internal -- initializes the ANSI interpreter.  called by DoorInit().
  326.     reservedlines is the number of lines at the bottom of the screen to
  327.     reserve as status lines.  after a DoorSpawn() this is called again,
  328.     in case the screen size changes.
  329.  
  330. DoorCursor(int x,int y)
  331.  
  332.     position the local cursor to x,y (1-based).  To position locally and
  333.     remotely, use DoorPrintf("\x1b[%d;%dH",y,x); or DoorANSISetPos().
  334.  
  335. void DoorScrollUp (int tx,int ty,int bx,int by,char attr);
  336.  
  337.     scroll a local window up.  tx == top x coordinate, ty == top y
  338.     coordinate, bx == bottom x coordinate, by == bottom y coordinate,
  339.     attr == attribute with which to fill blanked lines (7 == pale grey
  340.     on black, 112 == black on grey).
  341.  
  342. void DoorClearWindow (int tx,int ty,int bx,int by,char attr);
  343.  
  344.     clear a local window.
  345.  
  346. char * DoorStripCR(char  *a);
  347.  
  348.     strip trailing '\r' and '\n' from a null-terminated string.
  349.  
  350. char * DoorLStrip(char  *a);
  351.  
  352.     strip leading spaces from a null-terminated string.
  353.  
  354. char * DoorRStrip(char  *a);
  355.  
  356.     strip trailing spaces from a null-terminated string.
  357.  
  358. void DoorBackup (int num);
  359.  
  360.     print num destructive backspaces.
  361.  
  362. void DoorBackupString(char *s);
  363.  
  364.     print enough destructive backspaces to erase the string.
  365.  
  366. char * DoorAddToLog(char *text,...);
  367.  
  368.     add an entry to the logfile (see DoorSetLogFile() and
  369.     DoorGetLogFile()).
  370.  
  371. int DoorInit(int argc,char **argv);
  372.  
  373.     initialize Doorskel.  If this returns non-zero your Door should
  374.     terminate.
  375.  
  376. int DoorDetectANSI(void);
  377.  
  378.     returns non-zero if it appears that the user has ANSI graphics
  379.     capability.
  380.  
  381. long DoorGetTime(void);
  382.  
  383.     checks time remaining (and returns time remaining).  if user is out
  384.     of time, runs appropriate termination function (see
  385.     DoorSetOutOfTime() and DoorGetOutOfTime()).  Updates time on status
  386.     line.  This is normally called by all Doorskel high-level input
  387.     functions for you, but if you write your own, you may need to call
  388.     this and DoorCheckCarrier() in the busy loop.
  389.  
  390. int DoorInkey(long millisecs);
  391.  
  392.     gets a keypress from local and/or remote.  translates remote ANSI
  393.     cursor keys and "Doorway"-mode keys.  handles local special keys
  394.     (like ALT-H to hang up, and function keys assigned with
  395.     DoorSetFunctionKeys()).
  396.  
  397. char * DoorGenericInput(int length,int password,int caps,
  398.                         int hot,int type,char *prompt,
  399.                         char *buffer);
  400.  
  401.     gets a null-terminated string from the user.  length is the length
  402.     of the string to receive (maximum 255 characters).  if password is
  403.     non-zero, Doorskel "masks" the echoed characters to obscure what's
  404.     being typed from prying eyes.  if caps is non-zero, input is echoed
  405.     and stored as upper case.  type is the type of input (see below).
  406.     if prompt != NULL Doorskel displays the null-terminated string in
  407.     prompt before accepting input.  if buffer != NULL Doorskel places
  408.     the string into buffer; otherwise it returns in a static string.
  409.     Note that this makes DoorGenericInput reentrant _if_ you use the
  410.     buffer.
  411.  
  412.     input types:
  413.  
  414.     ALLL      All printable characters.
  415.     ALPHA     Alphabetical [a...Z] characters.
  416.     NUM       Decimal digits [0...9].
  417.     ALPHANUM  Alphabetical characters and decimal digits.
  418.     YESNO     Y or N.
  419.     FLE       A filename.
  420.     FLEP      A filename with path.
  421.     FLEW      A filename with wildcards.
  422.     FLEPW     A filename with path and wildcards.
  423.     NAME      A name (capitalization enforced).
  424.     NEAT      First character of words capitalized.
  425.     PHONE     A phone number (formatted American-style, sorry).
  426.     DATE      A date (formatted American-style, sorry).
  427.     SUBJECT   First letter of input capitalized.
  428.     YESNOM    Y or N, hot, no echo.
  429.     ARROWS    ESC, CTRL_K, 0 (Enter), UPP, DN, LEFT or RIGHT.
  430.     FBATCH    Batch filenames (separated by spaces).
  431.     FBATCHW   Batch filenames with wildcards.
  432.     FBATCHWP  Batch filenames with wildcards and path.
  433.     FBATCHP   Batch filenames with path.
  434.     HYPER     Internal.
  435.     FLENX     Filename without extension.
  436.     YESNOQ    Y, N or Q.
  437.  
  438. int DoorCheckCarrier(void);
  439.  
  440.     check for carrier loss.  if carrier has been lost, runs the
  441.     appropriate termination function (see DoorSetLostCarrier() and
  442.     DoorGetLostCarrier()).  if bit 1 of the return is set, a character
  443.     is waiting at the commport.
  444.  
  445. void DoorHitReturn(void);
  446.  
  447.     displays "\r\n[Enter] to continue..." message and then waits for the
  448.     user to press [Enter].  Erases its prompt.
  449.  
  450. void DoorCLS(void);
  451.  
  452.     clears local and remote screens.
  453.  
  454. int DoorPrintf(char *string,...);
  455.  
  456.     printf-clone that displays both locally (and remotely if someone's
  457.     online).  returns length of string written.
  458.  
  459. void DoorANSIPrintf(char *string,...);
  460.  
  461.     printf-clone that displays locally through ANSI interpreter.
  462.  
  463. void DoorDebugPrintf(char *string,...);
  464.  
  465.     printf-clone that displays locally if debug mode is on (see
  466.     DoorSetDebugMode() and DoorGetDebugMode()).  Note that debug mode
  467.     can be turned on at the command line of the Door.
  468.  
  469. int DoorPuts(char *text);
  470.  
  471.     displays a null-terminated string both locally (and remotely if
  472.     someone's online).  returns length of string written.
  473.  
  474. int DoorDirectPuts(int x,int y,char attr,char *str);
  475.  
  476.     display a null-terminated string fast (usually directly to screen or
  477.     LVB) at location x,y with attribute attr.
  478.  
  479. int DoorDirectPrintf(int x,int y,char attr,char *str,...);
  480.  
  481.     printf-clone that displays a null-terminated string fast (usually
  482.     directly to screen or LVB) at location x,y with attribute attr.
  483.  
  484. DoorMakeColor(fg,bg)
  485.  
  486.     build attributes for direct screen writing and scrolling/clearing
  487.     functions.  fg == foreground color (7 = white), bg == background
  488.     color (0 = black).
  489.  
  490. DoorClr(bg,fg,in)
  491.  
  492.     as above, in == intensity bit.
  493.  
  494. char * DoorMakeANSI (int avacode,char *buf);
  495.  
  496.     build an ANSI escape sequence string from a PC (Avatar) color code
  497.     (7 = light grey on black, 112 = black on white, etc.).    If buf is
  498.     not NULL must point to a string sized long enough to receive the
  499.     built sequence (about 30 characters is more than sufficient).
  500.     If buf is NULL, an internal static buffer is used.  Can be used in
  501.     conjunction with DoorMakeColor and DoorClr above.
  502.  
  503. DoorMakeANSIIf (int avacode,char *buf);
  504.  
  505.     returns "\0" if user doesn't have ANSI graphics on, else returns
  506.     the built-up ANSI escape sequence to set the color (as for
  507.     DoorMakeANSI).
  508.  
  509. void DoorLoadHelp (char *helpfilename);
  510.  
  511.     load a help file.  help files are plain old flat ASCII files with
  512.     the following layout:
  513.         <topic1>
  514.         text for topic1
  515.         more text for topic1
  516.         <topic2>
  517.         text for topic2
  518.  
  519. void DoorSetHelp (char *topic);
  520.  
  521.     set current help topic.  do not include <> brackets.
  522.  
  523. void DoorHelp (void);
  524.  
  525.     display text for current help topic.
  526.  
  527. int DoorANSIMenu2 (char tcolor,char color,char *title,
  528.                    char *lineorig,char **variable,int startat);
  529.  
  530.     create and process a pulldown menu.  if the user is not an ANSI
  531.     graphics user, it creates and processes a tree menu.  note that
  532.     pulldown menus are a good way to present the user with a few
  533.     options that have several related suboptions in a way that isn't
  534.     as "alien" as many online formats:  most every user is familiar
  535.     with pulldown menus, so they're intuitive.
  536.  
  537.     tcolor is the ANSI color to use for the title (37 == white).  color
  538.     is the ANSI color to use for the rest of the window.  title is the
  539.     string to print centered in the top of the pulldown.  lineorig is a
  540.     string of options (up to 10) separated by spaces.  variable is an
  541.     array of strings (must be the same number of strings in the array
  542.     that there are options in lineorig) containing suboptions for the
  543.     corresponding main option. startat can cause DoorANSIMenu2 to start
  544.     with something already selected.  DoorANSIMenu2 returns an integer
  545.     that equates to the selected option or suboption as main option * 10
  546.     (+ suboption).  this interfaces automatically with the DoorHelp
  547.     system to provide context-sensitive help.  I'll refer you to the
  548.     sample archive for more on that.
  549.  
  550.     that's seems pretty complicated, but it's really not.  here's a
  551.     simple example:
  552.  
  553.     int opt;
  554.     char *subopts[] = {"1st_Subopt1 2nd_Subopt1","1st_Subopt2 2nd_Subopt2",
  555.                        NULL};
  556.  
  557.     opt = 0;
  558.     while(opt != 30) {  /* option 30 == "Exit" */
  559.       opt = DoorANSIMenu2(33,36," Example ",
  560.                           "1st_Option 2nd_Option Exit",
  561.                           subopts,opt);
  562.       switch(opt) {
  563.         case 0:
  564.           DoorPuts("\r\nYou selected nothing.\r\n");
  565.           break;
  566.         case 11:
  567.         case 12:
  568.         case 21:
  569.         case 22:
  570.           DoorPrintf("\r\nYou selected main option #%u suboption #%u.\r\n",
  571.                      opt / 10,opt % 10);
  572.           break;
  573.         case 30:
  574.           break;
  575.       }
  576.     }
  577.  
  578. int DoorANSIMenu (char color, char *lineorig);
  579.  
  580.     create and process a one-line ANSI menu (if the user is not in ANSI
  581.     graphics mode, it's a "standard" one-line menu).  Returns the first
  582.     letter of the option selected.  color is the base ANSI color to use
  583.     for the menu (37 == white), and lineorig is a string containing
  584.     options separated by spaces.  this also interfaces automatically to
  585.     the DoorHelp system; again, see sample archive.
  586.  
  587. int DoorSelectOne (char **selections,int numselecs,char *prompt,
  588.                    unsigned int flags);
  589.  
  590.     creates and processes a "rolling" menu.  selections contains an
  591.     array of strings containing selections.  numselecs indicates how
  592.     many selections there are.  prompt is the prompt presented to the
  593.     user.  flags are bitmapped:  1 == show initial list of options
  594.     2 == show initial list of first letters  4 == no "roll"
  595.     returns the index of the selected item or -1 if cancelled with
  596.     CTRL-K or ESCape.
  597.  
  598. int DoorTopMenu (char **selections,int numselects);
  599.  
  600.     similar to DoorSelectOne but only for ANSI users.  this creates and
  601.     processes a top-of-screen menu, similar to the menu in Lotus 1-2-3.
  602.     the user can select from the menu using cursor keys (or numeric
  603.     keypad; not all terminals properly send arrow keys).  the menu can
  604.     exceed the length of the screen.  returns the index of the selected
  605.     item or -1 if cancelled with CTRL-K or ESCape.
  606.  
  607. int DoorReadText(char *filename,int paged);
  608.  
  609.     display text file filename in typed (paged == 0) or paged (paged is
  610.     non-zero) mode.
  611.  
  612. int DoorReadDorInfo(void);
  613.  
  614.     internal -- read a DORINFO?.DEF file.  See DoorUseDorInfo().
  615.  
  616. int DoorDialTrans (char *str);
  617.  
  618.     send a string to the modem with dial translation:
  619.  
  620.     ~ = 1 second pause
  621.     ` = .1 second pause
  622.     | = carriage return
  623.     ^ = DTR up
  624.     v = DTR down
  625.  
  626. char * DoorGetModemString (clock_t timer);
  627.  
  628.     get a null-terminated cr-ended string from the modem in timer
  629.     milliseconds.  usually used to get return codes from modem commands.
  630.  
  631. int DoorSetBaudRate (unsigned int baud,char parity,
  632.                      int databits,int stopbits);
  633.  
  634.     set current line characteristics.  parity is 'N', 'E' or 'O'.
  635.     databits is 5, 6, 7 or 8.  stopbits is 0 (for one stopbit) or 2 (for
  636.     two stopbits).
  637.  
  638. void DoorCurrCursor(int *x,int *y);
  639.  
  640.     return location of local cursor (1-based).
  641.  
  642. int DoorWhereX(void);
  643.  
  644.     return x coordinate of local cursor (1-based).
  645.  
  646. int DoorWhereY(void);
  647.  
  648.     return y coordinate of local cursor (1-based).
  649.  
  650. int DoorSpawn(char *strr);
  651.  
  652.     spawn an external process.  clears screen, restores status lines on
  653.     return.  returns error code of spawned process (note that spawning
  654.     through COMMAND.COM does not return a valid error code).
  655.  
  656. int DoorComReadByte (long msecs);
  657.  
  658.     read a byte from the commport, waiting up to msecs milliseconds.
  659.     returns -1 if timeout occurs .
  660.  
  661. int DoorComOnLine (void);
  662.  
  663.     return non-zero if carrier is detected.  does not run any
  664.     termination functions if carrier is not found.
  665.  
  666. int DoorComWriteBlk (char *buf,int len);
  667.  
  668.     write a block of len bytes in buf out the commport.
  669.  
  670. int DoorComPeekByte (long msecs);
  671.  
  672.     return the waiting commport byte (if any).  waits up to msecs
  673.     milliseconds for something to arrive if nothing's there.  returns -1
  674.     if timeout occurs.
  675.        
  676. int DoorComReadBlk (char *buf,int len,long msecs);
  677.  
  678.     read a block of up to len bytes into buf, waiting up to msecs
  679.     milliseconds for enough to arrive.  returns length read or -1
  680.     if a timeout occurs.
  681.  
  682. DoorComOutEmpty (void);
  683.  
  684.     return non-zero if output buffer is empty.
  685.  
  686. DoorComInEmpty (void);
  687.  
  688.     return non-zer of input buffer is empty.
  689.  
  690. int DoorComOutWaiting(void);
  691.  
  692.     return number of bytes in output buffer.
  693.  
  694. int DoorComInWaiting(void);
  695.  
  696.     return number of bytes in input buffer.
  697.  
  698. char * DoorSearchPath(char *filename);
  699.  
  700.     search the current directory and directories listed in the PATH
  701.     environment variable for a file.  under OS/2, also searches
  702.     DPATH and XPATH (in that order).
  703.  
  704. char *DoorStrTime(time_t t,char *s);
  705.  
  706.     returns the current time (if t == 0L, otherwise the time represented
  707.     by t) in format HH:MM:SS.  The buffer s must be at least 9 bytes
  708.     long.
  709.  
  710. char *DoorStrDate(time_t t,char *s);
  711.  
  712.     returns the current date (if t == 0L, otherwise the date represented
  713.     by t) in the unambigous and more-or-less universally accepted format
  714.     YYYY/MM/DD.  The buffer s must be at least 11 bytes long.
  715.  
  716. void DoorReadScreenLine(int x,char *s);
  717.  
  718.     reads line x from the screen into buffer s.  buffer should be
  719.     DoorGetMaxx() + 1 bytes long.  buffer will be null-terminated.
  720.  
  721. void DoorReadScreen(int *s);
  722.  
  723.     reads the entire screen (well, the window that normal i/o goes into,
  724.     discounting status lines) into buffer s.  buffer should be size
  725.     DoorGetMaxx() * DoorGetMaxy() * sizeof(short) long.
  726.  
  727. void DoorWriteScreen(int *s);
  728.  
  729.     writes the entire screen (discounting status lines) from buffer s.
  730.  
  731. FILE * DoorFsopen (char *filename,char *mode,int sharemode);
  732.  
  733.     open file stream with sharing.  use instead of compiler-specific
  734.     functions like MSC's _fsopen.
  735.  
  736. char * DoorStristr (char *t, char *s);
  737.  
  738.     a case insensitive strstr().
  739.  
  740. long DoorFreeSpace (char *path);
  741.  
  742.     returns the amount of free space on the drive indicated by path
  743.     (i.e. if path is "C:\\DUH" returns free space on drive C).
  744.  
  745. void DoorSetFDate (char *name,long tim);
  746.  
  747.     sets filename name to time tim (where tim == a time_t type,
  748.     should be seconds from 1970).
  749.  
  750. int DoorDoHydra(char *send,char *sendalias,long hydraopts);
  751.  
  752.     engage Hydra file transfer protocol (Hydra designed by Arjen Lentz
  753.     and Joaquim Homrighausen).  I have no idea if this works or not.
  754.  
  755. DoorSetTimeOff(time_t x);
  756.  
  757.     set the time at which the user will be out of time.  to give the
  758.     user 30 minutes, DoorSetTimeOff(time(NULL) + (30L * 60L));
  759.  
  760. DoorSetProgramName(char *x);
  761.  
  762.     set the name of the program.  should be called before DoorInit().
  763.  
  764. DoorSetCopyRight(char *x);
  765.  
  766.     set the copyright notice for the program.  should be called before
  767.     DoorInit().
  768.  
  769. DoorSetNumStatLines(int x);
  770.  
  771.     set the number of status lines to reserve.  should be called before
  772.     DoorInit().  one line is reserved for "standard" information (time
  773.     remaining, program name, user name).
  774.  
  775. DoorSetOutOfTime((void x)(void));
  776.  
  777.     set the function to be run when the user runs out of time.  this
  778.     function should usually terminate the Door via exit().  the default
  779.     displays an informational message and terminates with error level
  780.     200.  the function should be declared like:  void myfunc(void);
  781.  
  782. DoorSetTimedOut((void x)(void));
  783.  
  784.     set the function to be run when the user times out (idle).  this
  785.     function should usually terminate the Door via exit().  the default
  786.     displays an informational message and terminates with error level
  787.     201.  the function should be declared like:  void myfunc(void);
  788.  
  789. DoorSetLostCarrier((void x)(void));
  790.  
  791.     set the function to be run when carrier is lost.  this function
  792.     should usually terminate the Door via exit().  the default displays
  793.     a local informational message and terminates with error level 202.
  794.     the function should be declared like:  void myfunc(void);
  795.  
  796. DoorSetExtraHelp((void x)(void));
  797.  
  798.     set the function to be run (if any) when the sysop requests command
  799.     line help (programname /?).  the default is none; standard help
  800.     only.  the function should be declared like:  void myfunc(void);
  801.  
  802. DoorSetExtraStatLine((void x)(void));
  803.  
  804.     set the function to be run when the status line needs updating.  the
  805.     default status line will already have been refreshed.  use
  806.     DoorDirectPrintf() and DoorDirectPuts() to display your extra status
  807.     line(s).  the function should be declared like:  void myfunc(void);
  808.  
  809. DoorSetExtraArgs((int x)(char *arg));
  810.  
  811.     set the function to be run when unknown arguments are encountered
  812.     while processing the command line.  the default prints an error
  813.     message and continues.  the function should be declared like:
  814.     int myfunc(char *);  it should return non-zero to abort the Door.
  815.  
  816. DoorSetFunctionKey(int key,(void x)(int keynum));
  817.  
  818.     set the function to be run when the local sysop presses ALT plus a
  819.     function key (F1 - F10).  the default is to do nothing.  the
  820.     function should be declared like:  void myfunc(int);
  821.  
  822. DoorSetGraphics(int x);
  823.  
  824.     sets the current state of the user's ANSI graphics capability.
  825.     only 0 and 1 are valid.
  826.  
  827. DoorSetBaudVar(word x);
  828.  
  829.     sets the current baud rate.  setting to 0 disables carrier detection
  830.     and commport interaction.  this does NOT actually change the baud
  831.     rate, just what the Door considers the baud rate to be.
  832.  
  833. DoorSetLength(int x);
  834.  
  835.     sets the length of the user's screen.
  836.  
  837. DoorSetSecLevel(word x);
  838.  
  839.     sets the user's security level.  Doorskel doesn't use this
  840.     internally; it's for your use.
  841.  
  842. DoorSetSysopIn(int x);
  843.  
  844.     set whether the sysop is in or out.  Doorskel doesn't use this
  845.     internally; it's for your use.  only 0 and 1 are valid.
  846.  
  847. DoorSetLogFile(char *x);
  848.  
  849.     sets the name of the log file.
  850.  
  851. DoorSetUserName(char *x);
  852.  
  853.     sets the name of the user.
  854.  
  855. DoorSetWidth(int x);
  856.  
  857.     sets the width of the user's screen.
  858.  
  859. DoorSetNodeNumber(int x);
  860.  
  861.     sets the number of the node in use (default is one) for multinode
  862.     systems.  Doorskel uses this to build the name of the DORINFO?.DEF
  863.     file to read.
  864.  
  865. DoorSetUseBIOS(int x);          /* MS-DOS only */
  866.  
  867.     if set to a non-zero number, Doorskel performs BIOS writes where it
  868.     would normally perform direct screen writes.
  869.  
  870. DoorSetUseANSI(int x);
  871.  
  872.     if set to non-zero, the ANSI sequence interpreter is turned off
  873.     locally.  not much need for that...
  874.  
  875. DoorSetTabSpaces(int x);
  876.  
  877.     sets the number of spaces to which the ANSI sequence interpreter
  878.     expands tabs.
  879.  
  880. DoorUseDorInfo(void);
  881.  
  882.     sets whether or not Doorskel will read a DORINFO?.DEF file.  note
  883.     that this is normally determined by the sysop using the door via
  884.     the command line.  must be set before calling DoorInit().
  885.  
  886. DoorSetVidHandle(int x);        /* OS/2 only */
  887.  
  888.     set the video handle to something besides 0.  would only be useful
  889.     if you were trying to use AVIO, and would have to be set before
  890.     calling DoorInit.
  891.  
  892. DoorSetSystemName(char *x);
  893.  
  894.     set the system name (name of the BBS).
  895.  
  896. DoorSetSysopName(char *x);
  897.  
  898.     set the sysop's name.
  899.  
  900. DoorSetDebugMode(int x);
  901.  
  902.     set debug mode.  only 0 and 1 are valid.  this is normally set by
  903.     the sysop via the command line.
  904.  
  905. DoorSetMaxx(int x);
  906.  
  907.     internal; sets the maximum x coordinate used by the ANSI
  908.     interpreter.  this shouldn't be used.
  909.  
  910. DoorSetMaxy(int x);
  911.  
  912.     internal; sets the maximum y coordinate used by the ANSI
  913.     interpreter.  this should normally be set by using DoorSetNumStat()
  914.     before calling DoorInit().
  915.  
  916. DoorSetRealMaxx(int x);
  917.  
  918.     internal; sets the real maximum x coordinate of the local screen.
  919.     Doorskel normally figures this out for itself, and this shouldn't be
  920.     used.
  921.  
  922. DoorSetRealMaxy(int x);
  923.  
  924.     internal; sets the real maximum y coordinate of the local screen.
  925.     Doorskel normally figures this out for itself, and this shouldn't be
  926.     used.
  927.  
  928. DoorSetCommHandle(int x);
  929.  
  930.     sets the commport number (0 == COM1, 1 == COM2) under MS-DOS, or the
  931.     commport handle under OS/2.  this is normally passed by the sysop on
  932.     the command line.
  933.  
  934. DoorSetCurx(int x);
  935.  
  936.     internal; sets the current x coordinate for the ANSI interpreter.
  937.     You shouldn't play with this.
  938.  
  939. DoorSetCury(int x);
  940.  
  941.     internal; sets the current y coordinate for the ANSI interpreter.
  942.     You shouldn't play with this.
  943.  
  944. DoorSetCurAttr(char x);
  945.  
  946.     internal; sets the current attribute used by the ANSI interpreter.
  947.     You shouldn't play with this.
  948.  
  949. DoorSetLVB(word *x);
  950.  
  951.     internal; sets the current LVB (Logical Video Buffer, video RAM
  952.     under MS-DOS) location.  Doorskel normally figures this out for
  953.     itself, and you shouldn't mess with it.
  954.  
  955. DoorSetLVBLen(word x);
  956.  
  957.     internal; sets the length of the LVB.
  958.  
  959. DoorSetLVBMin(word x);
  960.  
  961.     internal; sets the minimum changed area of the LVB.
  962.  
  963. DoorSetLVBMax(word x);
  964.  
  965.     internal; sets the maximum changed area of the LVB.
  966.     DoorFlushOutLocal() flushes the area between the LVBMin and LVBMax
  967.     to the screen.  no flushing is performed under MS-DOS.
  968.  
  969. char *DoorGetProgramName(void);
  970.  
  971.     returns the program's name.
  972.  
  973. char *DoorGetCopyRight(void);
  974.  
  975.     returns the program's copyright information.
  976.  
  977. int DoorGetNumStatLines(void);
  978.  
  979.     returns the number of status lines (minimum 1, Doorskel's reserved
  980.     line).
  981.  
  982. DoorGetOutOfTime(void);
  983.  
  984.     returns the function set by DoorSetOutOfTime().
  985.  
  986. DoorGetTimedOut(void);
  987.  
  988. DoorGetLostCarrier(void);
  989.  
  990. DoorGetExtraHelp(void);
  991.  
  992. DoorGetExtraStatLine(void);
  993.  
  994. DoorGetExtraArgs(void);
  995.  
  996. DoorGetFunctionKey(int key);
  997.  
  998. DoorGetGraphics(void);
  999.  
  1000. DoorGetBaudVar(void);
  1001.  
  1002. DoorGetLength(void);
  1003.  
  1004. DoorGetSecLevel(void);
  1005.  
  1006. DoorGetSysopIn(void);
  1007.  
  1008. DoorGetLogFile(void);
  1009.  
  1010. DoorGetUserName(void);
  1011.  
  1012. DoorGetWidth(void);
  1013.  
  1014. DoorGetNodeNumber(void);
  1015.  
  1016. DoorGetUseBIOS(void);               /* MS-DOS only */
  1017.  
  1018. DoorGetUseANSI(void);
  1019.  
  1020. DoorGetTabSpaces(void);
  1021.  
  1022. DoorDontUseDorInfo(void);
  1023.  
  1024. DoorGetVidHandle(void);             /* OS/2 only */
  1025.  
  1026. DoorGetSystemName(void);
  1027.  
  1028. DoorGetSysopName(void);
  1029.  
  1030. DoorGetDebugMode(void);
  1031.  
  1032. DoorGetDorInfo(void);
  1033.  
  1034. DoorGetMaxx(void);
  1035.  
  1036. DoorGetMaxy(void);
  1037.  
  1038. DoorGetRealMaxx(void);
  1039.  
  1040. DoorGetRealMaxy(void);
  1041.  
  1042. DoorGetCommHandle(void);
  1043.  
  1044. DoorGetTimeOff(void);
  1045.  
  1046. DoorToggleGraphics(void);
  1047.  
  1048.     toggles graphics mode from on to off and off to on.
  1049.  
  1050. DoorGetCurx(void);
  1051.  
  1052. DoorGetCury(void);
  1053.  
  1054. DoorGetCurAttr(void);
  1055.  
  1056. DoorGetLVB(void);
  1057.  
  1058.     internal; returns address of Logical Video Buffer (video RAM under
  1059.     MS-DOS).
  1060.  
  1061. DoorGetLVBLen(void);
  1062.  
  1063.     internal; returns length of LVB.
  1064.  
  1065. DoorGetLVBMin(void);
  1066.  
  1067.     internal; returns minimum changed area of LVB.
  1068.  
  1069. DoorGetLVBMax(void);
  1070.  
  1071.     internal; return maximum changed area of LVB.
  1072.  
  1073.  
  1074.  
  1075. M. Kimes
  1076. 542 Merrick
  1077. Shreveport, LA  USA  71104
  1078. (318)222-3455 data
  1079. Fidonet#1:380/16.0
  1080.