home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 19 / CD_ASCQ_19_010295.iso / vrac / commspy.zip / COMMSPY.DOC < prev    next >
Text File  |  1994-05-21  |  7KB  |  123 lines
  1. 12-4-94 DAL  CommSpy.Doc
  2.  
  3. INSTALLING COMMSPY
  4.   There are 6 files associated with Commspy. These are COMMSPY.EXE, 
  5. CSPYHKS.DLL, COMMSPY.HLP, BC30RTL.DLL, SH20W16.DLL. All other files 
  6. required are created dynamically by CommSpy. The files COMMSPY.EXE, 
  7. CSPYHKS.DLL, and COMMSPY.HLP can all be installed into a local directory
  8. wherever you like. The files BC30RTL.DLL and SH20W16.DLL may also be used
  9. by other applications, and so they should be copied into the 
  10. WINDOWS\STSTEM directory. BC30RTL.DLL is a Borland product and is used by
  11. CSPYHKS.DLL for runtime library functions. SH20W16.DLL is a library that
  12. provides memory management services; all memory allocations that commspy 
  13. requires are implemented through this library.
  14.   Note: COMMSPY.DOC (this file) is also included with those files.
  15.  
  16. OPERATION:
  17.   Commspy intercepts API function calls made to the serial communications 
  18. services in Windows by other applications. It accomplishes this by patching 
  19. the entry point of each function call with a piece of code that directs the
  20. program flow into CSPYHKS.DLL. Once the API function has been intercepted,
  21. Commspy records all the parameters passed to the function and then allows 
  22. the original call to proceed. The menu option "Start Spying" toggles the
  23. interception on-and-off. When it is off, the API calls are no longer 
  24. intercepted and the patch is removed.
  25.  
  26. SPECIAL FEATURES:
  27.   The menu option "Filter Uninteresting Events" affects two
  28. API function calls; ReadComm, and GetCommError. Most Windows
  29. programs are written to operate in a "polled" mode, which is a fancy way
  30. of saying that they must continually check the serial port to see if 
  31. anything happened since the last time they checked. 
  32.   Many applications call the function GetCommError to do the polling. 
  33. This function not only tells the app if an error has occurred, it clears 
  34. any pending errors, and also tells the app how many characters are present 
  35. in the transmit and receive queues. An app may call this function to 
  36. clear outstanding errors and get the quantity of characters it has just 
  37. received; if any are available it will then call ReadComm to get the 
  38. characters.
  39.   Some apps do not call GetCommError, they just call ReadComm and check to 
  40. see if they were able to get anything. This is not the recommended way to 
  41. do it under Windows, but some apps did.
  42.   Based upon how the app implemented its polling logic, it may make a 
  43. lot of calls to either GetCommError or ReadComm as it looks for work to do,
  44. but many of these calls return a value that simply tells the app that nothing
  45. happened. This is what the option "Filter Uninteresting Events" is designed
  46. to detect. In order to avoid filling up the screen and log file with 
  47. a list of events that signify nothing, when this option is turned on it
  48. will ignore these polling type events that mean that the polling operation
  49. indicated nothing of interest was occurring.
  50.   For ReadComm, if 0 bytes were read, it is filtered out and ignored.
  51.   For GetCommError, if the status is 0 (meaning ok) and the transmit and
  52. receive queues are both empty, it is filtered out and ignored.
  53.  
  54. DISPLAY OPTIONS:
  55.   When the option "Record Task/Module Data" is turned on, the task and 
  56. module data of the caller of the API function is displayed. When the
  57. option "Parameter Display" is on, all parameters to the API function are
  58. displayed. When "Show Time in elapsed units" is on, the value displayed is
  59. the interval between the current function and the last function that was 
  60. called. If the option is off, the time since Commspy was started to the 
  61. time the API function was called is displayed.
  62.  
  63. RINGBUFFERS:
  64.   When characters are actually read or written to one of the ports, Commspy
  65. saves those characters off into a special buffer called a ring buffer. This
  66. will happen after a call to either ReadComm, WriteComm, or TransmitCommChar.
  67. This is called a ring buffer because when the buffer fills up, new characters
  68. that are saved overwrite previous characters. Each of the ports has a 
  69. separate buffer, (COM1-4), and each buffer can contain up to approximately
  70. 10,000 characters.
  71.   When the option "AutoOpen/Close on use" is on, then whenever the API 
  72. function OpenComm or CloseComm is called, Commspy will automatically open or
  73. close the appropriate ring buffer window.
  74.  
  75.   CommSpy considers each call to ReadComm and WriteComm to be a separate
  76. transaction, and when it saves the data, it marks the first character in 
  77. that transaction with a flag that indicates that this character was the 
  78. start of a transaction. When the display option "One line per transaction"
  79. is on, it will begin a new display line each time it finds a character 
  80. with this flag. This is useful when programs read and write characters 
  81. as blocks.
  82.  
  83. COMM PORT STATUS DISPLAY  (*** NEW FEATURE ALERT***)
  84.   Commspy is capable of showing an LED style display that shows the
  85. current status of the hardware handshaking lines, and whether or not
  86. characters are present in the transmit and receive queues. The user 
  87. should keep in mind that this is a software display only, and may not
  88. accurately reflect the actual status of the comm port status. Discrepancies
  89. may occur when the status display is open but there aren't any applications
  90. that actually have the port open. The display is based on reading values
  91. out of comm.drv, and comm.drv does not update the hardware handshaking lines
  92. when the port is not in use. Also, the Rx and Tx display is based upon the
  93. quantity of characters present in the software buffers that hold these 
  94. characters; if an application is not removing characters from the receive
  95. queue then commspy will show the Rx line as on even though there isn't an
  96. actual reception occurring. Also, if for some reason the commport is
  97. incapable of transmitting, then the Tx line will show ON even though
  98. characters are not physically being transmitted.
  99.   The display of the output lines RTS and DTR should, however, be 
  100. completely accurate, as Commspy reads these values directly out of the 
  101. communications port and does not rely on other software for its values.
  102.   All outputs are colored RED and all inputs to the port are colored GREEN.  
  103.  
  104.   
  105. FUNCTION INTERCEPTION LIST
  106.   OpenComm,
  107.   CloseComm,
  108.   WriteComm,
  109.   ReadComm,
  110.   BuildCommDCB,
  111.   ClearCommBreak,
  112.   EnableCommNotification,
  113.   EscapeCommFunction,
  114.   FlushComm,
  115.   GetCommError,
  116.   GetCommEventMask,
  117.   GetCommState,
  118.   SetCommBreak,
  119.   SetCommEventMask,
  120.   SetCommState,
  121.   TransmitCommChar,
  122.   UngetCommChar,
  123.