|
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 |
| Connected
|
Determine if the
control is connected to a remote host |
| HostAddress
|
Gets and sets the
IP address of the remote host |
| HostName
|
Gets and sets the
name of the remote host |
| IsBlocked
|
Return if the
control is blocked performing an operation |
| IsReadable
|
Return if data can
be read from the remote host without blocking |
| IsWritable
|
Return if data can
be sent to the remote host 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 remote system, 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 Connected property returns True if a connection has
been made with a remote 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 HostAddress property is used to specify the IP
address of a remote host 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
remote host 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 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 remote host 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 remote host. 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. It is required that you have a SocketTools Secure Visual
Edition license in order to establish a secure connection.
Attempting to set this property to True will cause the control to
throw an exception if SocketTools has been installed with a
Standard Edition license.
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. If the property is set to a
value of zero, then the control will wait indefinitely for a
blocking operation to complete, except when establishing a
connection. The default value for the property in most cases is 60
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 cstrace6.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 remote host. |
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.
|