|
Many of the SocketTools components share a common set of properties,
each with the same general functionality. This approach makes it easier
to understand the interface and reduces the overall learning curve.
However, it is important to note that some common properties may affect
the operation of the controls in different ways. Although this guide
can provide a general overview of those properties and how they are
used, it is recommended that you also review the Technical Reference
material for the control that you are using in your application.
| Property Name |
Description |
| AutoResolve |
Determines if host names and IP addresses are automatically
resolved |
| Blocking |
Gets and sets the blocking state of the control |
| HostAddress |
Gets and sets the IP address of the server |
| HostName |
Gets and sets the name of the server |
| IsBlocked |
Return if the control is blocked performing an operation |
| IsConnected |
Determine if the control is connected to a server |
| IsReadable |
Return if data can be read from the server without
blocking |
| IsWritable |
Return if data can be sent to the server without
blocking |
| LastError |
Gets and sets the last error that occurred on the
control |
| LastErrorString |
Return a description of the last error to occur |
| LocalAddress |
Return the IP address of the local host |
| LocalName |
Return the name of the local host |
| Password |
Gets and sets the password for the current user |
| RemotePort |
Gets and sets the port number for a remote connection |
| ResultCode |
Return the result code of the previous action |
| ResultString |
Return a string describing the results of the previous
action |
| Secure |
Set or return if a connection to the server is secure |
| State |
Return the current state of the control |
| ThrowError |
Enable or disable error handling by the container of the
control |
| Timeout |
Gets and sets the amount of time until a blocking operation
fails |
| Trace |
Enable or disable socket function level tracing |
| TraceFile |
Specify the socket function trace output file |
| TraceFlags |
Gets and sets the socket function tracing flags |
| UserName |
Gets and sets the current user name |
| Version |
Return the current version of the object |
The AutoResolve property controls how host names are
resolved by the control whenever the HostName or HostAddress
properties are set. By default, the property is set to False, which
means that the control does not attempt to resolve the host name
until a connection attempt is made. If the property is set to True,
then the control will immediately attempt to resolve the host name
into an IP address. Note that this can cause the control to block for
several seconds and negatively affect the performance of your
program. In most cases, this property should be set to False.
The Blocking property determines whether or not the control
operates in blocking (synchronous) mode or non-blocking
(asynchronous) mode. In blocking mode, the control waits for a given
operation to complete before returning control to your application
and executing the next statement. In non-blocking mode, control is
immediately returned to the program without waiting for the operation
to complete. In this case, events are used to notify the application
that a specific operation has completed.
In general, using a control in blocking mode means that your code
is going to be structured in a top-down fashion. For example, when
establishing a connection with a server, your program will
block until the connection has completed or has timed out. In
non-blocking mode, your code is event driven and must implement event
handlers to process those event notifications.
In general, it is recommended that you only establish a
non-blocking connection when you understand the implications of doing
so and it is required by your application. If you require multiple
instances of the control to establish connections to different
servers, it is preferable to create a multithreaded application
rather than attempt to use multiple instances of the control in a
single thread.
The HostAddress property is used to specify the IP address
of a server to connect to. The address should be given in dot
notation, which is four numbers separated by periods (e.g.:
192.168.0.10). If the AutoResolve property is set to True,
setting this property will force the control to immediately resolve
the address into a host name. Note that if you attempt to set this
property to the value of a host name, an exception will be thrown
indicating that the property value is invalid.
The HostName property is used to specify the name of a
server to connect to. This property will accept either host
names or IP addresses. If an IP address is specified, then setting
this property is similar to setting the HostAddress property. If the
AutoResolve property is set to True, setting this property will force
the control to immediately resolve the host name into an IP address.
The value of this property is used as the default host name when the
Connect method is called.
The IsBlocked property returns True if the control is
currently performing a blocking operation. This can be used in
conjunction with the State property to determine if the
control can be used to issue a command to the server or perform some
other operation. When the IsBlocked property returns False and
the State property returns a value of zero or one, the control
is in either an inactive or idle state. If the program attempts to
perform another operation while a blocking operation is in progress,
the error stErrorOperationInProgress is returned.
The IsConnected property returns True if a connection has
been made with a server, otherwise it will return False. The
property is read-only, and any attempt to set it to a value will
result in an error. To establish a connection, refer to the
Connect method.
The IsReadable property returns True if there is data
available to read using the Read method. If the property
returns False, then there is no data available to be read. In this
case, if the Blocking property is set to True, calling the
Read method will cause the control to block until data arrives
or the timeout period is exceeded; otherwise, it will fail and return
the error stErrorOperationWouldBlock. Note that this property can
only be used to determine if there is data available to be read, not
the amount of data.
The IsWritable property returns True if the control can
successfully write data using the Write method. If the
property returns False, then the control's internal buffers are full
and cannot accept any more data until the server reads some of
the data that has already been written. In this case, if the
Blocking property is set to True, the Write method will
cause the control to block until the data can be written or the
timeout period is exceeded; otherwise, it will fail and return the
error stErrorOperationWouldBlock. Note that this property can only be
used to determine if some data can be written, not the amount of
data.
The LastError property returns a numeric value which
identifies the last error that occurred. This property may be set to
zero, which will clear the last error code. Note that setting this
property to a non-zero value will have the effect of raising that
error, which must be handled by the application. Refer to the
Technical Reference for a complete list of error codes and their
description.
The LastErrorString property returns a description of the
last error that occurred, and corresponds to the value of the
LastError property. This property is typically used by an
application to display a message box to the user or include
information about the error in a log file. Note that the error
description will be in English, regardless of the current locale
settings.
The LocalAddress property returns the IP address of the
local host. Note that if the system is behind a router which uses
Network Address Translation (NAT) then the IP address returned will
be the address of the system on the local network, not the external
WAN address assigned to the router.
The LocalName property returns the fully qualified domain
name of the local host, if that information is available. If the
control is unable to determine the domain name for the local system,
then it will return the machine name as it was configured in the
Windows operating system.
The Password property is used to specify the password used
to authenticate the client session with the server. This property is
only used by those controls which support authentication. Setting
this property to an empty string will clear the current password
being used. This property should be used in conjunction with the
UserName property.
The RemotePort property is used to specify the port number
used to establish a connection with the server. A value of zero
specifies that the default port number for the protocol should be
used. For example, if the property is set to zero with the FTP
control, then the control will use port 21 by default. Valid port
numbers are in the range of 1 through 65535, and assigning the
property a value greater than this will result in an error. This
property value is used as the default port number when the
Connect method is called.
The ResultCode property returns the last numeric result
code sent by the server in response to a command. Result codes are
used to determine the status of a command issued by a server,
typically indicating success, failure or that the client must provide
additional information. It is important to note that different
protocols use result codes in different ways. Refer to the Technical
Reference for more information about how result codes are returned by
a specific control. To obtain a description of the result code, use
the ResultString property.
The ResultString property returns a description of the last
result code sent by the server in response to a command. The values
of these strings are completely dependent on the server
implementation and can vary from server to server. An application
should never depend on a server returning a specific description of a
command result and instead should rely on the ResultCode
property. The result string is primarily used to provide additional
information to the user or for debugging purposes.
The Secure property determines if the control should
establish a secure connection to the server. The default value for
this property is False, which specifies that a standard connection
should be established. If this property is set to True, then the
control will attempt to establish a secure connection using the
Secure Sockets Layer (SSL) or Transport Layer Security (TLS)
protocols.
The State property returns a numeric value which identifies
the current state of the control. A value of zero indicates that no
connection has been established with the control. A value of one
indicates that the control is in an "idle" state, waiting
to process the next request or send a command to the server. Values
greater than one indicate that the control is actively performing
some operation. Refer to the Technical Reference documentation for
the specific control to determine what each state value means.
The ThrowError property is used to determine how errors are
reported by the control when calling a method. The default value is
False, which specifies that errors should be returned as values from
the method call and the control should not throw an exception. If
this property is set to True, then methods will throw an exception
whenever an error is encountered. This can be useful if you want to
implement an exception handler for any error conditions rather than
checking the return value from each method call.
The Timeout property used to determine how long the control
will wait for a blocking operation to complete before returning
control to the application. The default value for the property in most
cases is 20 seconds. Note that the Internet Control Message Protocol
(ICMP) control is an exception in that the Timeout property
specifies a value in milliseconds, not seconds. The Timeout
property is only used when the Blocking property is set to True.
The Trace property is used to enable or disable the trace
logging features of the control. When the property is set to True,
the control will record all of the networking function calls that it
makes, and depending on the trace level, the data exchanged between
the client and server. To enable trace logging, you must include the
trace library cstrcv10.dll with your application. If this library
cannot be loaded, the Trace property value will be
ignored.
The TraceFile property is used to specify the name of a
file that will contain the trace logging data generated when the
Trace property is set to True. This property should be set
prior to setting the Trace property.
The TraceFlags property is used to specify the amount of
information that is recorded by the trace logging facility. The
default value of zero specifies that all of the networking function
calls should be logged, along with their arguments and return values.
The following values are used:
| Value |
Description |
| 0 |
All function calls are written to the trace file, including
information about successful calls made to the networking
library. This is the default value. |
| 1 |
Only those function calls which fail are recorded in the
trace file. Functions which are successful or only return
values which indicate a warning are not logged. |
| 2 |
Only those function calls which fail, or return values
which indicate a warning, are recorded in the trace file.
Successful function calls are not logged. |
| 4 |
All functions calls are written to the trace file, plus all
the data that is sent or received is displayed in both ASCII
and hexadecimal format. This is useful for examining the actual
byte stream that is exchanged between the application and the
server. |
The UserName property is used to specify the username used
to authenticate the client session with the server. This property is
only used by those controls which support authentication. Setting
this property to an empty string will clear the current username.
This property should be used in conjunction with the Password
property.
The Version property returns the current version of the
control as a string. This can be used by the application to check
that the correct version of the control has been registered on the
local system.
|