This function notifies NDIS that an array of received packets is available to be forwarded to the appropriate bound protocol driver(s).

VOID
NdisMIndicateReceivePacket(
IN NDIS_HANDLE
MiniportAdapterHandle
,
IN PPNDIS_PACKET
ReceivePackets
,
IN UINT
NumberOfPackets
);

Parameters

MiniportAdapterHandle

Handle originally input to the MiniportInitializefunction.

ReceivePackets

Pointer to an array of packet descriptor pointers, with each descriptor set up by the caller to specify the received data.

NumberOfPackets

Specifies how many pointers are in the array at ReceivePackets. The value must be at least 1.

Remarks

Drivers of busmaster DMA NICs are most likely to show significant gains in performance by making multipacket receive indications with this function. However, drivers that indicate out-of-band data with receive packets, such as packet priority and/or time stamps, can also call this function with a single packet at a time.

When a miniport calls this function, NDIS passes each pointer at ReceivePacketsseparately, in the miniport-determined order, to the ProtocolReceivePacketfunction(s) of bound protocol(s) that export this function. To other bound protocols, NDIS passes each packet pointer to the ProtocolReceivefunction(s).

If the miniport did not designate its NIC's medium as a type for which the system supplies a filter package in response to the OID_GEN_MEDIA_IN_USE query, NDIS forwards that driver's receive indications to all bound protocol drivers that export a ProtocolReceivePacketsfunction. Otherwise, NDIS automatically applies the appropriate filter library to the miniport's receive indications.

Any caller of this function must first set up the packet array, as follows:

• Each element is the pointer to a packet descriptor, which the caller must allocate from a packet pool. Each packet descriptor can have at most 16 bytes in its ProtocolReservedsection.
• All buffer descriptors chained to such a packet descriptor must be allocated from a buffer pool. The miniport must call the NdisAdjustBufferLengthfunction with any buffer descriptor mapping a receive buffer on the NIC that contains less received data than the full range of the receive buffer so that the buffer descriptor maps only the received data for the indication. The NIC driver must readjust the mapping with NdisAdjustBufferLengthwhen it regains ownership of such a buffer descriptor, as well.
• If the miniport indicates time stamps for received packets, it must set the TimeReceivedand/or TimeSentmembers in the NDIS_PACKET_OOB_DATAstructure associated with the packet descriptor using the NDIS_SET_PACKET_TIME_RECEIVEDand/or NDIS_SET_PACKET_TIME_SENTmacros. It can call the NdisGetCurrentSystemTimefunction once to set the receive time stamp for all packets of a particular packet array.
• The HeaderSizein the out-of-band data block must match the header size of each received packet for the medium. For example, a driver that selects Ethernet as its preferred medium at initialization would initialize the NDIS_PACKET_OOB_DATAstructure HeaderSizeto 14 when it allocates the packet descriptor.
• If the driver indicates additional out-of-band information with receives, it must set the SizeMediaSpecificInfoto the number of bytes of information supplied in the caller-allocated buffer at MediaSpecificInformation. The miniport can use the NDIS_SET_PACKET_MEDIA_SPECIFIC_INFOmacro to set these values. Otherwise, SizeMediaSpecificInfoshould be 0, and MediaSpecificInformationshould be NULL.
• The miniport can set the Statusmember of the out-of-band data block to NDIS_STATUS_RESOURCES if it needs to retain ownership of the packet descriptor and buffer descriptors of some element(s) in a particular indication. Setting this status for a packet implicitly sets the same status for all subsequent packets of the indicated array. Setting NDIS_STATUS_RESOURCES forces NDIS to indicate each such packet, one at a time, to bound protocols' ProtocolReceivefunctions, thus forcing each protocol to copy the packet data and release each packet to be returned to the miniport. Otherwise, the call to this function gives interested protocols exclusive, read-only access to the buffers chained to each packet until either of the following occurs:
  • The Statusin the out-of-band data block is set to NDIS_STATUS_SUCCESS on return from this function. In this case, the miniport regains ownership of the packet descriptor and all buffers chained to the packet. It can prepare these descriptors immediately for reuse in subsequent receive indications.
  • The Statusis set to NDIS_STATUS_PENDING on return from this function. In this case, the driver's MiniportReturnPacketfunction is called when the miniport regains ownership of the packet and buffer descriptors. It can then prepare these descriptors for reuse in subsequent receive indications.

    The miniport should use NDIS_GET_PACKET_STATUS to determine whether it has regained ownership of indicated packets when this function returns control.

    When the miniport regains ownership of an indicated packet descriptor, it prepares the associated out-of-band data block for reuse by passing the pointer returned by NDIS_OOB_DATA_FROM_PACKETto the NdisZeroMemoryfunction. As an alternative, the miniport can simply reset the relevant member(s) at the subsequent receive with the NDIS_SET_PACKET_ XXXmacro(s) or with the pointer returned by NDIS_OOB_DATA_FROM_PACKET.

    A miniport must not pass a packet descriptor pointer to NdisZeroMemory. Doing this destroys the packet descriptor, rendering it unusable for subsequent indications. To clear the associated out-of-band data block, the driver must pass the pointer returned by NDIS_OOB_DATA_FROM_PACKET.

    Packet arrays passed to this function can be allocated on the stack, which cannot be paged out in the NDIS library's receive-indication code path.

    When NDIS calls the ProtocolReceivefunction of a driver that exports a ProtocolReceivePacketfunction, ProtocolReceivecan call NdisQueryReceiveInformationto retrieve the out-of-band information associated with an incoming packet that was indicated as part of a packet array.

    Any miniport that calls this function must indicate full packets. Consequently, such a driver has no MiniportTransferDatafunction.

    A driver that calls this function can run at IRQL <= DISPATCH_LEVEL, but usually callers are running at DISPATCH_LEVEL.

    Requirements

    Runs on	Versions	Defined in	Include	Link to
    Windows CE OS	2.0 and later	Ndis.h

    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

    NdisAdjustBufferLength, NdisAllocateBuffer, NdisAllocatePacket, NdisChainBufferAtBack, NdisChainBufferAtFront, NdisZeroMemory

    
    

    ---

     Last updated on Tuesday, July 13, 2004

    © 2004 Microsoft Corporation. All rights reserved.