Función WdfDeviceAddQueryInterface (wdfqueryinterface.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfDeviceAddQueryInterface crea una interfaz definida por el controlador que otros controladores pueden consultar y usar.

Sintaxis

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

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] InterfaceConfig

Puntero a una estructura de WDF_QUERY_INTERFACE_CONFIG asignada por el controlador que describe la interfaz.

Valor devuelto

WdfDeviceAddQueryInterface devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método podría devolver uno de los siguientes valores:

Código devuelto	Descripción
STATUS_INVALID_DEVICE_REQUEST	Se llamó al método en el IRQL incorrecto.
STATUS_INVALID_PARAMETER	Un parámetro de entrada (posiblemente incluidos los miembros de la estructura WDF_QUERY_INTERFACE_CONFIG) no era válido.
STATUS_INFO_LENGTH_MISMATCH	El tamaño de la estructura WDF_QUERY_INTERFACE_CONFIG era incorrecto.
STATUS_INSUFFICIENT_RESOURCES	No había memoria suficiente.

Para obtener una lista de valores devueltos adicionales, vea Errores de creación de objetos de marco.

Este método también podría devolver otros valores NTSTATUS.

Se produce una comprobación de errores del sistema si el controlador proporciona un identificador de objeto no válido.

Comentarios

Nota

No se puede llamar a WdfDeviceAddQueryInterface para un dispositivo de control.

Los controladores que crean interfaces definidas por controladores suelen llamar a WdfDeviceAddQueryInterface desde una función de devolución de llamada EvtDriverDeviceAdd o EvtDevicePrepareHardware .

Después de que un controlador llame a WdfDeviceAddQueryInterface para crear una interfaz definida por el controlador, otro controlador basado en marco puede acceder a la interfaz llamando a WdfFdoQueryForInterface.

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

Ejemplos

El ejemplo de código siguiente es del controlador de bus de ejemplo toaster . En este ejemplo se crea una interfaz definida por el controlador que usa la estructura TOASTER_INTERFACE_STANDARD del ejemplo del sistema.

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;
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Encabezado	wdfqueryinterface.h (incluir Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)