|
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. SocketWrench also supports creating client and server
applications which use TLS security protocol without any dependencies
on third-party security libraries.
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
server, 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 server. 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 server 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 multithreaded server
application. The server runs on a separate thread in the background,
automatically managing the individual client sessions as servers
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 multihomed systems that have more than one adapter and
the application needs to know which adapter is being used for the
connection.
InetGetAdapterAddress
Return the IP or MAC address assigned to a network adapter on the
local system.
InetEnumNetworkAddresses
Enumerate the network addresses that are configured for the local
host. If the system is multihomed, then the IP address for each
network adapter will be returned.
|