Implementing a ProtocolReceivePacket Handler in a Protocol Driver (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.
When an underlying connectionless miniport driver indicates an array of one or more packet descriptors with NdisMIndicateReceivePacket, NDIS will usually call a bound protocol driver's ProtocolReceivePacketfunction with each packet descriptor. This allows the protocol driver (or its clients) to retain the packet descriptor and all the resources it specifies until the protocol or its clients have consumed the data and returned the packet descriptor.
The ProtocolReceivePacketfunction allows the protocol driver to:
Receive indications of full network packets from the underlying miniport driver.
Read the OOB data associated with each packet descriptor using NDIS-supplied macros.
Retain ownership of the packet descriptor and associated data or forward them to its clients. If the protocol driver copies the buffered data for its clients, it can retain ownership of the input packet descriptor, and it can retain direct read-only access to the buffered data specified by the descriptor. Otherwise, the protocol driver can forward the indicated packet descriptor to its clients after selecting the range of packet data that is of interest to the clients.
Return the packet descriptor and the associated data. If the protocol driver forwards the descriptors, the protocol driver's clients return the packet descriptor and associated data. If the protocol driver retains ownership, it can call NdisReturnPackets to return the descriptor along with other retained packet descriptors. The protocol driver calls NdisReturnPackets after the driver has consumed all of the indicated data.
Even when a protocol driver provides a ProtocolReceivePackethandler, a miniport driver's call to NdisMIndicateReceivePacketcan result in a call to the protocol driver's ProtocolReceivefunction. Since a miniport driver temporarily relinquishes ownership of driver-allocated resources when it calls NdisMIndicateReceivePacket, the miniport driver depends on the consumers of those packets to return the packets in a timely manner. Otherwise, the miniport driver can run short of receive resources, such as receive buffer space in the NIC. When a miniport driver runs short of receive resources, the driver sets NDIS_STATUS_RESOURCES in the OOB block associated with a packet descriptor. Indicating a packet with NDIS_STATUS_RESOURCES causes NDIS to call the overlying driver's ProtocolReceivefunction with the packet and with any subsequent packets in the array. This forces the protocol driver to copy the packet data immediately, rather than retaining the receive resources allocated by the miniport driver.
If the protocol driver requires the OOB data associated with a packet descriptor but NDIS called ProtocolReceive, the protocol driver must call NdisGetReceivedPacketand NDIS_GET_ORIGINAL_PACKETto copy the media-specific information into a protocol-supplied buffer. This also copies the TimeSentand TimeReceivedvalues, if the underlying miniport driver provides these time stamps. For additional information about OOB data, see Accessing OOB Information from a Connectionless Protocol Driver.