W_RETURN_PACKET_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 MiniportReturnPacket function is required in drivers that indicate receives with NdisMIndicateReceivePacket or NdisMCoIndicateReceivePacket.

Syntax

W_RETURN_PACKET_HANDLER MiniportReturnPacket;

VOID MiniportReturnPacket(
  _In_ NDIS_HANDLE  MiniportAdapterContext,
  _In_ PNDIS_PACKET Packet
)
{ ... }

Parameters

• MiniportAdapterContext [in]
  Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.

• Packet [in]
  Pointer to a packet descriptor being returned to the miniport driver, which previously indicated a packet array that contained this pointer.

Return value

None

Remarks

The following types of drivers must supply a MiniportReturnPacketfunction:

• A miniport driver of a bus-master DMA NIC that supports multipacket receives. Such drivers include serialized miniports that export a MiniportSendPackets function, deserialized miniports, and connection-oriented miniports.

• A miniport driver that supplies media-specific information, such as packet priorities, with its receive indications

• An NDIS intermediate driver that binds itself to a miniport driver that supplies a MiniportReturnPacket function

For Serialized Drivers

Any receive packet with associated NDIS_PACKET_OOB_DATAstructure in which the Statusis set to NDIS_STATUS_PENDING on return from NdisMIndicateReceivePacketwill be returned to MiniportReturnPacket. When all bound protocols have called NdisReturnPacketsas many times as necessary to release their references to the originally indicated packet array, NDIS returns pended packets from the array to the MiniportReturnPacketfunction of the driver that originally allocated the packet array.

If the driver, before indicating up a receive packet descriptor with NdisMIndicateReceivePacket, set the Statusmember in the NDIS_PACKET_OOB_DATA associated with the descriptor to NDIS_STATUS_SUCCESS, the driver must check the packet's Statuson return of NdisMIndicateReceivePacket:

• If the Status is set to NDIS_STATUS_SUCCESS, the packet descriptor and associated buffer descriptors have been returned to the driver.

• If the Status is set to NDIS_STATUS_PENDING, NDIS will return the packet descriptor to the driver's MiniportReturnPacket function.

For Deserialized and Connection-Oriented Drivers

If the driver, before indicating up a receive packet descriptor with NdisMIndicateReceivePacketor NdisMCoIndicateReceivePacket, sets the Statusmember in the NDIS_PACKET_OOB_DATAstructure associated with the packet descriptor to NDIS_STATUS_SUCCESS, NDIS returns that packet descriptor to the driver's MiniportReturnPacketfunction. However, if the miniport driver sets the Statusmember to NDIS_STATUS_RESOURCES, thereby indicating that it needs to retain ownership of the packet descriptor and associated buffer descriptors, NDIS implicitly returns the packet descriptor to the driver on return of NdisMCoIndicateReceivePacket.

A deserialized or connection-oriented miniport driver must not examine the Statusof indicated packets on return of NdisMIndicateReceivePacket. Instead, a deserialized miniport driver must save a packet's Statusin a local variable before indicating up the packet descriptor. When NdisMIndicateReceivePacketreturns, the miniport driver should check the saved packet Status. If the miniport driver set the packet's Statusto NDIS_STATUS_RESOURCES before indicating up the packet descriptor, it should reclaim the packet descriptor immediately after NdisMIndicateReceivePacketreturns, preferably by calling its own MiniportReturnPacketfunction. In this case, NDIS does not call the miniport driver's MiniportReturnPacketfunction to return the packet descriptor. If the miniport driver set the packet's Statusto NDIS_STATUS_SUCCESS before indicating up the packet descriptor, the miniport driver must not reclaim the packet descriptor until NDIS subsequently returns the packet descriptor to the miniport driver's MiniportReturnPacketfunction.

For All Drivers

Usually, MiniportReturnPacketprepares such a returned packet to be used in a subsequent receive indication. Although MiniportReturnPacketcould return the buffer descriptors chained to the packet to buffer pool and the packet descriptor itself to packet pool, it is far more efficient to reuse returned descriptors.

MiniportReturnPacketmust call NdisUnchainBufferAtXxx as many times as necessary to save the pointers to all chained buffer descriptors before it calls NdisReinitializePacket. Otherwise, MiniportReturnPacketcannot recover the buffer descriptors the driver originally chained to the packet for the indication.

MiniportReturnPacketalso can call NdisZeroMemorywith the pointer returned by NDIS_OOB_DATA_FROM_PACKETto prepare the packet's associated out-of-band block for reuse.

If a particular buffer descriptor was shortened to match the size of an indicated range of data, MiniportReturnPacketshould call NdisAdjustBufferLengthwith that buffer descriptor to restore its mapping of the NIC's receive buffer range.

Requirements

Send comments about this topic to Microsoft