RECEIVE_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 ProtocolReceive function is a required driver function in NDIS protocols that bind themselves to connectionless NIC drivers. ProtocolReceive determines whether a received network packet is of interest to the protocol's client(s) and, if so, copies the indicated data and, possibly, calls NdisTransferData to retrieve the rest of the indicated packet.
Syntax
RECEIVE_HANDLER ProtocolReceive;
NDIS_STATUS ProtocolReceive(
_In_ NDIS_HANDLE ProtocolBindingContext,
_In_ NDIS_HANDLE MacReceiveContext,
_In_ PVOID HeaderBuffer,
_In_ UINT HeaderBufferSize,
_In_ PVOID LookAheadBuffer,
_In_ UINT LookaheadBufferSize,
_In_ UINT PacketSize
)
{ ... }
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.MacReceiveContext [in]
Specifies a context handle that the underlying NIC driver associates with the packet received from the network. This handle is opaque to the protocol, reserved for use by the underlying driver that made the indication, and a required parameter to NdisTransferData.HeaderBuffer [in]
Pointer to the base virtual address of a range containing the buffered packet header. The address is valid only within the current call to ProtocolReceive.HeaderBufferSize [in]
Specifies the number of bytes in the packet header.LookAheadBuffer [in]
Pointer to the base virtual address of a range that contains LookaheadBufferSize bytes of buffered network packet data. This address is valid only within the current call to ProtocolReceive.LookaheadBufferSize [in]
Specifies the number of bytes of network packet data in the lookahead buffer.The indicating driver ensures this number is at least as large as the size it returned for the protocol's preceding call to NdisRequest with OID_GEN_CURRENT_LOOKAHEAD or the size of the packet, whichever is less.
If PacketSize is less than or equal to the given LookaheadBufferSize, the lookahead buffer contains the entire packet.
PacketSize [in]
Specifies the size, in bytes, of the network packet data. The length of the packet does not include the length of the header.ProtocolReceive determines whether the protocol must call NdisTransferData by comparing this parameter to the given LookaheadBufferSize.
Return value
ProtocolReceive can return either of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_NOT_ACCEPTED | The protocol has no use for the indicated packet, that is, it has no current clients interested in the indicated network data. Returning this status quickly for rejected packets yields higher performance for the protocol and the highest possible network I/O throughput for the system as a whole. |
| NDIS_STATUS_SUCCESS | ProtocolReceive has processed the header information and accepted the packet, that is, it has copied the indicated network data from the header and lookahead buffers and, possibly, called NdisTransferData to retrieve the remaining data if less than a full network packet was indicated. |
Remarks
NDIS provides equal packet access for any number of protocol drivers bound above an underlying connectionless miniport driver. NDIS can use the status that ProtocolReceive returns to optimize the order in which bound protocols receive indications for subsequent packets.
When a miniport driver calls a filter-specific NdisM..IndicateReceive function, NDIS calls the ProtocolReceive functions of bound protocols. A call to an NdisM..IndicateReceive function indicates that a network packet, or some initial lookahead portion of it, is available for inspection by bound protocols. Each ProtocolReceive function, in turn, inspects the packet header and data, optionally copies as much of the header and/or data as is made available, and calls NdisTransferData to instruct the NIC driver to copy any remaining data into a protocol-supplied buffer chained to a protocol-allocated packet descriptor if the protocol accepts the packet. ProtocolReceive can call NdisTransferData only once per receive indication.
Before a serialized miniport driver calls NdisMIndicateReceivePacket with a packet array, it can set the Status member of an out-of-band block associated with a packet descriptor in the array to NDIS_STATUS_RESOURCES. This also causes NDIS to call the ProtocolReceive functions of bound protocols with the network packet header and data specified by that packet descriptor and, separately, with the received network packets specified in all subsequent descriptors in the indicated packet array. Each ProtocolReceive function, in turn, inspects the given network packet header and data and each optionally copies the indicated network packet data.
If the underlying miniport driver supplies out-of-band information with the receives it indicates, ProtocolReceive can call NdisGetReceivedPacket or NDIS_GET_ORIGINAL_PACKET to retrieve the out-of-band information for each such packet. Because such an underlying miniport driver always indicates full-packet receives, ProtocolReceive will never call NdisTransferData for a packet indicated with NdisMIndicateReceivePacket.
NDIS calls ProtocolReceive functions sequentially as calls to NdisM..IndicateReceive or NdisMIndicateReceivePacket occur, but it can indicate a packet to bound protocols using separate calls. However, every protocol must be able to handle out-of-order received packets since neither NDIS nor the underlying miniport driver has any control over the network over which packets are transmitted.
A driver writer should minimize the amount of time spent in the ProtocolReceive function so that the protocol does not lose additional incoming packets, particularly from underlying drivers that call the filter-specific NdisM..IndicateReceive functions. ProtocolReceive must either reject an incoming packet or recognize the packet as of interest to its client(s) quickly. If it accepts the packet, ProtocolReceive must find a place to put packet data and copy the data quickly. Shortly after ProtocolReceive returns, when time constraints are not so severe, any underlying miniport driver that made one or more indications with NdisM..IndicateReceive will call the corresponding NdisM..IndicateReceiveComplete. The protocol driver's ProtocolReceiveComplete function then performs any necessary postprocessing for the original indication(s).
The underlying driver does not remove any headers or trailers from the packet data received on its NIC, nor does it remove any received padding. In other words, a packet can include padding in the data and length indicated to protocols. ProtocolReceive is responsible for detecting and ignoring such padding.
The buffers at HeaderBuffer and LookaheadBuffer passed to ProtocolReceive are read-only and valid only until ProtocolReceive returns control. ProtocolReceive must copy all the indicated data that the driver needs into protocol-allocated storage. Whether a Windows 2000 or later protocol can copy the indication directly depends on the NDIS_MAC_OPTION_COPY_LOOKAHEAD_DATA flag returned for the OID_GEN_MAC_OPTIONS query. If this flag was set, ProtocolReceive can use NdisMoveMemory to copy the indicated data to its own storage; otherwise, it should use TdiCopyLookaheadData. However, a Windows 2000 or later protocol can call TdiCopyLookaheadData even if the underlying driver set the NDIS_MAC_OPTION_COPY_LOOKAHEAD_DATA flag.
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
NdisGetFirstBufferFromPacketSafe