The SocketWrench class 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 network programming. 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.
Initialize
Initialize an instance of the class, loading the networking library
and validating the development license. This method must be called
before any properties are changed or any other methods in this
class are called by the application.
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 networking 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.
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.
The class 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 class 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.
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.