SocktSpy/32... A Trace/Debug utility for Winsock 1.1 applications 1. Introduction..A Word about Shareware 1.1 What Shareware is 1.2 Advantages of Registration. 1.3 Registration of the SocktSpy Application 1.4 Licensing Agreement 1.5 Warranty 2. SocktSpy/32 System Requirements 2.1 Operational Overview 2.2 Linking an application with WnTch32.dll 2.3 Launching a Winsock application from SocktSpy 3. Installation 3.1 Making Backups 3.2 Installing SocktSpy/32 4. Basic Menu Selections 4.1 ToolBar 4.2 Starting/Stopping the Trace 4.3 Display Preferences 4.3.1 Color & Font Selection 4.3.2 WinSock API Display Options 4.4 StatusBar 5. Buffer Configuration 5.1 Trace Buffer Operation 5.1.1 Storing Send/Recv Data 5.1.2 Displaying Send/Recv Data 5.2 Trap Buffer Selection 6. Browsing Captured Data 6.1 Browse Menu Options 6.1.1 Record Index 6.1.2 Scrolling Operation 6.2 Block Operations 6.2.1 Print 6.2.2 Copy to Clipboard 7. Using Filters 7.1 API Command Filters 7.2 Using WinSock Error Status Filters 7.3 Restricting Trace to a designated socket 8. Trap Buffer Operation 8.1 Trigger 8.2 Browsing the Trap Buffer 9. Technical Support 9.1 Contacting WinTECH --------------------------------------------------------------------------- 1. Introduction..A Word about Shareware --------------------------------------------------------------------------- 1.1 What is Shareware Shareware is a distribution method, not a type of software. Shareware products may be freely distributed among potential users with each user given an opportunity to fully evaluate the software over a specified period of time. This distribution method gives users a chance to try software before buying it. If the particular shareware application provides a service that the user wishes to continue beyond the specified evaluation period, a registration payment to the software author is required. Copyright laws apply to both Shareware and commercial software, and WinTECH Software retains all rights to its software products with the following exception: WinTECH Software specifically grants the right to copy and distribute unregistered copies of the SocktSpy/32 Application to all interested parties for an evaluation period not to exceed thirty-days. There are to be no fees involved in its transfer without expressed written consent from WinTECH Software. 1.2 Advantages of Registration The Shareware distribution system depends upon the integrity of the user to make the required registration payment only if the application proves itself useful. Shareware products have the ultimate money-back guarantee. If the product is not used, no payment is required. Registration of Shareware products support this system of distribution and allow continued development of low-cost high quality software solutions. 1.3 Registration of the SocktSpy/32 Application Unregistered copies of the SocktSpy Application are functionally equivalent to registered copies with the following exception: To encourage registration, a limit is placed on the number of buffers which may be allocated for the Trace & Trap Windows. This limit does not effect the ability of a user to fully evaluate either the functionality or through-put of the application. Registration of the SocktSpy Application requires a registration fee of $45.00 be submitted to WinTECH Software. The user shall receive in return the most recent version of SocktSpy/32 with all buffer limit constraints and registration reminder screens disabled. The user shall also receive free technical support for a period of three months after registration. WinTECH Software plans to provide a commercial non-shareware version of the application, (SocktSpy/32-PRO), which will contain support for API socket calls not included in the shareware version, (i.e. WSA Windows extensions, database reference calls, and WSAAsync callback notifications). Registered users of the shareware application may, at any time, apply the original registration fee toward the purchase of the extended version. 1.4 Licensing Agreement Registered WinTECH software is protected by both United States Copyright Law and International Treaty provisions. Therefore, you must treat this software just like a book with the following single exception. WinTECH Software authorizes you to make archival copies of the software for the sole purpose of backing-up your software and protecting your investment from loss. By saying "just like a book," WinTECH means for example that this software may be used by any number of people and may be freely moved from one computer location to another so long as there is no possibility of it being used at two locations at the same time. Execution of two copies of the same registered SocktSpy application at the same time constitutes a Copyright violation and is expressly prohibited. This licensing agreement does not apply to the unregistered, shareware version of SocktSpy/32 nor the Winsock interceptor dll's supplied with the system. WnTch32.dll & WnTch32b.dll may be distributed with a user's application to support tracing API calls in the field, however, each version of the SocktSpy/32 executable, (Trace/Debug Application), must be licensed individually by the end-user. 1.5 Warranty With respect to the physical diskette and physical documentation enclosed herein, WinTECH Software warrants the same to be free of defects in materials and workmanship for a period of 30 days from the date of registration. In the event of notification within the warranty period of defects in material or workmanship, WinTECH will replace the defective diskette or documentation. WinTECH Software disclaims all other warranties, expressed or implied, including without limitation, the warranties of merchantability and of fitness for any purpose. WinTECH Software assumes no liability for damages, direct or consequential, which may result from the use of this program. --------------------------------------------------------------------------- 2. SocktSpy/32 System Requirements --------------------------------------------------------------------------- 2.1 Operational Overview Socket Spy/32 is a trace/debugging system designed for developers of WINSOCK version 1.1 communications applications. It provides tracing capabilities for monitoring API socket calls between the application and the communications system by transparently tapping into the messaging interaction between the two. As protocol messages are exchanged, they are duplicated and routed to a Trace Window for user inspection. SocktSpy-32 is fully compatible with Winsock Version 1.1, and supports the standard API socket calls. The spy window displays API calls in real-time and may be configured with various filters and traps to isolate design problems. SocktSpy/32 does not replace the WSock32.dll, rather it operates with the installed version of Winsock to trap API calls using an interceptor library, (WnTch32.dll). A valid Wsock32.dll must be operational with the installed communications system for tracing with the SocktSpy/32 application. The Socket Spy/32 system generally requires that the user application be linked using WNTCH32.LIB rather than WSOCK32.LIB, however, the capability exists for launching a 100% WINSOCK VER 1.1 COMPLIANT application from within the Spy window without re-linking the source code with the interceptor dll. 2.2 Linking an application with WnTch32.dll The SocktSpy system was designed for developers of Winsock compatible applications. WnTch32.dll is a Winsock 1.1 compatible interceptor and debugging .dll which must be linked with the application under test to allow tracing and monitoring of sockets API calls. WnTch32 is not a Wsock32 .dll. It simply accepts API calls from an application and forwards control to the installed Winsock while transfering copies of all pass-thru data to the SocktSpy application for monitoring and display. A version of WSock32 compatible with the underlying communications protocol must be installed on the system under test. Furthermore, the WnTch32.dll only supports those API calls defined by the WinSock 1.1 specification. Some Winsock suppliers may utilize extensions to the standard which take advantages of special characteristics of their communications systems. Any extensions to the Winsock specification used by the application under test can not be supported by the SocktSpy system, without modification to the interceptor .dll. (If required, special modifications may be made by WinTECH Software to support specific vendor's enhancements to the Winsock implementation.) There are two ways to initiate the link with the WnTch32 interceptor .dll. The first, and most appropriate is to link in WnTch32.lib with the application during the build process. (WnTch32.lib would replace WSock32.lib in the application make file. WnTch32 effectively replaces all API functions defined in the Winsock.h header file, so no source modules would need to be re-compiled.) This will insure that all sockets calls will be passed to the interceptor .dll first and allow effective monitoring by the Spy. A common practice is to link in WnTch32.lib for the debugging version of an application, and WSock32.lib with the release version. WnTch32.dll may be freely distributed, and a user is permitted to include the spy interceptor functionality in his own product if desired. Each instance of the SocktSpy itself, however, must be licensed individually. 2.3 Launching a Winsock application from SocktSpy The second way to initiate a trace operation using the WnTch32.dll functionality is to launch a Winsock compatible application from within the SocktSpy application. A menu selection from within the SocktSpy application allows a third-party Winsock application to be started. If the application conforms to the Winsock version 1.1 specification with no extended API calls, SocktSpy will attempt to intercept the function references as though the WnTch32.dll had been linked in with the application during build. A temporary disk file will be created in the targeted directory to accomplish the links necessary for performing the trace. -------------------------------------------------------------------------- 3. Installation -------------------------------------------------------------------------- 3.1 Making Backups The distribution diskette is not copy-protected, and the registered user may make backup copies as required. The SocktSpy/32 application may be moved from one PC to another so long as the basic licensing agreement of only one copy in use at a time is maintained. Site licenses are available for commercial users by contacting WinTECH Software. 3.2 Installing SocktSpy/32 Installation of the SocktSpy/32 Application involves simply copying the socspy32.exe & socspy32.hlp files from the distribution diskette to a working directory on the hard disk. wntch32.dll & wntch32b.dll should bo copied to the same directory as the working copy of wsock32.dll. After running the application for the first time, a configuration file will be created on the working directory. socspy32.cfg represents the user configurable selections, (character font, filters, trigger, etc.), in effect at the time the program terminated. These settings will be restored the next time SocktSpy is started. -------------------------------------------------------------------------- 4. Basic Menu Selections -------------------------------------------------------------------------- 4.1 ToolBar Toolbar buttons provide access to the commonly used menu options defined below: FILE OPEN: Fills the display buffer with the contents of a previously saved trace operation. FILE SAVEAS: Copies the displayed buffer, (trace or trap), to a defined disk file. TIMESTAMP: Include timestamp with display of each API trace record. VERBOSE: Display extended information for each API trace record. FILTER: Specify filtering characteristics for trace operation. TRAP: Enable/disable logic trap. START TRACE: Begin monitoring socket calls. STOP TRACE: Stop monitoring. COPY: Copy selected trace records to Windows clipboard. PRINT: Print selected trace records. ABOUT: Display copyright notice and software revision levels. 4.2 Starting/Stopping the Trace The SocktSpy Trace Window operates in two modes. During an active trace operation, API calls are displayed as they occur between the application and the Winsock.dll. During a browsing operation, the user may scroll back and forth through the trace buffer, switch between the trace and trap buffers, copy & print trace records and save data to a disk file. All message interaction between the application under test and the .dll continue as normal during browse operations, however the spy does not receive the information except during an active trace. Trace operations are controlled via two menu option/toolbar buttons (START & STOP). 4.3 Display Preferences 4.3.1 Color & Font Selection Menu options are provided to select the font and colors used to display the results of a trace. Any installed font may be used to suit the taste of the user. Up to five colors may be selected; one for the window background and four text pens used to display API trace records. 4.3.2 WinSock API Display Options The display of trace records is controlled by four options accessible from the PREFERENCES menu selection. TIMESTAMP: Include timestamp with display of each API trace record. VERBOSE: Display extended information for each API trace record. Verbose display shows arguments passed to the Winsock.dll for each API call as well as data buffers transfered via send(), sendto(), recv() & recvfrom(). VERTICAL SPACE: Simply adds an extra CRLF after the display of each record on the display. DATA ONLY: This option allows the display to represent only the data blocks passed through the socket as a result of the send(), sendto(), recv(), or recvfrom() API calls. A description of the actual call/argument list is not displayed. 4.4 StatusBar The statusbar is used to represent the status of the trap buffer and trigger during an active trace operation. The trap buffer is cleared whenever the trap is activated and the trace starts. It will be filled with an image of the trace buffer at the time the trigger event occurs. The statusbar is also used to display the record numbers represented by the SocktSpy display. The index of the first record displayed in the window and the maximum number of trace records contained in the displayed trace buffer are depicted. -------------------------------------------------------------------------- 5. Buffer Configuration -------------------------------------------------------------------------- 5.1 Trace Buffer Operation As API record descriptions are received from the interceptor dll, they are copied in their entirety to buffers dynamically allocated within the SocktSpy. Dll buffers are then released for re-use by WnTch32. Memory buffers allocated by the SocktSpy trace window vary in size depending upon the amount of data to maintain. This is minimal for everything except data blocks captured as a result of the send()/recv() operations. The maximum size for SocktSpy memory block allocation is four times the BufSize parameter specified for the DLL. API call records are collected and maintained in a circular list of buffers with new data replacing old data. The size of the circular list is controlled by a dialog box entry accessible from the SocktSpy Filter Selection Dialog. Buffer parameters may only be changed while the SocktSpy is in a Browse mode of operation. They may not be changed during an active trace operation. An unregistered shareware version of the SocktSpy application places a limit of 50 records on the circular list size. 5.1.1 Storing Send/Recv Data Normally, the SocktSpy application would be configured to monitor all data passed through a socket. In applications involving large block transfers, it may be desirable to limit the amount of data captured by the spy. The user may select to only capture partial data blocks from the send(), sendto(), recv(), & recvfron() socket calls. This maximizes the through-put of the application/spy/winsock interaction. 5.1.2 Displaying Send/Recv Data The user may also elect to only display partial data block information within the spy window. Data block displays may be reduced to show a "thumbprint" of the actual data collected during an real-time trace, and subsequently expanded for a more detailed examination during browse. 5.2 Trap Buffer Selection SoctkSpy provides a unique list of data buffers used to take a snapshot of the normal trace buffer based on the occurrence of an event trigger. During a trace operation, SocktSpy constantly compares API trace records received from the interceptor dll with a trigger mask configured by the user. If the received data matches the trigger specification, trace records are moved into the trap buffer and the trigger is disabled. As additional records are received, they will overwrite records in the trace buffer, but the trap buffers maintain the original record descriptions at the time of the trigger. The trap buffer may be configured to position the trigger in the front, middle, or back. In other words, the trap buffer can be setup to capture the data records immediately preceeding the trigger, immediately after the trigger, or surrounding the trigger. -------------------------------------------------------------------------- 6. Browsing Captured Data -------------------------------------------------------------------------- 6.1 Browse Menu Options Timing operation of messaging interactions between the application under test, the communications system, and the spy application are maximized by restricting most user menu selections to an off-line browse mode of operation. These include the ability to scroll the display, copy and print operations. 6.1.1 Record Index The display of each API record includes a buffer index designating its position in the list. The record index of the first record displayed on the screen is also listed in the SocktSpy statusbar. If the trap buffer is being displayed, the event which triggered the capture will have its record identifier set to [TRIGGER]. 6.1.2 Scrolling Operation Vertical scroll bar support is provided for browsing either the trace or trap buffers. The scrollbar is disabled, (hidden), during an active trace. 6.2 Block Operations 6.2.1 Print A group of API trace records may be selected for print operations by specifying the starting and ending indexes. Printer output of data will conform to the same options selected for the window display, (i.e. TIMESTAMP, VERBOSE, VERTICAL SPACE, & DATA ONLY options apply). 6.2.2 Copy to Clipboard API records may also be copied to the Windows clipboard based on a starting and ending record index. Data will be copied in an ASCII format as would be displayed on the screen. -------------------------------------------------------------------------- 7. Using Filters -------------------------------------------------------------------------- 7.1 API Command Filters SocktSpy provides trace support for the following WinSock API function references: accept() bind() closesocket() connect() getpeername() getsockname() getsockopt() htonl() htons() inet_addr() inet_ntoa() ioctlsocket() listen() ntohl() ntohs() recv() recvfrom() select() send() sendto() setsockopt() shutdown() socket() Tracing may be selectively enabled/disabled for each API event. 7.2 Using WinSock Error Status Filters Two options are provided within the Filter Specification to capture data using the return value from the WinSock.dll in response to a given API call. WSAEWOULDBLOCK is a status indication returned from the dll in response to an API call request which cannot be immediately completed. This may or may not be a normal occurrence for any given WinSock application. A filter specification option allows all API requests which return WSAEWOULDBLOCK to be ignored, (in terms of the trace operation). SocktSpy may also be configured to only monitor API calls which return an error status from WinSock. 7.3 Restricting Trace to a designated socket During a trace operation, multiple sockets may be active, from one or more applications linked with the WnTch32 interceptor dll. Monitoring of API records may be restricted to only those associated with a given socket by specifying the socket id within the Filter Specification. Since the filtering characteristics of the SocktSpy system may be changed during an active trace operation, the user may monitor socket assignments made in real-time and selectively monitor those of interest. -------------------------------------------------------------------------- 8. Trap Buffer Operation -------------------------------------------------------------------------- 8.1 Trigger As mentioned previously, the trap buffer represents a snapshot of trace records contained in the normal trace buffer at the time of a user defined logic trigger. The trigger spcification may be associated with a particular API reference, API status return value, or data contained in a transmitted or received data block. In the case of an event triggered from a data block operation, the user may specify a byte pattern and an offset from the start of the block to begin the comparison. 8.2 Browsing the Trap Buffer During a browsing operation, the display may be switched back and forth between the trace buffer and trap buffer by selecting an option from the main SocktSpy menu. Scrolling operations, copy & print operations, and display parameters operate identically for either buffer display. -------------------------------------------------------------------------- 9. Technical Support -------------------------------------------------------------------------- 9.1 Contacting WinTECH Additional information and FAQ may be found on the World-Wide-Web at: http://www.win-tech.com For technical questions, problems with installation and/or operation of the SocktSpy application, or feedback concerning enhancements or improvements, please contact: WinTECH Software P.O. Box 907 Lewisburg, WV 24901 (304) 645-5966 email: jross@win-tech.com