OID_RECEIVE_FILTER_SET_FILTER

OID_RECEIVE_FILTER_SET_FILTER

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:

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:

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)

See also

NdisMIndicateReceiveNetBufferLists
NDIS_OID_REQUEST
NDIS_RECEIVE_FILTER_PARAMETERS
NET_BUFFER_LIST
NET_BUFFER_LIST_RECEIVE_FILTER_ID
OID_NIC_SWITCH_CREATE_VPORT
OID_RECEIVE_FILTER_CLEAR_FILTER
OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft