OID_RECEIVE_FILTER_ALLOCATE_QUEUE
Overlying drivers issue object identifier (OID) method requests of OID_RECEIVE_FILTER_ALLOCATE_QUEUE to allocate a queue that has an initial set of configuration parameters.
The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_RECEIVE_QUEUE_PARAMETERS structure. After a successful return from the OID method request, the InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_RECEIVE_QUEUE_PARAMETERS structure that has a new queue identifier.
Remarks
The OID method request of OID_RECEIVE_FILTER_ALLOCATE_QUEUE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue (VMQ) interface.
The overlying driver initializes the NDIS_RECEIVE_QUEUE_PARAMETERS structure with its requested queue configuration. NDIS assigns a queue identifier in the QueueId member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure and passes the method request to the miniport driver.
Note The overlying driver can set the NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION and NDIS_RECEIVE_QUEUE_PARAMETERS_LOOKAHEAD_SPLIT_REQUIRED flags in the Flags member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure. The other flags are not used for queue allocation.
After a miniport driver is issued an OID request of OID_RECEIVE_FILTER_ALLOCATE_QUEUE and handles it successfully, the queue is in the Paused state.
The overlying driver must use the queue identifier that NDIS provides in subsequent OID requests, for example, to modify the queue parameters or free the queue. The queue identifier is also included in the out-of-band (OOB) data on all NET_BUFFER_LIST structures that are associated with the queue. Drivers use the NET_BUFFER_LIST_RECEIVE_QUEUE_ID macro to retrieve the queue identifier in a NET_BUFFER_LIST structure.
When NDIS receives an OID request to allocate a receive queue, it verifies the queue parameters. After NDIS allocates the necessary resources and the queue identifier, it submits the OID request to the underlying miniport driver. The queue identifier is unique to the associated network adapter.
If the miniport driver can successfully allocate the necessary software and hardware resources for the receive queue, it completes the OID request by returning NDIS_STATUS_SUCCESS.
The miniport driver must retain the queue identifiers for the allocated receive queues. NDIS uses the queue identifier of a receive queue for subsequent calls to the miniport driver in order to set a receive filter on the receive queue, change the receive queue parameters, or free the receive queue.
After an overlying driver allocates one or more receive queues and optionally sets the initial filters, it must issue OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE set OID requests to notify the miniport driver that the allocation is complete for the current batch of receive queues.
The miniport driver must not retain any packets in a receive queue if there are no filters set on that queue. If either a queue never had any filters set or all the filters were cleared, the queue should be empty and any packets should be discarded. That is, the packets are not indicated up the driver stack or retained in the queue.
Overlying drivers use OID requests of OID_RECEIVE_FILTER_FREE_QUEUE to free queues that they allocate.
Return Status Codes
Either NDIS or the miniport driver returns one of the following status codes for the OID method request of OID_RECEIVE_FILTER_ALLOCATE_QUEUE.
| Status code | Description |
|---|---|
NDIS_STATUS_SUCCESS |
The queue was allocated successfully. The information buffer contains the updated NDIS_RECEIVE_QUEUE_PARAMETERS structure. |
NDIS_STATUS_PENDING |
The request is pending completion. The final status code and results will be passed to an OID request completion handler of the caller. |
NDIS_STATUS_INVALID_PARAMETER |
One or more of the parameters that the overlying driver provided were not valid. |
NDIS_STATUS_INVALID_LENGTH |
The information buffer was too short. NDIS set the DATA.METHOD_INFORMATION.BytesNeeded member in the NDIS_OID_REQUEST structure to the minimum buffer size that is required. |
NDIS_STATUS_NOT_SUPPORTED |
The NDIS version of the miniport driver is earlier than version 6.20. |
NDIS_STATUS_FAILURE |
The request failed for other reasons. |
Requirements
Version |
Supported in NDIS 6.20 and later. |
Header |
Ntddndis.h (include Ndis.h) |
See also
NET_BUFFER_LIST_RECEIVE_QUEUE_ID