|
The SocketWrench control provides a simplified interface to the
Windows Sockets API. It was designed to be easier to use, and to
provide properties and methods which eliminate much of the
redundant coding common to Windows Sockets programming. Developers
who are working in languages other than C or C++ will find
SocketWrench to be particularly useful. For the Secure Visual
Edition, SocketWrench also provides an interface for creating
client and server applications which use the SSL and TLS security
protocols without any dependencies on third-party security
libraries or the need for the developer to understand how to use
Microsoft's CryptoAPI.
The following properties, methods and events are available for
use by your application:
Initialize
Initialize the control and load the Windows Sockets library for the
current process. This method is normally not used if the control is
placed on a form in languages such as Visual Basic. However, if the
control is being created dynamically using a function similar to
CreateObject, then the application must call this method to
initialize the component before setting any properties or calling
any other methods in the control.
Connect
Connect to the remote host, using either a host name or IP address.
When an application calls this method, it will be acting as a
client. This method creates the socket and must be called before
your application attempts to exchange data with a server. For an
asynchronous session, set the Blocking property to False.
Listen
Begin listening for incoming client connections. When an
application calls this method, it will be acting as a server. Once
the Listen method returns, the socket is created and that socket
handle is used by the Accept method accept an incoming client
connection. For an asynchronous session, set the Blocking property
to False.
Accept
Accept a connection from a client. This method should only be
called if the application has previously called the Listen method.
If there is no client waiting to connect at the time this method is
called, it will block until a client connects or the timeout period
is reached.
Uninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
method call that the application should make prior to terminating.
This is only necessary if the application has previously called the
Initialize method.
Input and Output
When a TCP connection is
established, data is sent and received as a stream of bytes. The
following methods can be used to send and receive data over the
socket:
Read
A low-level method used to read data from the socket and copy it to
the string buffer or byte array provided by the caller. If the
remote host closes the connection, this method will return zero
after all the data has been read. If the method is successful, it
will return the actual number of bytes read. This method should
always be used when reading binary data from the remote host into a
byte array.
ReadLine
Read a line of text from the socket, up to an end-of-line character
sequence or when the remote host closes the connection. This method
is useful when the client and server are exchanging textual data,
as is common with most command/response application protocols.
ReadStream
A high-level method used to read a stream of bytes and copy it to a
string buffer or byte array provided by the caller. This method can
be used to read an arbitrarily large amount of data in a single
call.
Write
A low-level method used to write data to the socket. If the method
succeeds, the return value is the number of bytes actually written.
This method should always be used when sending binary data to the
remote host.
WriteLine
Write a line of text to the socket, terminating it with an
end-of-line character sequence. This method is useful when the
client and server are exchanging textual data, as is common with
most command/response application protocols.
WriteStream
A high-level method used to write a stream of bytes to the socket.
This method can be used to write an arbitrarily large amount of
data to the socket in a single call.
IsReadable
This property is used to determine if there is data available to be
read from the socket. If the property returns a value of True, the
Read method will return without causing the application to block.
If the property returns False, there is no data available to read
from the socket.
IsWritable
This property is used to determine if data can be written to the
socket. In most cases this will return True, unless the internal
socket buffers are full.
Host Name Resolution
The control can be used to resolve host names into IP addresses,
as well as perform reverse DNS lookups converting IP addresses into
the host names that are assigned to them. The control will search
the local system's host table first, and then perform a nameserver
query if required.
HostAddress
This property can be used to set the IP address for a remote system
that you wish to communicate with. If the address is valid and
matches an entry in the host table, the HostName property will be
changed to match the address.
HostName
This property should be set to the name of the remote system that
you wish to communicate with. If the name is found in the host
table, the HostAddress property is updated to reflect the IP
address of the host. Note that it is legal to assign an IP address
to this property, but it is not legal to assign a host name to the
HostAddress property.
Local Host Information
Several methods are provided
to return information about the local host, including its fully
qualified domain name, local IP address and the physical MAC
address of the primary network adapter.
LocalName
Return the fully qualified domain name of the local host, if it has
been configured. If the system has not been configured with a
domain name, then the machine name is returned instead.
LocalAddress
Return the IP address of the local host. If a connection has been
established, then the IP address of the network adapter that was
used to establish the connection will be returned. This can be
particularly useful for multihomed systems that have more than one
adapter and the application needs to know which adapter is being
used for the connection.
ExternalAddress
Return the IP address assigned to the router that connects the
local host to the Internet. This is typically used by an
application executing on a system in a local network that uses a
router which performs Network Address Translation (NAT).
PhysicalAddress
Return the physical MAC address for the primary network adapter on
the local system.
AdapterAddress
This property array returns the IP addresses that are associated
with the local network or remote dial-up network adapters
configured on the system. The AdapterCount property can be used to
determine the number of adapters that are available.
|