NDIS_SET_PACKET_STATUS

Article
06/30/2006

This macro sets the Status member in the structure associated with a specified packet descriptor just before a driver calls the NdisMIndicateReceivePacket function or before a driver's MiniportSendPackets function returns control.

NDIS_STATUS NDIS_SET_PACKET_STATUS(
  PNDIS_PACKET _Packet,
  NDIS_STATUS _Status
);

Parameters

_Packet
Pointer to a packet descriptor allocated either by the caller, for a receive indication, or by a protocol, for a send.

_Status
Specifies the status to be set, which can be either of the following values.

Value	Description
NDIS_STATUS_SUCCESS	The driver is relinquishing ownership of the packet to be indicated by the NdisMIndicateReceivePacket function until the packet descriptor is returned to its MiniportReturnPacket function. Protocols that receive the indication can use the packet descriptor, along with all buffers mapped by buffer descriptors chained to the packet descriptor and any out-of-band information supplied with the packet, to copy the indicated net packet data, possibly forwarding the processed copy to interested clients.
NDIS_STATUS_RESOURCES	The driver is retaining ownership of the packet to be indicated by the NdisMIndicateReceivePacket function and of all subsequent packets in the packet array. All these packets are indicated, one at a time, to the ProtocolReceive functions of bound protocols. Setting this status forces bound protocols to return ownership of each such packet descriptor, of any medium-specific buffer in the out-of-band data block for each packet descriptor, and of the memory mapped by each packet descriptor's respective chained buffer descriptors to the indicating driver more quickly. The protocols must wait for a call to their ProtocolReceiveComplete functions to begin post-processing the data that they copied from the indication and forwarding the processed data to their clients. An indicating driver sets this status if it is running low on packet pool or buffer pool. An indicating NIC driver usually sets this status if it is running low on NIC receive buffers due to high network traffic. NDIS assumes that, if this status is set for a packet in an indicated array, it is set for all subsequent packets in that array. Consequently, an indicating driver need not set the status for subsequent packet descriptors in an array after it sets this status in the out-of-band block for one packet descriptor.

NDIS_STATUS_SUCCESS

The driver is relinquishing ownership of the packet to be indicated by the NdisMIndicateReceivePacket function until the packet descriptor is returned to its MiniportReturnPacket function.

Protocols that receive the indication can use the packet descriptor, along with all buffers mapped by buffer descriptors chained to the packet descriptor and any out-of-band information supplied with the packet, to copy the indicated net packet data, possibly forwarding the processed copy to interested clients.

NDIS_STATUS_RESOURCES

The driver is retaining ownership of the packet to be indicated by the NdisMIndicateReceivePacket function and of all subsequent packets in the packet array. All these packets are indicated, one at a time, to the ProtocolReceive functions of bound protocols.

Setting this status forces bound protocols to return ownership of each such packet descriptor, of any medium-specific buffer in the out-of-band data block for each packet descriptor, and of the memory mapped by each packet descriptor's respective chained buffer descriptors to the indicating driver more quickly. The protocols must wait for a call to their ProtocolReceiveComplete functions to begin post-processing the data that they copied from the indication and forwarding the processed data to their clients.

An indicating driver sets this status if it is running low on packet pool or buffer pool. An indicating NIC driver usually sets this status if it is running low on NIC receive buffers due to high network traffic.

NDIS assumes that, if this status is set for a packet in an indicated array, it is set for all subsequent packets in that array. Consequently, an indicating driver need not set the status for subsequent packet descriptors in an array after it sets this status in the out-of-band block for one packet descriptor.

For packet descriptors used in sends, the MiniportSendPackets function can set one of the following values.

Value	Description
NDIS_STATUS_PENDING	The driver completes the requested send operation asynchronously. After MiniportSendPackets returns control, the driver calls the NdisMSendComplete function with a final completion status for the specified packet descriptor, which NDIS propagates to the ProtocolSendComplete function of the driver that allocated the resources specified by the packet descriptor and initiated the send.
NDIS_STATUS_RESOURCES	The driver cannot process all sends specified in a packet array due to current resource constraints. NDIS assumes that the Status member for all subsequent packet descriptors in the array sent to MiniportSendPackets is set to the same value. NDIS reflects this miniport-set status value to protocols as NDIS_STATUS_PENDING.
NDIS_STATUS_XXX	MiniportSendPackets is completing a specified send request before it returns control. Whether such a send packet is completed with NDIS_STATUS_SUCCESS or a driver-determined error status, MiniportSendPackets must set the Status member for the specified packet descriptor so that NDIS can reflect this status back to the protocol that initiated the send when NDIS calls ProtocolSendComplete with the returned packet descriptor.

