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