Функция WdfDeviceAddQueryInterface (wdfqueryinterface.h)

Статья
03/05/2024

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

Метод WdfDeviceAddQueryInterface создает интерфейс, определяемый драйвером, который могут запрашивать и использовать другие драйверы.

Синтаксис

NTSTATUS WdfDeviceAddQueryInterface(
  [in] WDFDEVICE                   Device,
  [in] PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] InterfaceConfig

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

Возвращаемое значение

WdfDeviceAddQueryInterface возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_DEVICE_REQUEST	Метод был вызван в неправильном IRQL.
STATUS_INVALID_PARAMETER	Входной параметр (возможно, включающий элементы структуры WDF_QUERY_INTERFACE_CONFIG) был недопустимым.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_QUERY_INTERFACE_CONFIG.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

Список дополнительных возвращаемых значений см. в разделе Ошибки создания объектов платформы.

Этот метод также может возвращать другие значения NTSTATUS.

Системная ошибка проверка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

После того как драйвер вызывает WdfDeviceAddQueryInterface для создания определяемого драйвером интерфейса, другой драйвер на основе платформы может получить доступ к интерфейсу, вызвав WdfFdoQueryForInterface.

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

Примеры

Следующий пример кода получен из примера драйвера автобуса Тостер . В этом примере создается интерфейс, определяемый драйвером, который использует структуру TOASTER_INTERFACE_STANDARD примера тостера.

typedef struct _TOASTER_INTERFACE_STANDARD {
 INTERFACE  InterfaceHeader;
  PTOASTER_GET_CRISPINESS_LEVEL  GetCrispinessLevel;
  PTOASTER_SET_CRISPINESS_LEVEL  SetCrispinessLevel;
  PTOASTER_IS_CHILD_PROTECTED  IsSafetyLockEnabled;
} TOASTER_INTERFACE_STANDARD, *PTOASTER_INTERFACE_STANDARD;

TOASTER_INTERFACE_STANDARD  ToasterInterface;
WDF_QUERY_INTERFACE_CONFIG  qiConfig;

//
// Initialize the ToasterInterface structure.
//
RtlZeroMemory(
              &ToasterInterface,
              sizeof(ToasterInterface)
              );

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID)hChild;

ToasterInterface.InterfaceHeader.InterfaceReference =
        WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
        WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

//
// Initialize the qiConfig structure.
//
WDF_QUERY_INTERFACE_CONFIG_INIT(
                                &qiConfig,
                                (PINTERFACE)&ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL
                                );

//
// Create the interface.
//
status = WdfDeviceAddQueryInterface(
                                    hChild,
                                    &qiConfig
                                    );
if (!NT_SUCCESS(status)) {
    return status;
}

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Верхняя часть	wdfqueryinterface.h (включая Wdf.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)