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

