EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST función de devolución de llamada (wdfqueryinterface.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

La función de devolución de llamada de eventos EvtDeviceProcessQueryInterfaceRequest de un controlador examina la solicitud de otro controlador para acceder a una interfaz definida por el controlador, antes de que el marco pase la interfaz al controlador solicitante.

Sintaxis

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

NTSTATUS EvtWdfDeviceProcessQueryInterfaceRequest(
  [in]      WDFDEVICE Device,
  [in]      LPGUID InterfaceType,
  [in, out] PINTERFACE ExposedInterface,
  [in, out] PVOID ExposedInterfaceSpecificData
)
{...}

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] InterfaceType

Puntero al GUID que identifica la interfaz definida por el controlador.

[in, out] ExposedInterface

Puntero a una estructura INTERFACE que describe la interfaz definida por el controlador y la proporcionó el controlador que solicita acceso a la interfaz.

[in, out] ExposedInterfaceSpecificData

Puntero a información adicional, opcional, definida por el controlador y específica de la interfaz. Los controladores basados en marcos especifican este valor proporcionando un valor de parámetro InterfaceSpecificData distinto de NULL al llamar a WdfFdoQueryForInterface.

Valor devuelto

Si la función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest recibe un GUID que admite y, si la función no encuentra ningún error, debe devolver STATUS_SUCCESS u otro valor de estado para el que NT_SUCCESS(status) es igual a TRUE. El marco de trabajo sigue pasando la solicitud a la pila para ver si los controladores adicionales también admiten la interfaz.

La función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest debe devolver STATUS_NOT_SUPPORTED si determina que, para un caso determinado, no atenderá la interfaz. El marco de trabajo continúa pasando la solicitud a la pila para ver si otro controlador admite la interfaz. Para obtener más información sobre esta situación, vea la siguiente sección Comentarios.

Si la función de devolución de llamada encuentra un error, debe devolver un valor de estado para el que NT_SUCCESS(status) es igual a FALSE. El marco produce un error en la solicitud del otro controlador para la interfaz y no pasa la solicitud a la pila.

Comentarios

Los controladores basados en marcos registran una función de devolución de llamada de eventos EvtDeviceProcessQueryInterfaceRequest llamando a WdfDeviceAddQueryInterface.

Si la interfaz definida por el controlador solo admite la comunicación unidireccional y establece el miembro ImportInterface de la estructura WDF_QUERY_INTERFACE_CONFIG que describe la interfaz en FALSE, la función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest es opcional. Cuando otro controlador llama a WdfFdoQueryForInterface, el marco copia los valores de interfaz definidos por el controlador en la estructura INTERFACE del controlador solicitante y, a continuación, llama a la función de devolución de llamada. Para la comunicación unidireccional, solo debe proporcionar una función de devolución de llamada si desea que el controlador examine y, posiblemente, modifique, los valores de interfaz antes de que el marco los devuelva al controlador solicitante.

El controlador debe proporcionar una función de devolución de llamada de eventos EvtDeviceProcessQueryInterfaceRequest si el controlador define una interfaz que admite la comunicación bidireccional (y establece el miembro ImportInterface de la estructura WDF_QUERY_INTERFACE_CONFIG en TRUE). La función de devolución de llamada es necesaria porque, si ImportInterface es TRUE y otro controlador llama a WdfFdoQueryForInterface, el marco no copia la interfaz definida por el controlador en la estructura de interfaz del controlador solicitante. En su lugar, la función de devolución de llamada debe actualizar la estructura de interfaz del controlador solicitante.

La función de devolución de llamada puede modificar la interfaz. En concreto, puede:

Cambie cualquier valor de cualquier miembro de la interfaz.
Asigne un contexto específico de instancia dinámica modificando el miembro Context de la estructura INTERFACE .

El marco llama a las funciones de devolución de llamada EvtDeviceProcessQueryInterfaceRequest del controlador solo para los GUID que el controlador ha registrado llamando a WdfDeviceAddQueryInterface. Por lo tanto, estas funciones de devolución de llamada no usan el valor devuelto STATUS_NOT_SUPPORTED para notificar GUID inesperados. En su lugar, una función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest debe devolver STATUS_NOT_SUPPORTED cuando determina que, para un caso determinado, no controlará la interfaz. Por ejemplo, en función de los datos que proporciona el controlador solicitante, el controlador podría determinar que un controlador de nivel inferior debe atender la solicitud de interfaz. El STATUS_NOT_SUPPORTED valor devuelto informa al marco de trabajo de que el controlador no está atendiendo la solicitud de interfaz, pero un controlador de nivel inferior podría atenderla.

Para obtener más información sobre las interfaces definidas por el controlador, consulte Uso de interfaces de Driver-Defined.

Ejemplos

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

Por ejemplo, para definir una función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest denominada MyDeviceProcessQueryInterfaceRequest, use el tipo de EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST como se muestra en este ejemplo de código:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

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

_Use_decl_annotations_
NTSTATUS
 MyDeviceProcessQueryInterfaceRequest (
    WDFDEVICE  Device,
    LPGUID  InterfaceType,
    PINTERFACE  ExposedInterface,
    PVOID  ExposedInterfaceSpecificData
    )
  {...}

El tipo de función EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST se define en el archivo de encabezado WdfQueryInterface.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 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de roles de función para controladores KMDF. Para obtener información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.