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.