структура WDF_QUERY_INTERFACE_CONFIG (wdfqueryinterface.h)

Статья
08/08/2023

[Относится только к KMDF]

Структура WDF_QUERY_INTERFACE_CONFIG описывает интерфейс, определяемый драйвером.

Синтаксис

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;

Члены

Size

Размер данной структуры (в байтах).

Interface

Указатель на структуру INTERFACE , описывающую интерфейс, определенный драйвером.

InterfaceType

Указатель на GUID, который идентифицирует интерфейс.

Примечание

При вводе новой версии существующего интерфейса создайте новый GUID вместо изменения полей Размер или Версия структуры ИНТЕРФЕЙСА . Дополнительные сведения см. в разделе Использование интерфейсов Driver-Defined.

SendQueryToParentStack

Если задано значение TRUE и драйвер указывает объект устройства, представляющий объект физического устройства (PDO) при вызове WdfDeviceAddQueryInterface, платформа отправляет запросы на интерфейс в верхнюю часть стека драйверов родительского устройства. Если этот элемент имеет значение FALSE или объект устройства не представляет PDO, платформа не отправляет запросы в стек родительского устройства. Дополнительные сведения см. в разделе "Примечания".

EvtDeviceProcessQueryInterfaceRequest

Указатель на функцию обратного вызова события EvtDeviceProcessQueryInterfaceRequest вашего драйвера, которая вызывается, когда другой драйвер запрашивает интерфейс.

ImportInterface

Если задано значение TRUE, интерфейс поддерживает двусторонний обмен данными между драйвером и драйверами, запрашивающими интерфейс.

Если этот элемент имеет значение FALSE, интерфейс поддерживает односторонний обмен данными между драйвером и драйверами, которые запрашивают интерфейс.

Для каждого интерфейса, определенного драйвером, который экспортирует драйвер, необходимо выделить WDF_QUERY_INTERFACE_CONFIG структуру, представляющую интерфейс . Другие драйверы могут запрашивать доступ к интерфейсу, вызывая WdfFdoQueryForInterface.

Если вы хотите, чтобы интерфейс поддерживал двусторонний обмен данными между запрашивающим драйвером и драйвером, задайте для элемента ImportInterface значение TRUE. Если параметр ImportInterface имеет значение TRUE, структура, предоставляемая запрашивающим драйвером, может содержать данные, которые драйвер может считывать. В данном случае:

Функция обратного вызова EvtDeviceProcessQueryInterfaceRequest является обязательной, и она должна инициализировать структуру интерфейса, которую предоставляет запрашивающий драйвер.
Так как функция обратного вызова EvtDeviceProcessQueryInterfaceRequest предоставляет интерфейс для запрашивающего драйвера, член интерфейсаWDF_QUERY_INTERFACE_CONFIG может иметь значение NULL. Если указан указатель, отличный от NULL , платформа проверяет, что значения размера и версии, предоставляемые запрашивающим драйвером, равны или больше значений в зарегистрированной структуре INTERFACE . Если одно из этих значений меньше, платформа отклоняет запрос. Если значение для interface не указано, функция обратного вызова EvtDeviceProcessQueryInterfaceRequest должна проверить эти значения.

Если вы хотите, чтобы интерфейс поддерживал только односторонний обмен данными между драйвером и запрашивающим драйвером, установите для свойства ImportInterfaceзначение FALSE. Структура интерфейса, которую предоставляет запрашивающий драйвер, может получать только данные, которые предоставляет драйвер. В данном случае:

Функция обратного вызова EvtDeviceProcessQueryInterfaceRequest является необязательной.
Член интерфейса не может иметь значение NULL. Платформа проверяет, совпадают ли значения GUID, размера и версии, предоставляемые запрашивающим драйвером, указанным вами, и отклоняет запрос, если значения не совпадают. Если значения допустимы, платформа инициализирует структуру интерфейса, которую предоставляет запрашивающий драйвер, используя значения, предоставленные для interface.

Кроме того, член интерфейса может иметь значение NULL , если значение элемента SendQueryToParentStack равно TRUE.

Если член интерфейса не равен NULL, платформа копирует значение во внутреннее дисковое пространство. Таким образом, драйвер может выделить структуру INTERFACE в локальном временном дисковом пространстве.

Когда драйвер вызывает WdfDeviceAddQueryInterface, он может связать интерфейс с объектом устройства платформы, который представляет либо объект функционального устройства (FDO), либо физический объект устройства (PDO). Если драйвер связывает интерфейс с PDO, он может задать для элемента SendQueryToParentStack структуры WDF_QUERY_INTERFACE_CONFIG значение TRUE. Когда платформа перехватывает запрос к интерфейсу, она проверяет член SendQueryToParentStack и, если для него задано значение TRUE, платформа отправляет запрос в верхнюю часть стека драйверов родительского PDO. В результате запрос перемещается вниз по двум стекам драйверов: во-первых, стек, содержащий драйвер, запрашивающий интерфейс, и, во-вторых, стек родительского устройства интерфейса.

Платформа предоставляет два метода ссылок и разыменования, которые можно использовать с интерфейсами, указав их адреса для элементов InterfaceReference и InterfaceDereference структуры INTERFACE . Дополнительные сведения об этих методах см. в разделах WdfDeviceInterfaceReferenceNoOp и WdfDeviceInterfaceDereferenceNoOp.

Драйверы должны инициализировать эту структуру, вызвав WDF_QUERY_INTERFACE_CONFIG_INIT.

Дополнительные сведения об интерфейсах, определяемых драйвером, см. в разделе Использование интерфейсов Driver-Defined.