OID_RECEIVE_FILTER_SET_FILTER

Article
02/18/2023

An overlying driver issues an OID method request of OID_RECEIVE_FILTER_SET_FILTER to set a filter on a network adapter.

The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to a caller-allocated buffer. This buffer is formatted to contain the following:

An NDIS_RECEIVE_FILTER_PARAMETERS structure that specifies the parameters for an NDIS receive filter.
An array of NDIS_RECEIVE_FILTER_FIELD_PARAMETERS structures that specifies the filter test criterion for a field in a network packet header.

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_FILTER_PARAMETERS structure. If the overlying driver is creating a new receive filter, NDIS updates this structure with a new filter identifier.

Remarks

NDIS receive filters are used in the following NDIS interfaces:

NDIS Packet Coalescing. For more information about how to use receive filters in this interface, see Managing Packet Coalescing Receive Filters.
Single Root I/O Virtualization (SR-IOV). For more information about how to use receive filters in this interface, see Setting a Receive Filter on a Virtual Port.
Virtual Machine Queue (VMQ). For more information about how to use receive filters in this interface, see Setting and Clearing VMQ Filters.

The OID method request of OID_RECEIVE_FILTER_SET_FILTER is mandatory for miniport drivers that support the NDIS packet coalescing, SR-IOV, or VMQ interface.

The overlying driver initializes the NDIS_RECEIVE_FILTER_PARAMETERS structure with its requested filter configuration. NDIS assigns a filter identifier in the FilterId member of the NDIS_RECEIVE_FILTER_PARAMETERS structure and passes the method request to the underlying miniport driver.

Each filter that is set on a receive queue has a unique filter identifier for a network adapter. That is, the filter identifiers are not duplicated on different queues that the network adapter manages. When NDIS receives an OID request to set a filter on a receive queue, it verifies the filter parameters. After NDIS allocates the necessary resources and the filter identifier, it submits the OID request to the underlying network adapter. If the network adapter can successfully allocate the necessary software and hardware resources for the filter, it completes the OID request with a return status of NDIS_STATUS_SUCCESS.

Note Starting with NDIS 6.30, packet coalescing receive filter are only supported on the default receive queue of the network adapter. This receive queue has an identifier of NDIS_DEFAULT_RECEIVE_QUEUE_ID.

The miniport driver must retain the filter identifiers for the allocated receive filters. NDIS uses the identifier of a filter in later OID requests to change the receive filter parameters or clear the receive filter.

After a miniport driver receives an OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE request and it has filters that are set on the queue, the queue is in the Running state. In this state, the miniport driver can start indications of packets in the queue by calling NdisMIndicateReceiveNetBufferLists.

Additional Guidelines for the SR-IOV Interface

The following points apply to miniport drivers that support the SR-IOV interface:

For the SR-IOV interface, a receive queue is created on a default or nondefault virtual port (VPort).

Note Starting with Windows Server 2012, the SR-IOV interface only supports the default receive queue of a VPort.

After an SR-IOV VPort is allocated through an OID set request of OID_NIC_SWITCH_CREATE_VPORT, overlying drivers can set filters on the VPort with OID requests of OID_RECEIVE_FILTER_SET_FILTER.

Note Only the overlying driver that allocated the VPort can set a filter on that VPort.
Because the default VPort always exists, overlying drivers can always set a filter on the default VPort.
When the VPort is created, no receive filters are set on it. In this case, the miniport driver must not indicate any receive packets on that VPort before the miniport driver receives an OID request of OID_RECEIVE_FILTER_SET_FILTER for the VPort. After this OID request is issued, the miniport driver can indicate packets on that VPort.

Note If the miniport driver indicates packets on a VPort while it is processing an OID request of OID_RECEIVE_FILTER_SET_FILTER, it must complete the OID request and return an NDIS_STATUS_SUCCESS status code.

Additional Guidelines for the VMQ Interface

The following points apply to miniport drivers that support the VMQ interface:

After a VMQ receive queue is allocated, overlying drivers can set filters on the receive queue with OID requests of OID_RECEIVE_FILTER_SET_FILTER.

Note Only the protocol driver that allocated a receive queue can set a filter on that queue.
Because the default queue always exists, overlying drivers can always set a filter on the default queue. If the network adapter supports a drop queue, overlying drivers can set a filter on the drop queue.

Overlying drivers do not own the default or drop queues. Therefore, all protocol drivers that are bound to a network adapter use the default or drop queue.
When the receive queue is created, no receive filters are set on it. In this case, the miniport driver must not indicate any receive packets on that receive queue before the miniport driver receives an OID request of OID_RECEIVE_FILTER_SET_FILTER for the receive queue. After this OID request is issued, the miniport driver can indicate packets on that receive queue.

Note If the miniport driver indicates packets on a queue while it is processing an OID request of OID_RECEIVE_FILTER_SET_FILTER, it must complete the OID request and return an NDIS_STATUS_SUCCESS status code.

Return status codes

The miniport driver returns one of the following status codes for the OID method request of OID_RECEIVE_FILTER_SET_FILTER:

NDIS_STATUS_SUCCESS
The filter was set on the queue successfully. The information buffer contains the updated NDIS_RECEIVE_FILTER_PARAMETERS structure.

NDIS_STATUS_PENDING
The request is pending completion. The final status code and results will be passed to the OID request completion handler of the caller.

NDIS_STATUS_INVALID_PARAMETER
One or more of the parameters that the overlying driver provided was not valid.

NDIS_STATUS_INVALID_LENGTH
The information buffer was too short. NDIS sets 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 an earlier version than 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)