## 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

Function: |  | Existing Driver Name:
socket | SSL | file
Name | X | X |
Start |  |  | X
Accept | C | C | X
Stop | X | X | X
Init |  | X |
Read | X | X | X
Write | X | X | X
Close | X | X | X
Free | X | X | X
Peer | X | X | X
Location | X | X | X
Host | X | X |
Port | X | X |
SendFd | C | C |
SendFile |  |  |
Detach | C |  |

#### Typical calling sequence from comm driver's perspective:

1. Ns_ModuleInit
2. Start - driver initialization
3. Accept - wait for connection
4. Init - connection initialization
5. Read/Write - connection I/O occurs
6. Close
7. Free
8. 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