Return Values

The return value is the _Status value.

Remarks

Only drivers that indicate receives with NdisMIndicateReceivePacket to bound protocols and/or drivers that have MiniportSendPackets functions use this macro.

After such an underlying driver has set the Status for a number of packet descriptors in an array and called NdisMIndicateReceive with the array of pointers to those packet descriptors, it uses the NDIS_GET_PACKET_STATUS macro when NdisMIndicateReceivePacket returns control. The returned Status in the NDIS_PACKET_OOB_DATA structure associated with each packet descriptor that the driver indicates with NDIS_STATUS_SUCCESS determines what the indicating driver does next. The following table shows the value associated with each flag.

Value	Description
NDIS_STATUS_SUCCESS	If this is set on return from a miniport's call to NdisMIndicatePacket, the miniport regains ownership of the following: The packet descriptor The associated out-of-band data block associated with the packet descriptor and of any media-specific information buffer specified in this block All buffers mapped by buffer descriptors chained to the packet descriptor The driver can prepare these descriptors, the out-of-band block, and media-specific information buffer, if any, for reuse in subsequent receive indications immediately.
NDIS_STATUS_PENDING	If this is set on return from NdisMIndicateReceive, protocols retain ownership of the packet descriptor, of its associated out-of-band data block, of any buffer specified in this block, and of all buffers mapped by buffer descriptors chained to the packet descriptor until the packet descriptor is returned to the indicating driver's MiniportReturnPacket function. However, protocols are given read-only access to these miniport-allocated resources.

NDIS_STATUS_SUCCESS

If this is set on return from a miniport's call to NdisMIndicatePacket, the miniport regains ownership of the following:

The packet descriptor
The associated out-of-band data block associated with the packet descriptor and of any media-specific information buffer specified in this block
All buffers mapped by buffer descriptors chained to the packet descriptor

The driver can prepare these descriptors, the out-of-band block, and media-specific information buffer, if any, for reuse in subsequent receive indications immediately.

NDIS_STATUS_PENDING

If this is set on return from NdisMIndicateReceive, protocols retain ownership of the packet descriptor, of its associated out-of-band data block, of any buffer specified in this block, and of all buffers mapped by buffer descriptors chained to the packet descriptor until the packet descriptor is returned to the indicating driver's MiniportReturnPacket function. However, protocols are given read-only access to these miniport-allocated resources.

When MiniportSendPackets sets the Status for an incoming send packet to anything other than NDIS_STATUS_PENDING or NDIS_STATUS_RESOURCES, it completes the packet and relinquishes ownership of all resources specified by the associated packet descriptor. NDIS returns the packet descriptor to the ProtocolSendComplete function of the allocating driver and propagates the miniport-set status value as an input parameter to ProtocolSendComplete. Otherwise, the underlying driver calls NdisMSendComplete with the packet descriptor and final status when the asynchronous send operation is done.

Protocol drivers should never test the Status value in the associated out-of-band data block on return from NdisSend. NDIS or the underlying driver retains ownership of the packet descriptor, of the associated out-of-band block, any buffers specified in this block, and of all buffers mapped by buffer descriptors chained to the packet descriptor until the ProtocolSendComplete function is called with the packet descriptor.

The NDIS_SET_PACKET_STATUS macro is defined as follows.

#define NDIS_SET_PACKET_STATUS(_Packet, _Status)            \
    ((PNDIS_PACKET_OOB_DATA)((PUCHAR)(_Packet) +            \
    (_Packet)->Private.NdisPacketOobOffset))->Status = (_Status)

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.

NDIS_SET_PACKET_STATUS

Parameters

Return Values

Remarks

Requirements

See Also

Additional resources