Receiving Data in a Protocol Driver

Article
06/30/2006

The following list shows how underlying NIC drivers can indicate packets in two ways:

A NIC driver calls NdisMIndicateReceivePacket, passing a pointer to an array of packet descriptor pointers to one or more full packets and relinquishing ownership of the resources for these packets to the overlying drivers. This process can consume the data and return the packet resources at a later time.
A NIC driver calls a filter-specific NdisMXXXIndicateReceive function, passing a pointer to a lookahead buffer, the size of the lookahead buffer, and the total size of the received net packet.

Every protocol driver must have at least one of two possible receive handlers. The following table shows the possible receive handlers for a protocol driver.

Handler	Description
ProtocolReceive	A required function that is called with a pointer to a lookahead buffer. After ProtocolReceive examines the lookahead data and determines that the packet is intended for one or more of its clients, it 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 to obtain the remaining received data, which the underlying driver copies into the protocol-supplied buffer.
ProtocolReceivePacket	An optional function that receives a pointer to packet descriptor specifying a buffered full network packet. ProtocolReceivePacket also examines the packet data and determines whether the packet is intended for one or more of its clients. If so, the protocol can give its clients ownership of the indicated packet resources, including direct read-only access to the buffered net packet data, by returning a nonzero value from ProtocolReceivePacket. The protocol driver's clients must subsequently 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 client call to the protocol driver returns the packet descriptor the required number of times, it relinquishes ownership of the returned packet resources to the NIC driver. If a protocol driver returns 0 from ProtocolReceivePacket, it relinquishes ownership of the packet resources when ProtocolReceivePacket returns.

ProtocolReceive

A required function that is called with a pointer to a lookahead buffer. After ProtocolReceive examines the lookahead data and determines that the packet is intended for one or more of its clients, it 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 to obtain the remaining received data, which the underlying driver copies into the protocol-supplied buffer.

ProtocolReceivePacket

An optional function that receives a pointer to packet descriptor specifying a buffered full network packet.
ProtocolReceivePacket also examines the packet data and determines whether the packet is intended for one or more of its clients. If so, the protocol can give its clients ownership of the indicated packet resources, including direct read-only access to the buffered net packet data, by returning a nonzero value from ProtocolReceivePacket. The protocol driver's clients must subsequently 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 client call to the protocol driver returns the packet descriptor the required number of times, it relinquishes ownership of the returned packet resources to the NIC driver.
If a protocol driver returns 0 from ProtocolReceivePacket, it relinquishes ownership of the packet resources when ProtocolReceivePacket returns.

Share via

Receiving Data in a Protocol Driver

See Also

Additional resources