NdisMTrIndicateReceive function

Article
06/19/2017

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.

NdisMTrIndicateReceive notifies NDIS that a Token Ring packet (or some initial lookahead portion of the packet) has arrived so NDIS can forward the packet to bound protocols.

Syntax

VOID NdisMTrIndicateReceive(
  _In_ NDIS_HANDLE MiniportAdapterHandle,
  _In_ NDIS_HANDLE MiniportReceiveContext,
  _In_ PVOID       HeaderBuffer,
  _In_ UINT        HeaderBufferSize,
  _In_ PVOID       LookaheadBuffer,
  _In_ UINT        LookaheadBufferSize,
  _In_ UINT        PacketSize
);

Parameters

MiniportAdapterHandle [in]
Specifies the handle originally input to MiniportInitialize.
MiniportReceiveContext [in]
Specifies a context handle supplied by the caller. NDIS returns this handle as an input parameter to the MiniportTransferData function if it is called. The miniport driver can use the context area designated by this handle to determine which packet, on which NIC, is being received.
HeaderBuffer [in]
Specifies the base virtual address of the buffered packet header.
HeaderBufferSize [in]
Specifies the size in bytes of the packet header.
LookaheadBuffer [in]
Specifies the base virtual address of a buffer containing the initial LookaheadBufferSize bytes of the data in the packet.
LookaheadBufferSize [in]
Specifies the size in bytes of the lookahead buffer. This value must be at least as large as the lookahead size set when MiniportSetInformation was called with OID_GEN_CURRENT_LOOKAHEAD, or as large as the packet, whichever is smaller. When the packet is smaller than the lookahead size, the lookahead buffer contains the entire frame.

A miniport driver can (and should) set LookaheadBufferSize to something larger than the minimum required if sufficient received data is available on its NIC.
PacketSize [in]
Specifies the size in bytes of the received packet data. This value does not include the HeaderBufferSize.

When PacketSize is larger than LookaheadBufferSize, a protocol driver call to NdisTransferData causes a subsequent call to the MiniportTransferData function, which transfers the remaining data in the packet.

Return value

None

Remarks

A miniport driver calls NdisMTrIndicateReceive if it designates its NIC as of type NdisMedium802_5 in response to the OID_GEN_MEDIA_IN_USE query, unless the miniport driver indicates receives with NdisMIndicateReceivePacket.

When a miniport driver calls NdisMTrIndicateReceive, NDIS passes a pointer to the header of the packet and a pointer to some or all of the data in the packet to the ProtocolReceive function(s) of bound protocol driver(s). Each protocol that receives the indication can do the following:

Inspect the header and data in the packet to decide whether the indication is of interest to the protocol's client(s).
If it is, copy as much of the header or data as is visible into protocol-allocated memory with NdisMoveMemory.
Get the remaining data, if any, for the indication by allocating a packet descriptor with sufficient chained buffer descriptors and calling NdisTransferData. The call to NdisTransferData causes the NIC driver's MiniportTransferData function to copy the data into the protocol-supplied packet.

For any protocol driver that receives an indication through NdisMTrIndicateReceive, the HeaderBuffer and LookaheadBuffer addresses are valid only during the current call to its ProtocolReceive function, and these buffers are read-only. A protocol driver cannot retain a pointer to the indicated packet with these associated buffers nor can it retain any pointers to these buffers for later use. Any data that a protocol driver needs from such a packet must be copied and saved during the receive indication.

The data in the header is the same as that received on the NIC. A miniport driver need not remove any headers or trailers from the data its NIC receives.

The transmitting driver adds padding to any packet that is too short for the requirements of the medium. The receiving miniport driver can include such padding in the data and length it subsequently indicates. Each bound protocol is responsible for detecting any such padding and ignoring it.

A miniport driver must release any spin lock that it is holding before calling NdisMTrIndicateReceive.

Serialized callers of NdisMTrIndicateReceive must run at IRQL = DISPATCH_LEVEL. Deserialized callers of NdisMTrIndicateReceive must run at IRQL <= DISPATCH_LEVEL.

Requirements

Target platform	Desktop
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
IRQL	See Remarks section

Partager via