estructura WDF_QUERY_INTERFACE_CONFIG (wdfqueryinterface.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

La estructura WDF_QUERY_INTERFACE_CONFIG describe una interfaz definida por el controlador.

Sintaxis

typedef struct _WDF_QUERY_INTERFACE_CONFIG {
  ULONG                                          Size;
  PINTERFACE                                     Interface;
  const GUID                                     *InterfaceType;
  BOOLEAN                                        SendQueryToParentStack;
  PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
  BOOLEAN                                        ImportInterface;
} WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;

Miembros

Size

Tamaño, en bytes, de esta estructura.

Interface

Puntero a una estructura INTERFACE que describe la interfaz definida por el controlador.

InterfaceType

Puntero al GUID que identifica la interfaz.

Nota

Al introducir una nueva versión de una interfaz existente, cree un NUEVO GUID en lugar de revisar los campos Tamaño o Versión de la estructura INTERFACE . Para obtener más información, consulta Uso de interfaces de Driver-Defined.

SendQueryToParentStack

Si es TRUE y si el controlador especifica un objeto de dispositivo que representa un objeto de dispositivo físico (PDO) cuando llama a WdfDeviceAddQueryInterface, el marco envía solicitudes para la interfaz a la parte superior de la pila de controladores del dispositivo primario. Si este miembro es FALSE o si el objeto de dispositivo no representa un PDO, el marco no envía solicitudes a la pila del dispositivo primario. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

EvtDeviceProcessQueryInterfaceRequest

Puntero a la función de devolución de llamada de eventos EvtDeviceProcessQueryInterfaceRequest del controlador, a la que se llama cuando otro controlador solicita la interfaz.

ImportInterface

Si es TRUE, la interfaz admite la comunicación bidireccional entre el controlador y los controladores que solicitan la interfaz.

Si este miembro es FALSE, la interfaz admite la comunicación unidireccional desde el controlador a los controladores que solicitan la interfaz.

Comentarios

La estructura WDF_QUERY_INTERFACE_CONFIG se usa como entrada para el método WdfDeviceAddQueryInterface .

Para cada interfaz definida por el controlador que exporta el controlador, debe asignar una estructura de WDF_QUERY_INTERFACE_CONFIG que represente la interfaz. Otros controladores pueden solicitar acceso a la interfaz llamando a WdfFdoQueryForInterface.

Si desea que la interfaz admita la comunicación bidireccional entre el controlador solicitante y el controlador, establezca el miembro ImportInterface en TRUE. Si ImportInterface es TRUE, la estructura proporcionada por el controlador solicitante puede contener datos que el controlador puede leer. En este caso:

Se requiere la función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest y debe inicializar la estructura de interfaz que proporciona el controlador solicitante.
Dado que la función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest proporciona la interfaz al controlador solicitante, el miembro Interface de WDF_QUERY_INTERFACE_CONFIG puede ser NULL. Si proporciona un puntero distinto de NULL , el marco comprueba que los valores de tamaño y versión que proporciona el controlador solicitante son iguales o mayores que los valores de la estructura INTERFACE registrada. Si alguno de estos valores es menor, el marco rechaza la solicitud. Si no proporciona un valor para Interface, la función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest debe comprobar esos valores.

Si desea que la interfaz admita solo la comunicación unidireccional desde el controlador al controlador solicitante, establezca ImportInterface en FALSE. La estructura de interfaz que proporciona el controlador solicitante solo puede recibir los datos que proporciona el controlador. En este caso:

La función de devolución de llamada EvtDeviceProcessQueryInterfaceRequest es opcional.
El miembro Interface no puede ser NULL. El marco comprueba que el GUID, el tamaño y los valores de versión que proporciona el controlador solicitante coinciden con los proporcionados y el marco rechaza la solicitud si los valores no coinciden. Si los valores son válidos, el marco inicializa la estructura de interfaz que proporciona el controlador solicitante mediante los valores proporcionados para Interface.

Además, el miembro Interface puede ser NULL si el valor del miembro SendQueryToParentStack es TRUE.

Si el miembro Interface no es NULL, el marco copia el valor en el espacio de almacenamiento interno. Por lo tanto, el controlador puede asignar la estructura INTERFACE en el espacio de almacenamiento local y temporal.

Cuando el controlador llama a WdfDeviceAddQueryInterface, puede asociar la interfaz con un objeto de dispositivo de marco que representa un objeto de dispositivo funcional (FDO) o un objeto de dispositivo físico (PDO). Si el controlador asocia la interfaz a un PDO, puede establecer el miembro SendQueryToParentStack de la estructura WDF_QUERY_INTERFACE_CONFIG en TRUE. Cuando el marco intercepta una solicitud de la interfaz, comprueba el miembro SendQueryToParentStack y, si se establece en TRUE, el marco envía la solicitud a la parte superior de la pila de controladores del elemento primario del PDO. Como resultado, la solicitud desplaza dos pilas de controladores: en primer lugar, la pila que contiene el controlador que solicita la interfaz y, en segundo lugar, la pila del elemento primario del dispositivo de la interfaz.

El marco proporciona dos métodos de referencia y desreferencia que puede usar con las interfaces especificando sus direcciones para los miembros InterfaceReference e InterfaceDereference de la estructura INTERFACE . Para obtener más información sobre estos métodos, vea WdfDeviceInterfaceReferenceNoOp y WdfDeviceInterfaceDereferenceNoOp.

Los controladores deben inicializar esta estructura llamando a WDF_QUERY_INTERFACE_CONFIG_INIT.

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