CO_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 ProtocolCoReceivePacket function is required. This function processes receive indications made by underlying driver(s) that call NdisMCoIndicateReceivePacket.
Syntax
CO_RECEIVE_PACKET_HANDLER ProtocolCoReceivePacket;
UINT ProtocolCoReceivePacket(
_In_ NDIS_HANDLE ProtocolBindingContext,
_In_ NDIS_HANDLE ProtocolVcContext,
_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.ProtocolVcContext [in]
Specifies the handle to a protocol-allocated context area in which this driver maintains per-VC run-time state. The client or stand-alone call manager supplied this handle either when it called NdisCoCreateVc or from its ProtocolCoCreateVc function.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 NdisMCoIndicateReceivePacket.
Return value
ProtocolCoReceivePacket returns a driver-determined value that indicates to NDIS how many times this protocol must call NdisReturnPackets subsequently before NDIS can return the packet resources to the underlying driver that allocated these resources.
Remarks
Any protocol driver that binds itself to an underlying connection-oriented NIC driver must have a ProtocolCoReceivePacket function. Such an underlying miniport driver always indicates full-packet receives.
ProtocolCoReceivePacket must call the NDIS_GET_PACKET_STATUS macro once for each packet descriptor in the array pointed to by Packet. NDIS_GET_PACKET_STATUS obtains the OOB block Status associated with the packet descriptor.
If the underlying NIC driver, before calling NdisMCoIndicateReceivePacket, set the OOB block Status to NDIS_STATUS_SUCCESS, the NIC driver temporarily relinquished ownership of the resources associated with the packet descriptor. In this case, the protocol (or the TDI clients of a highest level protocol) can hold on to all received data, to which it is given read-only access, specified at Packet if ProtocolCoReceivePacket returns a nonzero value. For a highest level 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. A protocol driver retains ownership of the indicated packet until it calls NdisReturnPackets with Packet as many times as the reference count returned by ProtocolCoReceivePacket.
If ProtocolCoReceivePacket does not call NdisReturnPackets itself, the protocol must pass the input Packet pointer to NdisReturnPackets after ProtocolCoReceivePacket returns control. In this scenario, ProtocolCoReceivePacket 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 ProtocolCoReceivePacket function.
ProtocolCoReceivePacket 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 ProtocolCoReceivePacket function copies the data from the given packet and associated out-of-band block, if any, to protocol-allocated storage itself. When ProtocolCoReceivePacket 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.
When an underlying NIC does run short of resources, it sets a packet descriptor's associated OOB block Status to NDIS_STATUS_RESOURCES. This forces ProtocolCoReceivePacket to copy the packet data immediately rather than retaining the NIC-driver-allocated packet resources. ProtocolCoReceivePacket must return zero in such a situation.
If an underlying miniport driver supplies additional out-of-band information for receives, ProtocolCoReceivePacket can retrieve the associated out-of-band information for the given Packet with the appropriate NDIS_GET_PACKET_XXX macro(s).
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use ProtocolCoReceiveNetBufferListsinstead. 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