RECEIVE_PACKET_HANDLER callback function
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.
The ProtocolReceivePacket function is an optional driver function. ProtocolReceivePacket processes receive indications made by underlying connectionless NIC driver(s) that call NdisMIndicateReceivePacket either with packet arrays because the underlying driver supports multipacket receive indications or with individual packets that have associated out-of-band information. A call to ProtocolReceivePacket can also occur as a result of loopback.
Protocols that bind themselves exclusively to underlying connection-oriented miniport drivers must have a fully functional ProtocolCoReceivePacket function, rather than a ProtocolReceivePacket function.
Syntax
RECEIVE_PACKET_HANDLER ProtocolReceivePacket;
INT ProtocolReceivePacket(
_In_ NDIS_HANDLE ProtocolBindingContext,
_In_ PNDIS_PACKET Packet
)
{ ... }
Parameters
ProtocolBindingContext [in]
Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called NdisOpenAdapter.Packet [in]
Specifies a pointer to a packet descriptor for the received net packet. NDIS extracted this pointer from an array of packet descriptor pointers that an underlying driver passed to NdisMIndicateReceivePacket.
Return value
ProtocolReceivePacket returns a driver-determined value that tells NDIS how many times the protocol will subsequently call NdisReturnPackets with the given packet, or zero if the protocol is done with or not interested in this packet.
Remarks
Any protocol driver that might bind itself to an underlying connectionless NIC driver that supports multipacket receive indications should have a ProtocolReceivePacket function. Such an underlying driver always indicates full-packet receives.
A protocol can achieve better performance if it has a ProtocolReceivePacket function. Such a protocol (or the TDI clients of a highest level Windows 2000 or later protocol) can hold on to all received data, to which it is given read-only access, specified at Packet if ProtocolReceivePacket returns a nonzero value. For a highest level Windows 2000 or later protocol driver, the return value for such an input Packet descriptor pointer can be a reference count of clients the protocol has notified about the received net packet by forwarding the input Packet descriptor. For an intermediate NDIS driver, the return value can be a count of higher level protocols to which it has made a corresponding indication or one if the driver tracks the number of higher level protocols to which it forwards the processed indication. For a highest level Windows 2000 or later protocol that forwards the input Packet descriptor pointer to some number of interested clients, each client retains read-only access to the indicated data until the client calls TdiReturnChainedReceives. An intermediate NDIS driver retains ownership of the indicated packet until it calls NdisReturnPackets with Packet as many times as the reference count returned by ProtocolReceivePacket.
If ProtocolReceivePacket does not call NdisReturnPackets itself, the protocol must pass the input Packet pointer to NdisReturnPackets after ProtocolReceivePacket returns control. In this scenario, ProtocolReceivePacket should save the input Packet pointer in the ProtocolBindingContext area when it will return a nonzero value.
The NDIS library maintains the reference count for such an indicated packet, and the protocol retains ownership of the packet until it has called NdisReturnPackets with that packet as many times as the value returned by its ProtocolReceivePacket function.
ProtocolReceivePacket returns zero to relinquish ownership of the given Packet if the protocol has no current clients or bound higher level protocols interested in the indicated network packet or if the ProtocolReceivePacket function copies the data from the given packet and associated out-of-band block, if any, to protocol-allocated storage itself. When ProtocolReceivePacket returns zero, NDIS either calls another bound protocol with the receive indication or returns the given packet descriptor at Packet to the miniport driver that made the indication.
Any protocol that binds itself to an underlying connectionless NIC driver that supplies out-of-band information for receives must have a ProtocolReceivePacket function to interpret the miniport driver-supplied out-of-band information when processing receive indications. Such a protocol can retrieve the associated out-of-band information for the given Packet with the appropriate NDIS_GET_PACKET_XXX macro(s).
If an incoming packet descriptor has NDIS_STATUS_RESOURCES set for the Status in the associated OOB block, the protocol must not retain the packet descriptor and associated miniport driver-allocated resources. Instead, the ProtocolReceivePacket should copy the received data into protocol-allocated storage and return zero to NDIS as quickly as possible. Such a Status in the OOB block for a miniport driver-allocated packet descriptor indicates that the miniport driver is running low on receive resources.
On a multiprocessor system, this function may execute concurrently on more than one processor. Apply protection (for example, use spin locks) to critical data structures accessed by this function.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolReceiveNetBufferListsinstead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also
NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO