Important: |
---|
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
ProtocolReceiveis a required driver function in NDIS protocols that bind themselves to connectionless network adapter drivers. ProtocolReceivedetermines whether a received network packet is of interest to the protocol's client(s) and, if so, copies the indicated data and, possibly, calls NdisTransferDatato retrieve the rest of the indicated packet.
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
The indicating driver ensures this number is at least as large as the size it returned for the protocol's preceding call to NdisRequestwith OID_GEN_CURRENT_LOOKAHEAD or the size of the packet, whichever is less.
If PacketSizeis less than or equal to the given LookaheadBufferSize, the lookahead buffer contains the entire packet. If the underlying driver made the indication with NdisMIndicateReceivePacket, the lookahead buffer always contains a full network packet.
ProtocolReceivedetermines whether the protocol must call NdisTransferDataby comparing this parameter to the given LookaheadBufferSize.
Return Values
ProtocolReceivecan return either of the following:
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.
Comments
NDIS provides equal packet access for any number of protocol drivers bound above an underlying connectionless network adapter miniport. NDIS can use the status that ProtocolReceivereturns to optimize the order in which bound protocols receive indications for subsequent packets.
When a miniport calls a filter-specific NdisM..IndicateReceivefunction, NDIS calls the ProtocolReceivefunctions of bound protocols. A call to an NdisM..IndicateReceivefunction indicates that a network packet, or some initial lookahead portion of it, is available for inspection by bound protocols. Each ProtocolReceivefunction, in turn, inspects the packet header and data, optionally copies as much of the header and/or data as is made available, and calls NdisTransferDatato instruct the network adapter driver to copy any remaining data into a protocol-supplied buffer chained to a protocol-allocated packet descriptor if the protocol accepts the packet. ProtocolReceivecan call NdisTransferDataonly once per receive indication.
Before a serialized miniport calls NdisMIndicateReceivePacketwith a packet array, it can set the Statusmember 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 ProtocolReceivefunctions 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 ProtocolReceivefunction, in turn, inspects the given network packet header and data and each optionally copies the indicated network packet data.
If the underlying miniport supplies out-of-band information with the receives it indicates, ProtocolReceivecan call NdisGetReceivedPacketNDIS_GET_ORIGINAL_PACKET to retrieve the out-of-band information for each such packet. Because such an underlying miniport always indicates full-packet receives, ProtocolReceivewill never call NdisTransferDatafor a packet indicated with NdisMIndicateReceivePacket.
NDIS calls ProtocolReceivefunctions sequentially as calls to NdisM..IndicateReceiveor NdisTransferDataoccur, 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 network adapter miniport has any control over the network over which packets are transmitted.
A driver writer should minimize the amount of time spent in the ProtocolReceivefunction so that the protocol does not lose additional incoming packets, particularly from underlying drivers that call the filter-specific NdisM..IndicateReceivefunctions. ProtocolReceivemust either reject an incoming packet or recognize the packet as of interest to its client(s) quickly. If it accepts the packet, ProtocolReceivemust find a place to put packet data and copy the data quickly. Shortly after ProtocolReceivereturns, when time constraints are not so severe, any underlying miniport that made one or more indications with NdisM..IndicateReceivewill call the corresponding NdisM..IndicateReceiveComplete. The protocol driver's ProtocolReceiveCompletefunction 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 network adapter, nor does it remove any received padding. In other words, a packet can include padding in the data and length indicated to protocols. ProtocolReceiveis responsible for detecting and ignoring such padding.
Requirements
Runs on | Versions | Defined in | Include | Link to |
---|---|---|---|---|
Windows CE OS | 2.0 and later | Ndis.h | Ndislib.lib |
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
See Also
NdisMIndicateReceivePacket, NdisOpenAdapter, NdisRequest, NdisTransferData, ProtocolReceiveComplete