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

Статья
2025-03-22

[Применимо только к 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.
СТАТУС_НЕДЕЙСТВИТЕЛЬНЫЙ_ПАРАМЕТР	Входной параметр (возможно, включая элементы структуры WDF_QUERY_INTERFACE_CONFIG) был недопустимым.
STATUS_INFO_LENGTH_MISMATCH	Неправильный размер структуры WDF_QUERY_INTERFACE_CONFIG.
СТАТУС_НЕДОСТАТОЧНЫЕ_РЕСУРСЫ	Недостаточно памяти.

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

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

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

Замечания

Примечание.

WdfDeviceAddQueryInterface не может вызываться для устройства управления.

Драйверы, которые создают определяемые драйвером интерфейсы, обычно вызывают WdfDeviceAddQueryInterface из EvtDriverDeviceAdd или функцию обратного вызова EvtDevicePrepareHardware.

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

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

Примеры

В следующем примере кода показан пример драйвера автобуса тостера. В этом примере создается определяемый драйвером интерфейс, использующий TOASTER_INTERFACE_STANDARD структуру 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 (include Wdf.h)
Библиотека	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)