|
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. SocketWrench also
supports creating client and server applications which use the
TLS security protocol without any dependencies on third-party
security libraries.
The following properties, methods and events are available for use
by your application:
Initialize
Initialize the control and validate the runtime license key 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 server, 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 server
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 server into a byte array.
ReadLine
Read a line of text from the socket, up to an end-of-line character
sequence or when the server 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
server.
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 server
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 server 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.
|