home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1994 #1 / monster.zip / monster / MAXIMUS / MAXDLLS.ZIP / COMM.ZIP / COMM.H next >
C/C++ Source or Header  |  1994-01-09  |  13KB  |  393 lines
  1. /*
  2.  *  Header file for COMM.DLL,  a high performance multithreading
  3.  *  library for OS/2 serial port i/o.
  4.  *
  5.  *  Copyright (C) 1990, 1991 A:WARE Inc.  All rights reserved.
  6.  *
  7.  * Comm.h, MaxComm.lib, and MaxComm.dll may be used and distributed freely for
  8.  * non-profit use, provided that they are distributed together and
  9.  * are not modified in any way. This means that any program that uses
  10.  * them has to be free, unless prior written persmission from A:WARE
  11.  * Inc. states otherwise.
  12.  *
  13.  * Inclusion with a for-profit/commercial program requires that you
  14.  * purchase the source code for MaxComm.dll.  No royalties.
  15.  * The cost is US$199.
  16.  *
  17.  * Contact A:WARE Inc:
  18.  *
  19.  * 6056 Cayeswood Ct, Ste 100
  20.  * Mississauga, Ontario
  21.  * Canada
  22.  * L5V 1B1
  23.  *
  24.  * (416)858-3222.
  25.  *
  26.  * Author: Peter Fitzsimmons, March 1990.
  27.  */
  28.  
  29. /* NB:  To create a "maxcomm.lib" to link with,  do this:
  30.  
  31.       IMPLIB Maxcomm.lib Maxcomm.Dll
  32.  
  33.   (assuming maxcomm.dll is in the current directory
  34.  
  35.  */
  36.  
  37. /*
  38.  * include os2.h or os2def.h before this file.
  39.  *
  40.  */
  41. #ifndef APIENTRY
  42. #include <os2def.h>
  43. #include <bsedos.h>
  44. #endif
  45.  
  46. typedef SHANDLE  HCOMM;
  47. #define COMMAPI  pascal far
  48.  
  49.  
  50. /*
  51.  * open comm device.  return 0 if successful,  OS/2 error if not.
  52.  *
  53.  * This function (or ComHRegister()) must be called before any
  54.  * other Com() function.
  55.  *
  56.  * Do not use this function if the port handle has been inherited from
  57.  * another process (use ComHRegister() instead).
  58.  *
  59.  * The comm handle (placed in pHcomm) is not a file handle,  and should
  60.  * not be used by Dos() functions.  If the file handle to the port is
  61.  * needed (to pass to a child process),  use the ComGetFH() function.
  62.  *
  63.  * If RxBufSize and/or TxBufSize are/is zero,  a default size is used.
  64.  *
  65.  
  66.   When using COM0x.SYS,  the default buffer size is the same as the
  67.   buffer size used by COM0x.SYS.  For Tx, this is the optimum size
  68.   to keep COM0x.SYS busy.  A buffer larger than this will not gain
  69.   any extra performance.  Therefore, the common urge to make the
  70.   transmit buffer large will not have the desired effect.  If there
  71.   was some way to make the REAL transmit buffer (the one in
  72.   COM0x.SYS) larger,  performance gains WOULD be seen,  but there is
  73.   no way to do this unless you have the source code for COM0x.SYS.
  74.   If you DO have the source (in the DDK), and you increase the
  75.   buffer sizes, use 0 for the XxBufSize and ComOpen will use your
  76.   larger buffers (ComOpen/Register uses the standard IOCTL call to
  77.   query the buffer sizes).
  78.  
  79.   RxBufSize, on the otherhand, does not affect performance of any
  80.   functions in the Com() module.  To avoid overflows however,  you
  81.   should set this to at least the size of the COM0x.SYS Rx buffer,
  82.   or use 0 so the default size if selected.  When the Rx buffer gets
  83.   full,  the speaker will sound (DosBeep(200, 10)).  There are two
  84.   solutions to this problem:  Make the Rx buffer larger (preferred),
  85.   or raise the priority of the thread calling ComRead()/ComGetc().
  86.  
  87.   All threads created by comm.dll run at the default priority. Since
  88.   com0?.sys is interrupt driven,  Reading/Writing to it at a high
  89.   priorty does not improve anything.  If the Rx thread is starved
  90.   for such a long time that com0?.sys buffer gets full,  it means
  91.   some other process on your computer is badly behaved (IT is
  92.   problably running at Time Critical class when it shouldn't be).
  93.   There are four ways to solve this (in order of preference):
  94.  
  95.   1) Insert DosSleep(1L) in the polling loops that are guilty (this
  96.   assumes you have source code), and/or have it run at NORMAL
  97.   priority class.
  98.  
  99.   2) decrease MAXWAIT in config.sys.
  100.  
  101.   3) Prior to calling ComOpen/ComHRegister, raise the priorty of the
  102.   current thread (or of the whole process).  The Rx/Tx threads will
  103.   inherhit this priority.
  104.  
  105.   4) set PRIORITY=ABSOLUTE in config.sys.
  106.  
  107.  
  108.   FYI:  OS/2 1.2 uses a default size of 1024 bytes for Rx, and 128
  109.         bytes for Tx.
  110.  
  111.  *
  112.  *
  113.  */
  114. USHORT COMMAPI _loadds ComOpen(PSZ PortName,
  115.                        HCOMM FAR *pHcomm,  /* pointer to var for Comm handle */
  116.                        USHORT RxBufSize,   /* desired size of Receive queue*/
  117.                        USHORT TxBufSize);  /* desired size of Transmit queue */
  118.  
  119. /*
  120.  * ComHRegister():  Register a comm handle opened by another process.
  121.  *
  122.  * This function (or ComOpen()) must be called before any
  123.  * other Com() function.
  124.  */
  125. USHORT COMMAPI _loadds ComHRegister(HFILE hf,
  126.                        HCOMM FAR *pHcomm,  /* pointer to var for Comm handle */
  127.                        USHORT RxBufSize,   /* desired size of receive queue*/
  128.                        USHORT TxBufSize);  /* desired size of xmit queue */
  129.  
  130.  
  131. /* ComClose():  Close and/or DeRegister comm handle.
  132.  *
  133.  * This function will not DosClose() the handle if the handle was not
  134.  * opened by this process with ComOpen() (ie: If ComHRegister() was used,
  135.  * ComClose() will not DosClose() the handle.  ComClose() must still be
  136.  * called though).
  137.  */
  138. USHORT COMMAPI ComClose(HCOMM hcomm);
  139.  
  140.  
  141. /*
  142.  * return TRUE if the device (comx, named pipe, etc) is considered
  143.  * in an "Online" state.
  144.  */
  145. USHORT COMMAPI ComIsOnline(HCOMM hcomm);
  146.  
  147. /*
  148.  * ComWrite(): Place many bytes in output queue.
  149.  *
  150.  * This function does not return until all of the bytes have been
  151.  * placed in the output queue,  or an error occurs.
  152.  *
  153.  * If the device becomes offline while this function is waiting for
  154.  * queue space, and the watchdog feature is enabled (see
  155.  * ComWatchDog()),  this function returns before completion.
  156.  *
  157.  */
  158. USHORT COMMAPI ComWrite(
  159.      HCOMM hc,                          /* file handle                   */
  160.      PVOID pvBuf,                       /* pointer to buffer             */
  161.      USHORT cbBuf);                     /* number of bytes to write      */
  162.  
  163.  
  164. /*
  165.  * ComRead(): Read many bytes from input queue.
  166.  *
  167.  * This function will copy bytes from the input queue to pvBuf,
  168.  * until the input queue is empty, or 'cbBuf' bytes have been copied.
  169.  *
  170.  *
  171.  */
  172. USHORT COMMAPI ComRead(
  173.      HCOMM hc,                          /* file handle                 */
  174.      PVOID pvBuf,                       /* pointer to buffer           */
  175.      USHORT cbBuf,                      /* maximum bytes to read       */
  176.      PUSHORT pcbBytesRead);             /* pointer to variable receiving
  177.                                          * byte count */
  178.  
  179. /*
  180.  * ComGetc() : return next byte in input queue,  or -1 if there is none.
  181.  */
  182. SHORT COMMAPI ComGetc(HCOMM hc);
  183.  
  184. /*
  185.  * ComPeek():  the same as ComGetc(),  but the character is left in the
  186.  * input queue.
  187.  */
  188. SHORT COMMAPI ComPeek(HCOMM hc);
  189.  
  190. /*
  191.  * ComPutc():  Place one byte in output queue.  This function does not
  192.  * return until the byte is placed in the output queue, or an error occurs.
  193.  *
  194.  * If the device becomes offline while this function is waiting for
  195.  * queue space, and the watchdog feature is enabled (see
  196.  * ComWatchDog()),  this function returns before completion.
  197.  */
  198. USHORT COMMAPI ComPutc(HCOMM hc, SHORT c);
  199.  
  200. /*
  201.  * ComRxWait():  Wait for something to be placed into the input queue.
  202.  *
  203.  * If lTimeOut is -1L,  wait forever.  Otherwise, lTimeOut is the
  204.  * number of milliseconds to wait (or 0) before returning a timeout
  205.  * error (ERROR_SEM_TIMEOUT).
  206.  *
  207.  * If the device becomes offline while this function is waiting, and
  208.  * the watchdog feature is enabled (see ComWatchDog()),  this
  209.  * function returns before completion.
  210.  *
  211.  */
  212. USHORT COMMAPI ComRxWait(HCOMM hc, LONG lTimeOut);
  213.  
  214. /*
  215.  * ComTxWait():  Wait for output queue to empty.
  216.  *
  217.  * If lTimeOut is -1L,  wait forever.  Otherwise, lTimeOut is the
  218.  * number of milliseconds to wait (or 0) before returning a timeout
  219.  * error (ERROR_SEM_TIMEOUT).
  220.  *
  221.  * If the device becomes offline while this function is waiting, and
  222.  * the watchdog feature is enabled (see ComWatchDog()),  this
  223.  * function returns before completion.
  224.  */
  225. USHORT COMMAPI ComTxWait(HCOMM hc, LONG lTimeOut);
  226.  
  227.  
  228. /*
  229.  * return number of bytes in input queue.
  230.  *
  231.  */
  232. USHORT COMMAPI ComInCount(HCOMM hc);
  233.  
  234. /*
  235.  * return number of bytes in output queue.
  236.  *
  237.  */
  238. USHORT COMMAPI ComOutCount(HCOMM hc);
  239.  
  240. /*
  241.  * return space in output queue.
  242.  *
  243.  */
  244. USHORT COMMAPI ComOutSpace(HCOMM hc);
  245.  
  246.  
  247. #define COMM_PURGE_RX 1
  248. #define COMM_PURGE_TX 2
  249. #define COMM_PURGE_ALL  (COMM_PURGE_RX | COMM_PURGE_TX)
  250. /*
  251.  * ComPurge():  Purge (discard) i/o queue(s).
  252.  *
  253.  *  Where fsWhich is a combination of :
  254.  *           COMM_PURGE_RX      Purge input queue.
  255.  *
  256.  *           COMM_PURGE_TX      Purge output queue.
  257.  */
  258. USHORT COMMAPI ComPurge(HCOMM hc,  SHORT fsWhich);
  259.  
  260.  
  261. /*
  262.  * ComPause():
  263.  *
  264.  * This function causes the Rx and Tx threads to end, after all
  265.  * Tx activity has ended.  Any bytes still in the Rx queue are
  266.  * purged.  After calling this function,  it is safe for other
  267.  * processes to use the comm port file handle (see ComGetFH()).
  268.  *
  269.  */
  270. USHORT COMMAPI ComPause(HCOMM hc);
  271.  
  272. /*
  273.  * ComResume():
  274.  *
  275.  * This function creates new Rx and Tx threads,  and resets the state
  276.  * of the comm port to what is was when ComPause() was called.
  277.  *
  278.  * It is an error to call this function without calling ComPause().
  279.  *
  280.  */
  281. USHORT COMMAPI ComResume(HCOMM hc);
  282.  
  283. /*
  284.  *
  285.  * ComGetFH():  get the file handle (HFILE) the comm module is
  286.  * using.
  287.  *
  288.  * If the comm routines were initialized with ComHRegister(),  the
  289.  * handle returned by this function will be the same handle passed
  290.  * to ComHRegister().
  291.  *
  292.  * NOTE: Programs must not use this handle with any file system
  293.  * calls (DosRead, DosWrite, DosClose, etc).  It may be used with
  294.  * DosDevIOCTL() to query device dependant info.
  295.  *
  296.  * The intended use for this function is so that one process can
  297.  * pass the file handle to another process.  Don't forget to
  298.  * call ComPause() before spawning another process that uses the comm
  299.  * port.
  300.  */
  301. HFILE COMMAPI ComGetFH(HCOMM hc);
  302.  
  303. /*
  304.  * ComWatchDog():  Enable/disable the "online" watchdog.
  305.  *
  306.  * When the watchdog is enabled,  and the state of the comm handle
  307.  * is no longer "online" (in the case of a modem,  the carrier has dropped),
  308.  * any Com functions that are blocked (ComRxWait, ComTxWait) become
  309.  * unblocked,  within the period specified by the "Seconds" paramater.
  310.  *
  311.  * It is up to the application to notice that the device is no longer
  312.  * online,  after the blocked Com function returns.
  313.  *
  314.  * Obviously,  one must remember to disable the watchdog feature between
  315.  * phone calls.
  316.  *
  317.  * When a device is first initialized by the comm moduel (via ComOpen() or
  318.  * ComHRegister()) the watchdog feature is disabled.
  319.  *
  320.  * The "Seconds" paramater is ignored unless "OnOff" is TRUE.
  321.  *
  322.  * If "OnOff" is TRUE,  and "Seconds" is 0,  the current watchdog period
  323.  * is used.  When first initialized,  the watchdog period is 3 seconds.
  324.  */
  325. USHORT COMMAPI ComWatchDog(HCOMM hc, BOOL OnOff, USHORT Seconds);
  326.  
  327. /*******************************************************************
  328.  *                                                                 *
  329.  * Thus far, all functions listed are applicable to many           *
  330.  * device types,  including named pipes.  The 3 functions          *
  331.  * that follow, however, are specific to COM0x.SYS (rs232c ports). *
  332.  *                                                                 *
  333.  *******************************************************************/
  334.  
  335. /*
  336.  * Get/Set DBC.  See os/2 docs on "DCBINFO", used in a
  337.  * DosIOCTL(ASYNC_GETDCBINFO) call (ioctl category 1, function 73h)
  338.  *
  339.  *
  340.  * NOTE: ComSetDCB() ignores bits 0, 1 and 2 of the "fbTimeout"
  341.  * field of the DCBINFO structure. (if you are using the IBM toolkit,
  342.  * this is called "flags3" of the DCB).  These bits control the type
  343.  * of read timeout processing, and write timeout processing that the
  344.  * com01.sys device driver uses.  The Com() api insists that
  345.  * "write infinite timeout processing" NOT be enabled,  and
  346.  * "Wait-for-something read timeout processing" be in effect, so this
  347.  * function overrides the above mentioned bits to ensure this.
  348.  *
  349.  */
  350. #ifdef IOCTL_ASYNC
  351. USHORT COMMAPI ComGetDCB(HCOMM hc, PDCBINFO pdbc);
  352. USHORT COMMAPI ComSetDCB(HCOMM hc, PDCBINFO pdcb);
  353. #endif
  354.  
  355. USHORT COMMAPI ComSetBaudRate(HCOMM hcomm,
  356.      LONG bps,
  357.      CHAR parity,
  358.      USHORT databits,
  359.      USHORT stopbits);
  360.  
  361.  
  362.  
  363. #ifdef INCL_WININCLUDED
  364. /* First new function added since version 1.00:
  365.  *
  366.  * ComRxPostMsg() -- register a PM window handle. When data is
  367.  * available,  a message will be Posted to it.
  368.  *
  369.  * Be sure to deregister the window before it is destroyed.  Do
  370.  * this by passing 0 for the window handle (hwnd).
  371.  *
  372.  *
  373.  *  hwnd = Window handle or zero.
  374.  *  msg  = message to post (WM_USER for example)
  375.  *  mp1  = user defined (passed unchanged to hwnd)
  376.  *  mp2  = user defined (passed unchanged to hwnd)
  377.  *
  378.  *
  379.  * NOTES:  When the message is posted, it is advisory only.  The message
  380.  *         does not need to be processed.  The message will be posted
  381.  *         again when more data arrives.  The receiver should call
  382.  *         ComRead() to get the data when convenient.
  383.  *
  384.  *
  385.  * Returns:        0: success.
  386.  *          non-zero: OS/2 error
  387.  */
  388.  
  389. USHORT COMMAPI ComRxPostMsg(HCOMM hcomm, HWND hwnd, USHORT msg,
  390.     MPARAM mp1, MPARAM mp2);
  391.  
  392. #endif
  393.