home *** CD-ROM | disk | FTP | other *** search
/ Collection of Education / collectionofeducationcarat1997.iso / COMPUSCI / CENVIW.ZIP / COMM.LIB < prev    next >
Text File  |  1993-11-14  |  21KB  |  464 lines
  1. // Comm.lib - Windows routines for accessing (open, read, write, etc...)
  2. //            the COMM ports (serial ports, printer ports).  You may want
  3. //            to #include this file in your Cmm source, or just copy out
  4. //            the parts that you want.
  5. //
  6. //---- OpenComm(): Open COMM device and get handle to it -------------------
  7. // SYNTAX: int OpenComm(string CommName[,int ReadQueueSize,int WriteQueueSize])
  8. // WHERE: CommName: String name for the device, such as "COM1", "COM2", "LPT1", etc...
  9. //        ReadQueueSize, WriteQueueSize: Optional buffer sizes to prepare area
  10. //            for data to reside while it is being received or sent.  These
  11. //            values are ignored by Windows for LPT ports. If these
  12. //            are not supplied then they default to the following
  13.             #define DEFAULT_COMM_QUEUE_SIZE  500
  14. // RETURN: Returns a handle to the now-open communications device for subsequent
  15. //         calls to ReadComm(), WriteComm(), etc.  If error, then returns a
  16. //         negatvie value, which may be one of the following:
  17.       #define IE_BADID    (-1)   // Invalid or unsupported ID
  18.       #define IE_BAUDRATE (-12)  // Unsupported baud rate
  19.       #define IE_BYTESIZE (-11)  // Invalid byte size
  20.       #define IE_DEFAULT  (-5)   // Error in default parameters
  21.       #define IE_HARDWARE (-10)  // Hardware Not Present
  22.       #define IE_MEMORY   (-4)   // Unable to allocate queues
  23.       #define IE_NOPEN    (-3)   // Device not open
  24.       #define IE_OPEN     (-2)   // Device already open
  25. // NOTES: Call CloseComm before terminating your program. You may want to set
  26. //        up an atexit() function to ensure this.
  27. //
  28. //---- CloseComm(): Close COMM device opened with OpenComm ------------------
  29. // SYNTAX: int CloseComm(int CommHandle)
  30. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  31. // RETURN: Returns 0 for success, else a negative error. This call is expected
  32. //         to success and so most programmers don't test the return code.
  33. // NOTES: All characters in the output queue are sent before the device is closed.
  34. //
  35. //---- ReadComm(): Read characters from open COMM device ---------------------
  36. // SYNTAX: int ReadComm(int CommHandle,byte[] DestBuffer,int bufferLen[,int CommError])
  37. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  38. //        DestBuffer: Data will be read into this buffer, will be created as a
  39. //                    buffer if it is not already
  40. //        bufferLen: Maximum number of bytes to read into buffer
  41. //        CommError: If there is a communications error during read, then this will
  42. //                   be set to the error, else 0 for no error.  See CommError
  43. //                   values below.
  44. // RETURN: Returns number of bytes read, which is 0 up to bufferLen
  45. // NOTES: GetCommError() will always be called, whether or not the optional
  46. //        CommError is supplied in this function, to clear port errors.  If
  47. //        return value is bufferLen, then there may be more characters
  48. //        available.
  49. //
  50. //---- GetCommError(): Get COMM port error, and clear error -----------------
  51. // SYNTAX: int GetCommError(CommHandle,[struct CommStatus])
  52. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  53. //        CommStatus: an optional structure that will be set with the
  54. //        following elements
  55. //          bool fCtsHold     Transmit is on CTS hold
  56. //          bool fDsrHold     Transmit is on DSR hold
  57. //          bool fRlsdHold    Transmit is on RLSD hold
  58. //          bool fXoffHold    Received handshake
  59. //          bool fXoffSent    Issued handshake
  60. //          bool fEof         End of file character found
  61. //          bool fTxim        Character being transmitted
  62. //          int  cbInQue      count of characters in Rx Queue
  63. //          int  cbOutQue     count of characters in Tx Queue
  64. // RETURN: Return 0 for no error, else an error that may be an OR combination
  65. //         of the following:
  66.       #define CE_RXOVER    0x0001   // Receive Queue overflow
  67.       #define CE_OVERRUN   0x0002   // Receive Overrun Error
  68.       #define CE_RXPARITY  0x0004   // Receive Parity Error
  69.       #define CE_FRAME     0x0008   // Receive Framing error
  70.       #define CE_BREAK     0x0010   // Break Detected
  71.       #define CE_CTSTO     0x0020   // CTS Timeout
  72.       #define CE_DSRTO     0x0040   // DSR Timeout
  73.       #define CE_RLSDTO    0x0080   // RLSD Timeout
  74.       #define CE_TXFULL    0x0100   // TX Queue is full
  75.       #define CE_PTO       0x0200   // LPTx Timeout
  76.       #define CE_IOE       0x0400   // LPTx I/O Error
  77.       #define CE_DNS       0x0800   // LPTx Device not selected
  78.       #define CE_OOP       0x1000   // LPTx Out-Of-Paper
  79.       #define CE_MODE      0x8000   // Requested mode unsupported
  80. // NOTES: Many of the previous function call this function with no CommStatus
  81. //        just to clear any potential errors
  82. //
  83. //---- WriteComm: Write characters to open COMM device --------------------
  84. // SYNTAX: int WriteComm(int CommHandle,byte[] SrcBuffer,int bufferLen[,int CommError])
  85. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  86. //        SrcBuffer: Data will be written from this buffer
  87. //        bufferLen: Number of bytes to written from this buffer
  88. //        CommError: If there is a communications error during write, then this will
  89. //                   be set to the error, else 0 for no error.  See CommError
  90. //                   values below.
  91. // RETURN: Returns number of bytes written, which is 0 up to bufferLen. If less
  92. //         than bufferLen then there was certainly an error.
  93. // NOTES: GetCommError() will always be called, whether or not the optional
  94. //        CommError is supplied in this function, to clear port errors.  If there
  95. //        is not enough room in the output queue then some characters will be
  96. //        lost, and so if you're not sure there's enough room you may want to
  97. //        call GetCommError() to see how much room is available.
  98. //
  99. //
  100. //---- UngetCommChar: Place one character back into the receive queue -------
  101. // SYNTAX: int UngetCommChar(int CommHandle,byte Character)
  102. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  103. //        Character: Single character to place back in read queue
  104. // RETURN: Zero if successful, else negative error code
  105. // NOTES: You can only place one character back in the queue.  That character
  106. //        must be read out of the queue before placing another
  107. //
  108. //
  109. //---- TransmitCommChar: Place character at head of tranmsit queue ---------
  110. // SYNTAX: int TransmitCommChar(int CommHandle,byte Character)
  111. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  112. //        Character: Single character for immediate transmission
  113. // RETURN: Zero if successful, else negative error code.  Error if previous
  114. //         TransmitCommChar() has not been transmitted yet.
  115. //
  116. //
  117. //---- FlushComm: Flush all characters out of receive or transmit queue -----
  118. // SYNTAX: int FlushComm(int CommHandle,int WhichQueue)
  119. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  120. //        WhichQueue: 0 to flush transmit queue, else 1 to flush receive queue
  121. // RETURN: Zero if successful, else negative error code for invalid
  122. //         CommHandle or invalid WhichQueue.
  123. //
  124. //
  125. //---- SetCommBreak: Suspend transmission and fo to break state -------------
  126. // SYNTAX: int SetCommBreak(int CommHandle)
  127. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  128. // RETURN: Return 0 for success, else negative if CommHandle is invalid
  129. // NOTES: Suspends transmission and places the line in the break state until
  130. //        ClearCommBreak() is called.
  131. //
  132. //
  133. //---- ClearCommBreak: Restore transmission and set to non-break state ------
  134. // SYNTAX: int ClearCommBreak(int CommHandle)
  135. // WHERE: CommHandle: value returned from previous successful call to OpenComm()
  136. // RETURN: Return 0 for success, else negative if CommHandle is invalid
  137. //
  138. //
  139. //---- EscapeCommFunction: Perform an extended fun