FILTER_OID_REQUEST función de devolución de llamada (ndis.h)

Artículo
02/26/2024

NDIS llama a la función FilterOidRequest del controlador de filtro para procesar una solicitud OID asociada al módulo de filtro especificado.

Nota Debe declarar la función mediante el tipo FILTER_OID_REQUEST . Para obtener más información, consulte la sección Ejemplos siguientes.

Sintaxis

FILTER_OID_REQUEST FilterOidRequest;

NDIS_STATUS FilterOidRequest(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_OID_REQUEST OidRequest
)
{...}

Parámetros

[in] FilterModuleContext

Identificador del área de contexto del módulo de filtro que es el destino de esta solicitud. El controlador de filtro creó e inicializó este área de contexto en la función FilterAttach .

[in] OidRequest

Puntero a una estructura NDIS_OID_REQUEST que especifica la operación solicitada, incluido el código OID_XXX . La estructura puede especificar una solicitud de consulta OID o una solicitud de conjunto de OID. Para obtener más información sobre los OID, consulte NDIS OIDs.

Valor devuelto

FilterOidRequest devuelve uno de los siguientes valores de estado:

Código devuelto	Descripción
NDIS_STATUS_SUCCESS	FilterOidRequest completó correctamente la consulta o la operación de establecimiento del controlador de filtro para este módulo de filtro.
NDIS_STATUS_PENDING	Indica que el controlador de filtro completará la solicitud de forma asincrónica. Una vez que el controlador complete la solicitud, debe llamar a Función NdisFOidRequestComplete para informar a NDIS de que la solicitud se ha completado.
NDIS_STATUS_INVALID_OID	Indica que la solicitud, especificada en OidRequest, no es válida o no se reconoce.
NDIS_STATUS_NOT_SUPPORTED	FilterOidRequest no admite el OID, el OID es opcional.
NDIS_STATUS_BUFFER_TOO_SHORT	Indica que el búfer, proporcionado en OidRequest, es demasiado pequeño para contener los datos solicitados.
NDIS_STATUS_INVALID_LENGTH	Para una operación de consulta, el miembro InformationBufferLength de la estructura NDIS_OID_REQUEST no coincide con la longitud requerida por el OID especificado. FilterOidRequest devolvió el tamaño de búfer necesario, en bytes, en el miembro BytesNeeded de la estructura NDIS_OID_REQUEST.
NDIS_STATUS_INVALID_DATA	Para una operación set, los datos proporcionados en el miembro InformationBuffer de la estructura de NDIS_OID_REQUEST no eran válidos para el OID especificado.
NDIS_STATUS_NOT_ACCEPTED	FilterOidRequest intentó recopilar la información solicitada, pero no se realizó correctamente.
NDIS_STATUS_RESOURCES	Error de FilterOidRequest debido a recursos insuficientes.
NDIS_STATUS_FAILURE	FilterOidRequest devuelve NDIS_STATUS_FAILURE si no se aplica ninguno de los valores anteriores. El controlador de filtro debe llamar a la función NdisWriteErrorLogEntry con parámetros que especifican el motivo del error.

Comentarios

FilterOidRequest es una función opcional. Si un controlador de filtro no usa solicitudes OID, puede establecer el punto de entrada de esta función en NULL cuando llama a la función NdisFRegisterFilterDriver . Si un controlador de filtro define una función FilterOidRequestComplete , debe proporcionar la función FilterOidRequest .

NDIS llama a la función FilterOidRequest del controlador de filtro para procesar las solicitudes de OID que se originan mediante el exceso de controladores. Los controladores de filtro pueden reenviar estas solicitudes a controladores subyacentes mediante una llamada a la función NdisFOidRequest .

Antes de que el controlador llame a NdisFOidRequest, el controlador debe asignar una estructura NDIS_OID_REQUEST y transferir la información de solicitud a la nueva estructura llamando a NdisAllocateCloneOidRequest. Como opción, un controlador de filtro puede completar una solicitud inmediatamente sin reenviar la solicitud.

Para completar una solicitud de forma sincrónica, el controlador de filtro devuelve NDIS_STATUS_SUCCESS o un estado de error. Si el controlador devuelve NDIS_STATUS_PENDING, debe llamar a la función NdisFOidRequestComplete para informar al NDIS de que la solicitud se ha completado.

Para una operación de consulta, FilterOidRequest devuelve la información solicitada en el miembro InformationBuffer y establece la variable en el miembro BytesWritten de la estructura NDIS_OID_REQUEST en la cantidad de información que devolvió. Los controladores subyacentes lo hacen si el controlador de filtro pasó la solicitud en con NdisFOidRequest.

Para una operación set, FilterOidRequest puede usar los datos del miembro InformationBuffer de la estructura NDIS_OID_REQUEST para establecer la información requerida por el OID especificado. En este caso, FilterOidRequest establece la variable en BytesRead en la cantidad de los datos proporcionados que usó. Los controladores subyacentes lo hacen si el controlador de filtro pasó la solicitud en con NdisFOidRequest.

Al igual que los controladores de miniporte, los controladores de filtro solo pueden recibir una solicitud a la vez. NDIS serializa las solicitudes que envía a un controlador de filtro. NDIS no puede llamar a FilterOidRequest antes de que un controlador de filtro complete la solicitud actual.

NDIS llama a FilterOidRequest en IRQL <= DISPATCH_LEVEL.

Ejemplos

Para definir una función FilterOidRequest , primero debe proporcionar una declaración de función que identifique el tipo de función que está definiendo. Windows proporciona un conjunto de tipos de función para controladores. Declarar una función mediante los tipos de función ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación a encontrar errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función FilterOidRequest denominada "MyOidRequest", use el tipo FILTER_OID_REQUEST como se muestra en este ejemplo de código:

FILTER_OID_REQUEST MyOidRequest;

A continuación, implemente la función de la siguiente manera:

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

El tipo de función FILTER_OID_REQUEST se define en el archivo de encabezado Ndis.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función FILTER_OID_REQUEST en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores NDIS.

Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compatible con NDIS 6.0 y versiones posteriores.
Plataforma de destino	Windows
Encabezado	ndis.h (incluya Ndis.h)
IRQL	<= DISPATCH_LEVEL