|
The SocketWrench library provides an interface to the Windows
Sockets API. It was designed to be simpler to use, and to provide
functions 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 because it does not use many of the complex
structures that the Windows Sockets API uses.
For the Secure Library 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 first step your application must take is to initialize the
library. After the library has been initialized, the application
can either take on the role of a client and establish a connection
to a remote host, or become a server and listen for incoming
connections from other clients.
InetInitialize
Initialize the library and load the Windows Sockets library for the
current process. This must be the first function call the
application makes before calling the other SocketWrench API
functions.
InetConnect
Establish a connection with a remote host. This function will
return a handle to the application which can be used to send and
receive data. When an application calls this function, it will be
acting as a client. For an asynchronous session, use the
InetAsyncConnect function.
InetListen
Begin listening for incoming client connections. This function will
return a handle which should be passed to the InetAccept function
to accept any clients which establish a connection. When an
application calls this function, it will be acting as a server. For
an asynchronous session, use the InetAsyncListen function.
InetAccept
Accept a connection from a client. This function should only be
called if the application has previously called InetListen. If
there is no client waiting to connect at the time this function is
called, it will block until a client connects or the timeout period
is reached. For an asynchronous session, use the InetAsyncAccept
function.
InetUninitialize
Unload the Windows Sockets library and release any resources that
have been allocated for the current process. This is the last
function call the application should make prior to terminating.
Input and Output
When a TCP connection is
established, data is sent and received as a stream of bytes. The
following functions can be used to send and receive data over the
socket:
InetRead
Read data from the socket and copy it to the memory buffer provided
by the caller. If the remote host closes the connection, this
function will return zero after all the data has been read. If the
function is successful, it will return the actual number of bytes
written.
InetIsReadable
This function is used to determine if there is data available to be
read from the socket.
InetWrite
Write data to the socket. If the function succeeds, the return
value is the number of bytes actually written.
InetIsWritable
This function is used to determine if data can be written to the
socket. In most cases this will return a non-zero value (True),
unless the internal socket buffers are full.
Server Interface
The library provides a collection of functions which can be used
to easily create a scalable, event-driven multi-threaded server
application. The server runs on a separate thread in the
background, automatically managing the individual client sessions
as remote hosts connect and disconnect from the server. The
application is notified of events through a callback mechanism,
where it can respond to notifications such as a client establishing
a connection with the server, or the client sending data to the
server. Functions such as InetRead and InetWrite are used to
exchange data with the clients. Because each client session is
managed in its own thread, applications can perform calculations,
access database resources and so on without worrying about
interfering with other client sessions or the application's main UI
thread.
InetServerStart
This function starts the server, creating the background thread and
listening for incoming client connections on the specified port
number. A socket handle is returned to the caller which is used to
query the status of the server and perform other functions such as
suspending and restarting the server.
InetEnumServerClients
This function enables the server application to determine the
number of active client sessions, and obtain socket handles for
each client that is connected to the server.
InetServerBroadcast
Broadcasts data to each of the clients that are connected to the
server. This can be useful when the application needs to send the
same data to each active client session, such as broadcasting a
shutdown message when the server is about to be terminated.
InetServerThrottle
This function is used to control the maximum number of clients that
may connect to the server, the maximum number of clients that can
connect from a single IP address and the rate at which the server
will accept client connections. By default, there are no limits on
the number of active client sessions and connections are accepted
immediately. This function can be useful in preventing
denial-of-service attacks where the the attacker attempts to flood
the server with connection attempts.
InetServerSuspend
This function instructs the server to temporarily suspend accepting
new client connections. Existing connections are unaffected, and
any incoming client connections are queued until the server is
resumed. It is not recommended that you leave a server in a
suspended state for an extended period of time. Once the connection
backlog queue has filled, any subsequent client connections will be
automatically rejected.
InetServerResume
This function instructs the server to resume accepting client
connections after it was suspended. Any pending client connections
are accepted after the server has resumed normal operation.
InetServerLock
This function locks the server so that only the current thread may
interact with the server and the client sessions. This will cause
all other client threads to go to sleep, waiting for the server to
be unlocked. This should only be used when the server application
needs to ensure that no other client threads are performing a
network operation. For general purpose synchronization, it is
recommended that the application create a critical section rather
than lock the entire server. If the server is left in a locked
state for an extended period of time, it will cause the server to
become non-responsive. If the application has started multiple
servers, only one server can be locked at any one time.
InetServerUnlock
This function unlocks a server that has been previously locked. The
threads which manage the client sessions will awaken and resume
normal execution.
InetServerRestart
This function will terminate all active client connections, close
the listening socket and re-create a new listening socket bound to
the same address and port number. The function will return a socket
handle for the new listening socket that should replace the
original socket that was allocated using the InetServerStart
function.
InetServerStop
This function will terminate all active client connections, close
the listening socket and terminate the background thread that
manages the server. Any incoming client connections will be
refused, and all resources allocated for the server will be
released.
Address Conversion
Internet Protocol (IP) addresses can be represented in one of
two ways, either as unsigned 32-bit integer value or as string
where each byte of the address is written as an integer value and
separated by periods. For example, the local loopback IP address
can either be specified as the string "127.0.0.1" or as the integer
value 16777343. In most cases, using the string form of the address
is easier; however, some functions require that the numeric value
be used. The following functions are provided to enable you to
convert between the two formats.
InetGetAddress
Convert an IP address string in dotted notation into a 32-bit
integer value.
InetFormatAddress
Convert a numeric IP address into a string in dotted notation,
copying the result into a buffer that you provide to the
function.
Host Tables
When resolving a host name or IP address, the library will first
search the local system's host table, a file that is used to map
host names to addresses. On Windows 95/98 and Windows Me, if the
file exists it is usually found in C:\Windows\hosts. On Windows NT
and later versions, it is found in
C:\Windows\system32\drivers\etc\hosts. Note that the file does not
have an extension.
InetGetDefaultHostFile
Return the full path of the file that contains the default host
table for the local system. This can be useful if you wish to
temporarily switch between the default host file and another host
file specific to your application.
InetGetHostFile
Return the full path of the host table that is currently being used
by the library. Initially this is the same as the default host
table for the local system.
InetSetHostFile
Specify a new host table which the library should use to resolve
host names and IP addresses. This can be used by an application to
provide its own local cache of host names and addresses in order to
speed up the process of host name resolution.
Host Name Resolution
The library 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 library will search
the local system's host table first, and then perform a nameserver
query if required.
InetGetHostAddress
Resolve a host name into an IP address, returned as a string in
dotted notation. The library first checks the system's local host
table, and if the name is not found there, it will perform a
nameserver query for the A (address) record for that host.
InetGetHostName
Resolve an IP address into a host name. The address is passed as a
string in dotted notation, and the fully qualified host name is
returned in a string buffer you provide to the function. The
library first checks the system's local host table, and if the
address is not found there, it will perform a nameserver query for
the PTR (pointer) record for that address.
Local Host Information
Several functions 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.
InetGetLocalName
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.
InetGetLocalAddress
Return the IP address of the local host. If a valid socket handle
is provided, then the IP address of the network adapter that was
used to establish the connection will be returned. This can be
particularly useful for multi-homed systems that have more than one
adapter and the application needs to know which adapter is being
used for the connection.
InetGetPhysicalAddress
Return the physical MAC address for the primary network adapter on
the local system.
InetEnumNetworkAddresses
Enumerate the network addresses that are configured for the local
host. If the system is multi-homed, then the IP address for each
network adapter will be returned.
|