Receiving Data in a Connectionless 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.
Underlying connectionless miniport drivers can indicate packets in two ways:
A miniport driver calls NdisMIndicateReceivePacket. In this call, the miniport driver passes a pointer to an array of packet descriptor pointers to one or more full packets. The miniport driver relinquishes ownership of the resources for these packets to the overlying drivers. The overlying drivers can consume the data and return the packet resources to the miniport driver at a later time.
A miniport driver calls a filter-specific NdisMXxxIndicateReceive function. In such a call, the miniport driver passes a pointer to a lookahead buffer, the size of the lookahead buffer, and the total size of the received net packet.
Every connectionless protocol driver must have at least one of the two possible receive handlers and can have both of the following:
ProtocolReceive is a required function that is called with a pointer to a lookahead buffer.
ProtocolReceive examines the lookahead data to determine if the packet is intended for its clients. If so, the protocol driver must copy the lookahead data into a protocol-allocated buffer, possibly to be chained to a protocol-allocated packet descriptor.
If the size of the lookahead buffer is less than the total size of the received packet, ProtocolReceive must call NdisTransferData with the protocol-allocated packet descriptor. The underlying driver copies the rest of the received data into the protocol-supplied buffer.
ProtocolReceivePacket is an optional function that receives a pointer to a packet descriptor specifying a buffered full network packet.
ProtocolReceivePacket examines the packet data and determines whether the packet is intended for its clients. If so, the protocol driver can return a nonzero value (a count of clients to which the protocol driver forwarded the receive indication) from ProtocolReceivePacket to give its clients ownership of the indicated packet resources, including direct read-only access to the buffered net packet data. The protocol driver's clients must subsequently call NdisReturnPackets to return the packet descriptor and all the resources it specifies to the underlying driver. Each client must return the packet descriptor until all clients' calls total the nonzero value returned from ProtocolReceivePacket for that receive indication.
When the protocol driver's clients return the packet descriptor the required number of times, they relinquish ownership of the returned packet resources to the underlying miniport driver that originally indicated the receive.
If a protocol driver returns zero from ProtocolReceivePacket, it relinquishes ownership of the packet resources when ProtocolReceivePacket returns. Relinquishing of such a received packet immediately could occur, for instance, if the client for the packet has closed the connection or in some manner became unavailable; or if the protocol driver copies the indicated data into buffers of its own and processes the data internally before indicating the data up to its clients.
The following topics contain additional information about receiving data in a connectionless protocol driver:
Implementing a ProtocolReceivePacket Handler in a Protocol Driver
Implementing a ProtocolReceive Handler in a Protocol Driver
Accessing OOB Information from a Connectionless Protocol Driver