The TraceFile property is used to specify the name of the
file that is created when logging is enabled. If this property is set
to an empty string (the default value), then a file named
SocketTools.log is created in the current user's Documents
folder. It is recommended that you always specify a complete path to
the log file. The path can contain environment variable names surrounded
by percent (%) symbols which will be expanded prior to opening or
creating the file. If the file already exists, the current process
must have read and write permission to access the file.
If the file exists, the output is appended to the file, otherwise
the file is created. Since logging is enabled per-process, the log
file is shared by all instances of the controls being used. If you
create multiple instances of the control, you only need to enable
logging for a single instance. Because log files can grow very quickly,
even with modest applications, it is recommended that you delete the
file when it is no longer needed.
The log file has the following format:
APPNAME 105020 0000 INF: WSAAsyncSelect(46, 0xcc4, 0x7e9,0x27) returned 0
APPNAME 105020 0015 WRN: connect(46, 192.0.0.1:1234, 16) returned -1 [10035]
APPNAME 111535 0000 ERR: accept(46, NULL, 0x0) returned -1 [10038]
The first column contains the name of the process. The second column
is the local time in hours, minutes and seconds. The third column is the
elapsed time in milliseconds since the previous function call. The fourth
column identifies if the logged event contains information, a warning, or
an error. What follows is the name of the network function being called,
the arguments passed to the function and the function's return value. If
a warning or error is reported, the error code is appended to the record
and the value is enclosed in brackets.
If function parameters are passed as integer values, they are recorded
in decimal. If the parameter or return value is a memory address, it is
recorded as a hexadecimal value preceded with "0x".
Those functions which expect network addresses are displayed in one of
two formats:
aa.bb.cc.dd:nnnn
[xxxx:xxxx:xxxxx:xxxx::xxxx]:nnnn
With an IPv4 address, the first four numbers separated by periods
represent the IP address, and the number following the colon represents
the port number in host byte order. If an IPv6 address is used instead
of IPv4, the address will be a series of hexadecimal digits separated
by colons and enclosed in brackets. In the second line of the above
example, the control is attempting to connect to a system with the
IPv4 address 192.0.0.1 on port 1234.
If the log file cannot be created, or the user
does not have permission to modify an existing file, the error is
silently ignored and no output will be generated.