Asynchronous I/O and Completion Functions (NDIS 5.1)
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
Latency is inherent in some network operations. Because of this, many of the upper-edge functions provided by a NIC driver and the lower-edge functions of a protocol driver are designed to support asynchronous operation. Rather than wasting CPU cycles waiting in a loop for some time-consuming task to finish or a hardware event to signal, network drivers rely on the ability to handle most operations asynchronously.
Asynchronous network I/O is supported by using a completion function. The following example illustrates using a completion function for a network send operation, but this same mechanism exists for many other operations performed by a protocol or NIC driver.
When a protocol driver calls NDIS to send a packet, resulting in a call to the NIC driver's MiniportSendfunction, the NIC driver can try to complete this request immediately and return an appropriate status value as a result. For synchronous operation, the possible responses are NDIS_STATUS_SUCCESS for successful completion of the send, NDIS_STATUS_RESOURCES, and NDIS_STATUS_FAILURE indicating a failure of some kind.
But a send operation can take some time to complete while the NIC driver (or NDIS) queues the packet and waits for the NIC to indicate the result of the send operation. The NIC driver MiniportSendfunction can handle this operation asynchronously by returning a status value of NDIS_STATUS_PENDING. When the NIC driver completes the send operation, it calls the completion function, NdisMSendComplete, passing a pointer to the packet descriptor that was sent. This information is passed to the protocol driver, signaling completion.
Most driver operations that can require an extended time to complete support asynchronous operation with a similar completion function. Such functions have names of the form NdisMXxxComplete.
Completion functions are also provided for:
setting and querying configuration.
resetting hardware.
indicating status.
indicating received data.
transferring received data.