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

[Solo se aplica a KMDF]

La función de devolución de llamada de eventos EvtDeviceProcessQueryInterfaceRe quest de un controlador examina la solicitud de acceso de otro controlador 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 INTERFAZ estructura 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 proporcionandoun valor de parámetrointerfaceSpecificDatanull al llamar a WdfFdoQueryForInterface.

Valor devuelto

Si el EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada 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(estado) 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.

El EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada 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(estado) es igual a FALSE. El marco produce un error en la solicitud del otro controlador para la interfaz y no pasa la solicitud hacia abajo de la pila.

Observaciones

Los controladores basados en marcos registran una función de devolución de llamada de evento 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 de WDF_QUERY_INTERFACE_CONFIG que describe la interfaz para FALSE, es opcional el EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada. 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 evento EvtDeviceProcessQueryInterfaceRe quest si el controlador define una interfaz que admite la comunicación bidireccional (y establece el miembro ImportInterface de la estructura WDF_QUERY_INTERFACE_CONFIG para 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 la interfaz del controlador solicitante.

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

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

El marco llama al EvtDeviceProcessQueryInterfaceRequest de su controlador funciones de devolución de llamada 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 EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada debe devolver STATUS_NOT_SUPPORTED cuando determine que, para un caso determinado, no controlará la interfaz. Por ejemplo, en función de los datos que proporciona el controlador solicitante, el controlador puede determinar que un controlador de nivel inferior debe atender la solicitud de interfaz. El STATUS_NOT_SUPPORTED valor devuelto informa al marco de trabajo que el controlador no está atendiendo la solicitud de interfaz, pero un controlador de nivel inferior podría atenderlo.

Para obtener más información sobre las interfaces definidas por controladores, consulte Using Driver-Defined Interfaces.

Ejemplos

Para definir un EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada, 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 Análisis de código para controladores, comprobador de controladores estáticos (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 un EvtDeviceProcessQueryInterfaceRequest función de devolución de llamada denominada MyDeviceProcessQueryInterfaceRequest, use el tipo 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 rol de función para controladores kmDF. Para obtener información sobre Use_decl_annotations, vea Anotación del comportamiento de la función.

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.0
encabezado de	wdfqueryinterface.h (incluya Wdf.h)
irQL	PASSIVE_LEVEL

Consulte también

interface de

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface