Communications Driver Framework
Click here to view the
Communications Driver Functions document.
Click here to go back.
This may be somewhat out of date. We welcome
additions and corrections.
Background
The AOLserver is modular/extensible with respect to its basic
communications interface. This is accomplished by defining a set of
functions that the server calls for all communications operations. So,
an AOLserver communications "driver" is just a server module that
implements these special functions. The communications driver
framework is intended to support technical AOLserver users who must
create their own communications drivers to meet their customization
requirements--no matter how bizarre. Note that there are also
architecturally similar, but functionally independent "database
drivers" that we will not discuss here.
The standard AOLserver distribution includes socket,
SSL, and file communications drivers. The socket
driver implements the basic socket-based communications. The
ssl driver is the same code as the socket driver,
recompiled with #ifdefs that include ssl-specific code. In this
document, we'll outline the basic communications driver mechanism and
show how these 3 communications drivers fit into the framework. Access
to AOLserver source code for existing drivers is assumed.
Technical Details
Initialization
A communications driver module identifies itself to the server by
calling Ns_RegisterDriver
in its module init function.
The Ns_RegisterDriver
call tells the server everything it
needs to know about the communications driver, including pointers to
all special functions via the Ns_DrvProc
structure
pointer that is passed in, and a driver-specific context for future
reference. The functions that are identified via the
Ns_DrvProc
structure are listed and explained in the Communications Driver Functions section.
Interface
For each communications driver, a subset of the special functions is
typically implemented. The following table shows which communications
driver functions are implemented by each of the 3 existing drivers.
Mandatory functions are shown in bold.
Key to table cells:
-
X=implemented
C=implemented, usage depends on configuration variables
-
Typical calling sequence from comm driver's perspective:
-
Ns_ModuleInit
-
Start - driver initialization
-
Accept - wait for connection
-
Init - connection initialization
-
Read/Write - connection I/O occurs
-
Close
-
Free
-
goto step 3
Notes on existing drivers:
-
socket
-
Notice that the socket driver, by default, does not register the
Start, Accept, or Init functions. It makes the socket, bind, and
listen calls in its ModuleInit function, and sets up a callback
which actually does the accept and queues the connection. If,
however, you configure the nssock module via ListenThread=on (this
was undocumented), the driver will register an Accept function
which will be run in a separate thread by the server.
-
SSL
-
Unlike the socket driver, the SSL driver registers an Init
function. This is where the SSL driver does all of the
per-connection SSL session setup (see ssl_init_server() is
nssock/ssl.c). After this Init function has completed for a
connection, the SSL driver simply uses symmetric encryption in the
Read/Write routines.
-
file
-
The file module is unique in that it doesn't really talk to a
stateful peer. It simply reads and writes files. Because of this
simplicity, the file module is a good place to start when studying
communications drivers.
-
Driver Developer Guidelines
If feel the urge to create a new communications driver, first review
the following: For a socket-based driver, consider modifying/extending
the current socket driver to meet your needs. If modification of the
existing socket driver doesn't seem appropriate, you may be able to
reuse much existing code by adding #ifdefs to the existing socket code
to produce a new module--analogous to the SSL approach that is
currently in place. For a non-socket-based driver, you'll need to
create a new driver, modeling your code after the existing
socket or file driver. Review the Communications Driver Functions section and
the existing drivers to determine which function points you'll need to
create.
Important Files
The code that implements the framework discussed here can be found in:
-
inc/nsdriver.h
-
nsd/drv.c
-
nsd/conn.c
-
nssock/socket.c
-
nsfile/file.c
...Back to the top