NdisMCoIndicateReceivePacket 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.

NdisMCoIndicateReceivePacket notifies NDIS that an array of packets on a VC is available to be forwarded to the appropriate client or call manager.

Syntax

VOID NdisMCoIndicateReceivePacket(
  _In_ NDIS_HANDLE   NdisVcHandle,
  _In_ PPNDIS_PACKET PacketArray,
  _In_ UINT          NumberOfPackets
);

Parameters

NdisVcHandle [in]
Specifies the handle identifying the VC. The NIC driver originally obtained this handle as an input parameter to its MiniportCoCreateVc function, either when a client set up an outgoing call or when the call manager created a VC for a client-registered SAP on which to indicate an incoming-call notification.
PacketArray [in]
Pointer to an array of packet descriptor pointers, with each descriptor set up by the caller to specify the received data.
NumberOfPackets [in]
Specifies how many pointers are in the array at PacketArray. The value must be at least one.

Return value

None

Remarks

A call to NdisMCoIndicateReceivePacket causes NDIS to call the ProtocolCoReceivePacket function of the client or call manager that shares the given NdisVcHandle with the connection-oriented NIC driver. Whether a connection-oriented NIC driver makes multipacket or single-packet receive indications is implementation-dependent. However, multipacket indications yield better performance.

Before it calls NdisMCoIndicateReceivePacket, the miniport driver must set up the packet array as follows:

Each element at PacketArray is the pointer to a packet descriptor, which the caller allocated from packet pool with NdisAllocatePacket.
All buffer descriptors chained to such a packet descriptor were allocated from buffer pool with NdisAllocateBuffer. The miniport driver must call NdisAdjustBufferLength 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 will map only the received data for the indication. (The NIC driver must readjust the mapping with NdisAdjustBufferLength when it regains ownership of such a buffer descriptor, as well.)
If the miniport driver indicates timestamps for receives, it must set the TimeReceived or TimeSent members in the NDIS_PACKET_OOB_DATA associated with the packet descriptor using the NDIS_SET_PACKET_TIME_RECEIVED and/or NDIS_SET_PACKET_TIME_SENT macros. It can call NdisGetCurrentSystemTime once to get the value to be set as the receive timestamp for all packets of a particular array.
The HeaderSize in the out-of-band data block must match the header size of each received packet for the connection-oriented medium.
If the driver indicates any additional out-of-band information with receives, it must set the SizeMediaSpecificInfo to the number of bytes of information supplied in the caller-allocated buffer at MediaSpecificInformation in the OOB block. The miniport driver can use the NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO macro to set these values. Otherwise, SizeMediaSpecificInfo should be zero, and MediaSpecificInformation should be NULL.
The miniport driver can set the Status member of the out-of-band data block to NDIS_STATUS_RESOURCES if it needs to retain ownership of the packet descriptor(s) and associated buffer descriptor(s) for some packet(s) in a particular indication.

Setting NDIS_STATUS_RESOURCES forces NDIS to indicate each such packet descriptor, one at a time, to the protocol that shares the NdisVcHandle, thereby forcing that client or call manager to copy the packet data and release each packet descriptor (and the associated buffers) back to the miniport driver. Otherwise, the call to NdisMCoIndicateReceivePacket gives the protocol exclusive, read-only access to the buffers chained to each packet descriptor until the packet descriptor is returned to the miniport driver's MiniportReturnPacket function.

The miniport driver does not have to examine the status of indicated packets on return of NdisMCoIndicateReceivePacket:

If the miniport driver set the packet's Status to NDIS_STATUS_SUCCESS before indicating up the packet descriptor, the packet's Status is always NDIS_STATUS_PENDING on return of NdisMCoIndicateReceivePacket. NDIS subsequently returns the packet descriptor to the miniport driver's MiniportReturnPacket function with the packet's Status set to NDIS_STATUS_SUCCESS.
If the miniport driver set the packet's Status to NDIS_STATUS_RESOURCES before indicating up the packet descriptor, the packet's Status is always NDIS_STATUS_SUCCESS on return of NdisMCoIndicateReceivePacket.

When the miniport driver regains ownership of an indicated packet descriptor, it can prepare the associated out-of-band data blocks for reuse by passing the pointer returned by NDIS_OOB_DATA_FROM_PACKET to NdisZeroMemory. As an alternative, the miniport driver can simply reset the relevant member(s) at the subsequent receive with the NDIS_SET_PACKET_XXX macro(s) or with the pointer returned by NDIS_OOB_DATA_FROM_PACKET. However, a miniport driver should never pass a packet descriptor pointer to NdisZeroMemory, because doing this destroys the packet descriptor, rendering it unusable for subsequent receive indications.

After some miniport driver-determined number of calls to NdisMCoIndicateReceivePacket from its MiniportHandleInterrupt function, the miniport driver must call NdisMCoReceiveComplete.

If a protocol does not return the miniport driver-allocated resources for a receive indication promptly enough, the NIC driver can call NdisMCoIndicateStatus with NDIS_STATUS_RESOURCES to alert the offending protocol that the NIC driver is running low on available packet or buffer descriptors (or even on NIC receive buffer space) for subsequent receive indications.

If a miniport driver that is running on a Microsoft Windows XP or Windows 2000 system indicates packets that consist of multiple chained NDIS_BUFFER structures, the driver must do one of the following to ensure that the host stack properly processes such packets:

When responding to a query of OID_GEN_MAC_OPTIONS shortly after driver initialization, the driver must not set the NDIS_MAC_OPTION_COPY_LOOKAHEAD_DATA flag.
Before calling NdisMCoIndicateReceivePacket, the driver must set the Status member of the NDIS_PACKET_OOB_DATA structure that is associated with the packet descriptor to NDIS_STATUS_RESOURCES.

A miniport driver that is running on a Windows Server 2003 or later system does not have to handle the preceding situation.

Callers of NdisMCoIndicateReceivePacket must be running at IRQL = DISPATCH_LEVEL. A NIC driver generally makes this call from its MiniportHandleInterrupt function, which always runs at IRQL = DISPATCH_LEVEL.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMCoIndicateReceiveNetBufferListsinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	DISPATCH_LEVEL