OID_RECEIVE_FILTER_FREE_QUEUE
NDIS protocol drivers issue object identifier (OID) set requests of OID_RECEIVE_FILTER_FREE_QUEUE to free a receive queue.
The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_RECEIVE_QUEUE_FREE_PARAMETERS structure with a queue identifier of type NDIS_RECEIVE_QUEUE_ID.
Remarks
The OID set request of OID_RECEIVE_FILTER_FREE_QUEUE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue interface.
After an overlying driver issues the OID_RECEIVE_FILTER_ALLOCATE_QUEUE OID to allocate a receive queue, it issues the OID_RECEIVE_FILTER_FREE_QUEUE OID to free the receive queue.
When NDIS requests a miniport driver to free a VMQ receive queue, it follows these steps:
The network adapter stops the DMA transfer of data to receive buffers that are associated with the receive queue, after which the queue must enter the DMA Stopped state. The network adapter probably stopped the DMA activity when it received the OID_RECEIVE_FILTER_CLEAR_FILTER OID request to clear the last set filter on the receive queue.
The miniport driver generates an NDIS_STATUS_RECEIVE_QUEUE_STATE status indication with the QueueState member of the NDIS_RECEIVE_QUEUE_STATE structure set to NdisReceiveQueueOperationalStateDmaStopped to notify NDIS that the DMA transfer has been stopped.
The miniport driver waits for all the indicated receive packets for that queue to be returned to the miniport driver.
The miniport driver frees all the shared memory that it allocated for the network adapter's receive buffers that are associated with the queue by calling NdisFreeSharedMemory.
The miniport driver completes the OID_RECEIVE_FILTER_FREE_QUEUE OID request to free the receive queue.
Miniport drivers call the NdisFreeSharedMemory function to free shared memory for a queue. If the miniport driver allocated the shared memory for a nondefault queue, the driver frees the shared memory in the context of the OID_RECEIVE_FILTER_FREE_QUEUE OID while it is freeing the queue. Miniport drivers free shared memory that they allocated for the default queue in the context of the MiniportHaltEx function.
An overlying driver must free all the filters that it set on a queue before it frees the queue. Also, an overlying driver must free all the receive queues that it allocated on a network adapter before it calls the NdisCloseAdapterEx function to close a binding to the network adapter. NDIS frees all the queues that are allocated on a network adapter before it calls the miniport driver's MiniportHaltEx function.
Return Status Codes
The miniport driver's MiniportOidRequest function returns one of the following values for this request:
| Term | Description |
|---|---|
NDIS_STATUS_SUCCESS |
The miniport driver completed the request successfully. |
NDIS_STATUS_PENDING |
The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the NdisMOidRequestComplete function, passing NDIS_STATUS_SUCCESS for the Status parameter. |
NDIS_STATUS_NOT_ACCEPTED |
The miniport driver is resetting. |
NDIS_STATUS_REQUEST_ABORTED |
The miniport driver stopped processing the request. For example, NDIS called the MiniportResetEx function. |
NDIS returns one of the following status codes for this request:
| Status code | Description |
|---|---|
NDIS_STATUS_SUCCESS |
The requested queue was freed successfully. |
NDIS_STATUS_PENDING |
The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler for the caller after the request has completed. |
NDIS_STATUS_INVALID_PARAMETER |
The queue identifier is invalid. |
NDIS_STATUS_INVALID_LENGTH |
The information buffer is too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the NDIS_OID_REQUEST structure to the minimum buffer size that is required. |
Requirements
Version |
Supported in NDIS 6.20 and later. |
Header |
Ntddndis.h (include Ndis.h) |
See also
NDIS_RECEIVE_QUEUE_FREE_PARAMETERS