|This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.|
This macro sets the Statusmember in the structure associated with a specified packet descriptor just before a driver calls the NdisMIndicateReceivePacketfunction or before a driver's MiniportSendPacketsfunction returns control.
NDIS_SET_PACKET_STATUS( IN PNDIS_PACKET Packet , IN NDIS_STATUS Status );
|NDIS_STATUS_SUCCESS||The driver is relinquishing ownership of the packet
to be indicated by the
NdisIndicateReceivePacketfunction until the packet
descriptor is returned to its
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
NdisMIndicateReceivePacketfunction and of all subsequent
packets in the packet array. All these packets are indicated, one
at a time, to the
ProtocolReceivefunctions 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 ProtocolReceiveCompletefunctions to begin postprocessing 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. A busmaster DMA NIC driver might call the NdisMAllocateSharedMemoryAsyncfunction in these circumstances to get additional NIC receive buffer space.
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 MiniportSendPacketsfunction can set one of the following values:
|NDIS_STATUS_PENDING||The driver completes the requested send operation
After MiniportSendPacketsreturns control, the driver calls the NdisMSendCompletefunction with a final completion status for the specified packet descriptor, which NDIS propagates to the ProtocolSendCompletefunction 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 Statusmember for all subsequent packet descriptors in the array sent to MiniportSendPacketsis set to the same value. NDIS queues these packet descriptors internally in the same order for resubmission to MiniportSendComplete, whichever call occurs first. NDIS reflects this miniport-set status value to protocols as NDIS_STATUS_PENDING.
MiniportSendPacketsis 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, MiniportSendPacketsmust set the Statusmember for the specified packet descriptor so that NDIS can reflect this status back to the protocol that initiated the send when NDIS calls ProtocolSendCompletewith the returned packet descriptor.
Only drivers that indicate receives with NdisMIndicateReceivePacketto bound protocols and/or drivers that have MiniportSendPacketsfunctions use this macro.
After such an underlying driver has set the Statusfor a number of packet descriptors in an array and called NdisMIndicateReceivePacketwith the array of pointers to those packet descriptors, it uses the NDIS_GET_PACKET_STATUSmacro when NdisMIndicateReceivePacketreturns control. The returned Statusin the NDIS_PACKET_OOB_DATAstructure associated with each packet descriptor that the driver indicates with NDIS_STATUS_SUCCESS determines what the indicating driver does next, as follows:
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.
When MiniportSendPacketssets the Statusfor 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 ProtocolSendCompletefunction of the allocating driver and propagates the miniport-set status value as an input parameter to ProtocolSendComplete. Otherwise, the underlying driver calls NdisMSendCompletewith the packet descriptor and final status when the asynchronous send operation is done.
Protocol drivers should never test the Statusvalue 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 ProtocolSendCompletefunction is called with the packet descriptor.
A driver that uses this macro runs at IRQL <=DISPATCH_LEVEL.
|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.
Last updated on Tuesday, July 13, 2004