estrutura WDF_QUERY_INTERFACE_CONFIG (wdfqueryinterface.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

A estrutura WDF_QUERY_INTERFACE_CONFIG descreve uma interface definida pelo driver.

Sintaxe

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;

Membros

Size

O tamanho, em bytes, dessa estrutura.

Interface

Um ponteiro para uma estrutura interface que descreve a interface definida pelo driver.

InterfaceType

Um ponteiro para o GUID que identifica a interface.

Observação

Ao introduzir uma nova versão de uma interface existente, crie um novo GUID em vez de revisar os campos Tamanho ou Versão da estrutura interface . Para obter mais informações, consulte Usando interfaces de Driver-Defined.

SendQueryToParentStack

Se TRUE e se o driver especificar um objeto de dispositivo que representa um objeto de dispositivo físico (PDO) quando ele chama WdfDeviceAddQueryInterface, a estrutura envia solicitações para a interface para a parte superior da pilha de driver do dispositivo pai. Se esse membro for FALSE ou se o objeto do dispositivo não representar um PDO, a estrutura não enviará solicitações para a pilha do dispositivo pai. Para obter mais informações, consulte a seção Comentários a seguir.

EvtDeviceProcessQueryInterfaceRequest

Um ponteiro para a função de retorno de chamada de evento EvtDeviceProcessQueryInterfaceRequest do driver, que é chamada quando outro driver solicita a interface.

ImportInterface

Se TRUE, a interface dá suporte à comunicação bidirecional entre o driver e os drivers que solicitam a interface.

Se esse membro for FALSE, a interface oferecerá suporte à comunicação unidirecional do driver com os drivers que solicitam a interface.

Comentários

A estrutura WDF_QUERY_INTERFACE_CONFIG é usada como entrada para o método WdfDeviceAddQueryInterface .

Para cada interface definida pelo driver exportada pelo driver, você deve alocar uma estrutura WDF_QUERY_INTERFACE_CONFIG que represente a interface. Outros drivers podem solicitar acesso à interface chamando WdfFdoQueryForInterface.

Se você quiser que sua interface dê suporte à comunicação bidirecional entre o driver solicitante e o driver, defina o membro ImportInterface como TRUE. Se ImportInterface for TRUE, a estrutura fornecida pelo driver solicitante poderá conter dados que o driver pode ler. Nesse caso:

A função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest é necessária e deve inicializar a estrutura de interface fornecida pelo driver solicitante.
Como a função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest fornece a interface para o driver solicitante, o membro interface do WDF_QUERY_INTERFACE_CONFIG pode ser NULL. Se você fornecer um ponteiro não NULL , a estrutura verificará se os valores de tamanho e versão fornecidos pelo driver solicitante são iguais ou maiores que os valores em sua estrutura de INTERFACE registrada. Se um desses valores for menor, a estrutura rejeitará a solicitação. Se você não fornecer um valor para Interface, sua função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest deverá verificar esses valores.

Se você quiser que sua interface dê suporte apenas à comunicação unidirecional do driver com o driver solicitante, definir ImportInterface será FALSE. A estrutura de interface fornecida pelo driver solicitante pode receber apenas os dados que o driver fornece. Nesse caso:

A função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest é opcional.
O membro interface não pode ser NULL. A estrutura verifica se os valores GUID, tamanho e versão fornecidos pelo driver solicitante correspondem aos fornecidos e a estrutura rejeita a solicitação se os valores não corresponderem. Se os valores forem válidos, a estrutura inicializará a estrutura de interface que o driver solicitante fornece usando os valores fornecidos para Interface.

Além disso, o membro Interface poderá ser NULL se o valor do membro SendQueryToParentStack for TRUE.

Se o membro interface não for NULL, a estrutura copiará o valor para o espaço de armazenamento interno. Portanto, o driver pode alocar a estrutura interface no espaço de armazenamento local e temporário.

Quando o driver chama WdfDeviceAddQueryInterface, ele pode associar a interface a um objeto de dispositivo de estrutura que representa um FDO (objeto de dispositivo funcional) ou um PDO (objeto de dispositivo físico). Se o driver associar a interface a um PDO, ele poderá definir o membro SendQueryToParentStack da estrutura WDF_QUERY_INTERFACE_CONFIG como TRUE. Quando a estrutura intercepta uma solicitação para a interface, ela verifica o membro SendQueryToParentStack e, se estiver definida como TRUE, a estrutura envia a solicitação para a parte superior da pilha de driver do pai do PDO. Como resultado, a solicitação percorre duas pilhas de driver: primeiro, a pilha que contém o driver que está solicitando a interface e, em segundo lugar, a pilha do pai do dispositivo da interface.

A estrutura fornece dois métodos de referência/desreferência que você pode usar com suas interfaces especificando seus endereços para os membros InterfaceReference e InterfaceDereference da estrutura interface . Para obter mais informações sobre esses métodos, consulte WdfDeviceInterfaceReferenceNoOp e WdfDeviceInterfaceDereferenceNoOp.

Os drivers devem inicializar essa estrutura chamando WDF_QUERY_INTERFACE_CONFIG_INIT.

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