Communications Driver Functions

## Communications Driver Functions Click here to view the Communications Driver Framework document.
Click here to go back.

This may be somewhat out of date. We welcome additions and corrections.

All communications driver functions that can be specified via the `Ns_DrvProc` structure are listed below. Note that the actual enumeration type for each function name (`Ns_DrvId`) can be derived by prepending `Ns_DrvId` to each name, e.g. `DrvIdName`, `DrvIdStart`, etc.

These functions are generic, and some may not make sense for certain drivers, so it's typically a subset that needs to be implemented for a particular driver. If you examine how the Ns_DrvProc structure is initialized in existing drivers, you'll notice a NULL-terminated array of ID/functionPointer pairs, where each pair identifies an implemented function. Mandatory functions are shown in bold.

Name | Description | PreConditions | PostConditions
Name | Returns a (char *) that identifies the driver, e.g. "nssock", "nsssl", "nsfile". |  |
Start | Called at driver initialization time (not to be confused with Init which is called when a connection is initialized). | ModuleInit has already executed. | All driver initialization is complete.
Accept | Called when a driver can begin accepting connections; this may block. | Start function has completed (if defined). | Driver has established a connection with peer.
Stop | Called at driver shutdown time. |  | Driver has terminated connections with peer.
Init | Called when a connection is to be initialized. | A connection has been established via Accept | Per connection initialization is complete
Read | Called to read data from a peer. | Server is ready to receive data. | Driver has received data from peer.
Write | Called to write data to a peer. | Server has data to transmit. | Driver has transmitted data to peer.
Close | Called to close a connection. | A connection has been established; connection info is contained in the context. | Driver has closed connection with peer.
Free | Called to close a connection and free the context. | A connection has been established; connection info is contained in the context. | Driver has closed connection and freed resources associated with the context.
Peer | Returns the (char *) identifier of the peer (IP address in the case of socket-based drivers) |  |
Location | Returns the (char *) complete location that identifies the driver, e.g. https://www.docs-R-us.com:81 |  |
Host | Returns the (char *) hostname that identifies the driver |  |
Port | Returns the (int) port number associated with the driver |  |
SendFd | Called to send an open file | File descriptor is open/valid. | Driver has transmitted entire file.
SendFile | Called to send a named file (currently unused by all provided drivers) | Filename is valid/readable. | Driver has transmitted entire file.
Detach | Called to support socket KEEPALIVE function. In socket driver case: creates a new connection context that is marked as requeued. Returns a (void *) pointer to a new connection context, or NULL if existing context is NULL. | Connection info is contained in the context, or the context is NULL. | Driver has created a new connection context to represent the detached state.

Preconditions and postconditions reflect the contract that a driver has with the server. Preconditions represent the driver developer's assumptions before the function is called. Postconditions represent the server's assumptions after the function has completed.

...Back to the top