Função WdfDeviceAddQueryInterface (wdfqueryinterface.h)

Artigo
03/01/2024

[Aplica-se somente ao KMDF]

O método WdfDeviceAddQueryInterface cria uma interface definida pelo driver que outros drivers podem consultar e usar.

Sintaxe

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

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] InterfaceConfig

Um ponteiro para uma estrutura de WDF_QUERY_INTERFACE_CONFIG alocada por driver que descreve a interface .

Retornar valor

WdfDeviceAddQueryInterface retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, esse método pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_INVALID_DEVICE_REQUEST	O método foi chamado no IRQL errado.
STATUS_INVALID_PARAMETER	Um parâmetro de entrada (possivelmente incluindo membros da estrutura WDF_QUERY_INTERFACE_CONFIG) era inválido.
STATUS_INFO_LENGTH_MISMATCH	O tamanho da estrutura WDF_QUERY_INTERFACE_CONFIG estava incorreto.
STATUS_INSUFFICIENT_RESOURCES	Não havia memória suficiente.

Para obter uma lista de valores retornados adicionais, consulte Erros de criação de objeto de estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Um bug do sistema marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Observação

WdfDeviceAddQueryInterface não pode ser chamado para um dispositivo de controle.

Drivers que criam interfaces definidas pelo driver normalmente chamam WdfDeviceAddQueryInterface de dentro de uma função de retorno de chamada EvtDriverDeviceAdd ou EvtDevicePrepareHardware .

Depois que um driver chama WdfDeviceAddQueryInterface para criar uma interface definida pelo driver, outro driver baseado em estrutura pode acessar a interface chamando WdfFdoQueryForInterface.

Para obter mais informações sobre interfaces definidas pelo driver, consulte Usando interfaces Driver-Defined.

Exemplos

O exemplo de código a seguir é do driver de barramento de exemplo da Torradeira . Este exemplo cria uma interface definida pelo driver que usa a estrutura TOASTER_INTERFACE_STANDARD do exemplo de torradeira.

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	Valor
Plataforma de Destino	Universal
Versão mínima do KMDF	1.0
Cabeçalho	wdfqueryinterface.h (inclua Wdf.h)
Biblioteca	Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.)
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)