FILTER_OID_REQUEST_COMPLETE callback function (ndis.h)

Article
10/21/2021

NDIS calls the FilterOidRequestComplete function to complete a filter driver request that queried or set information in an underlying driver.

Note You must declare the function by using the FILTER_OID_REQUEST_COMPLETE type. For more information, see the following Examples section.

Syntax

FILTER_OID_REQUEST_COMPLETE FilterOidRequestComplete;

void FilterOidRequestComplete(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

Parameters

[in] FilterModuleContext

A handle to the context area for the filter module. The filter driver created and initialized this context area in the FilterAttach function.

[in] OidRequest

A pointer to the NDIS_OID_REQUEST structure that the filter driver previously passed to the NdisFOidRequest function.

[in] Status

The final status of the request set by an underlying driver or by NDIS. This parameter determines what FilterOidRequestComplete does with the information at OidRequest . For a list of the possible status values, see the return values of NdisFOidRequest.

Return value

None

Remarks

FilterOidRequestComplete is an optional function. If a filter driver does not use OID requests, it can set the entry point for this function to NULL when it calls the NdisFRegisterFilterDriver function. If a filter driver defines a FilterOidRequest function, it must provide the FilterOidRequestComplete function.

If the NdisFOidRequest function returns NDIS_STATUS_PENDING, NDIS must call the FilterOidRequestComplete function to complete the OID request.

If a filter driver forwarded a request that it received in the FilterOidRequest function, FilterOidRequestComplete should pass the completion status up the driver stack by calling the NdisFOidRequestComplete function. The filter driver must call NdisFreeCloneOidRequest, to free the NDIS_OID_REQUEST structure, before it calls NdisFOidRequestComplete.

A filter driver should keep track of requests that it originates and ensure that it does not call NdisFOidRequestComplete when NDIS calls FilterOidRequestComplete for such requests.

NDIS calls FilterOidRequestComplete at IRQL <= DISPATCH_LEVEL.

Examples

To define a FilterOidRequestComplete function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a FilterOidRequestComplete function that is named "MyOidRequestComplete", use the FILTER_OID_REQUEST_COMPLETE type as shown in this code example:

FILTER_OID_REQUEST_COMPLETE MyOidRequestComplete;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyOidRequestComplete(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

The FILTER_OID_REQUEST_COMPLETE function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the FILTER_OID_REQUEST_COMPLETE function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL