ProtocolReceivePacket (Compact 2013)

3/26/2014

ProtocolReceivePacket is an optional driver function that processes receive indications made by underlying connectionless NIC driver(s) that call either NdisMIndicateReceivePacket 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.

Syntax

INT ProtocolReceivePacket(
  NDIS_HANDLE ProtocolBindingContext,
  PNDIS_PACKET Packet 
);

Parameters

• ProtocolBindingContext
  [in] Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding runtime 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. A protocol can achieve better performance if it has a ProtocolReceivePacket function. Such a 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 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. 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 that made the indication.

When processing receive indications, any protocol that binds itself to an underlying connectionless NIC driver that is supplying out-of-band information for receives must have a ProtocolReceivePacket function. When this process is completed, the ProtocolReceivePacket function interprets the out-of-band information supplied by the miniport. 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-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-allocated packet descriptor indicates that the miniport is running low on receive resources.

By default, ProtocolReceivePacket runs at IRQL DISPATCH_LEVEL in an arbitrary thread context.

Requirements

See Also

Reference

NDIS 5.x Legacy Functions
NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO
NDIS_GET_PACKET_TIME_SENT
NDIS_PACKET
NDIS_PACKET_OOB_DATA
NdisAllocatePacket
NdisMIndicateReceivePacket
NdisOpenAdapter
NdisReturnPackets
ProtocolReceive