EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST função de retorno de chamada (wdfqueryinterface.h)

Artigo
08/08/2023

[Aplica-se somente ao KMDF]

A função de retorno de chamada de evento EvtDeviceProcessQueryInterfaceRequest de um driver examina a solicitação de acesso de outro driver a uma interface definida pelo driver, antes que a estrutura passe a interface para o driver solicitante.

Sintaxe

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

NTSTATUS EvtWdfDeviceProcessQueryInterfaceRequest(
  [in]      WDFDEVICE Device,
  [in]      LPGUID InterfaceType,
  [in, out] PINTERFACE ExposedInterface,
  [in, out] PVOID ExposedInterfaceSpecificData
)
{...}

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] InterfaceType

Um ponteiro para o GUID que identifica a interface definida pelo driver.

[in, out] ExposedInterface

Um ponteiro para uma estrutura interface que descreve a interface definida pelo driver e foi fornecido pelo driver que está solicitando acesso à interface.

[in, out] ExposedInterfaceSpecificData

Um ponteiro para informações adicionais, opcionais, definidas pelo driver e específicas da interface. Os drivers baseados em estrutura especificam esse valor fornecendo um valor de parâmetro Não NULLInterfaceSpecificData ao chamar WdfFdoQueryForInterface.

Retornar valor

Se a função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest receber um GUID compatível e, se a função não encontrar erros, ela deverá retornar STATUS_SUCCESS ou outro valor status para o qual NT_SUCCESS(status) é igual a TRUE. A estrutura continua passando a solicitação para baixo na pilha para ver se drivers adicionais também dão suporte à interface.

A função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest deverá retornar STATUS_NOT_SUPPORTED se determinar que, para um caso específico, não atenderá à interface. A estrutura continua passando a solicitação para baixo na pilha para ver se outro driver dá suporte à interface. Para obter mais informações sobre essa situação, consulte a seção Comentários a seguir.

Se a função de retorno de chamada encontrar um erro, ela deverá retornar um valor status para o qual NT_SUCCESS(status) é igual a FALSE. A estrutura falha na solicitação do outro driver para a interface e não passa a solicitação para baixo na pilha.

Comentários

Os drivers baseados em estrutura registram uma função de retorno de chamada de evento EvtDeviceProcessQueryInterfaceRequest chamando WdfDeviceAddQueryInterface.

Se a interface definida pelo driver der suporte apenas à comunicação unidirecional e definir o membro ImportInterface da estrutura WDF_QUERY_INTERFACE_CONFIG que descreve a interface como FALSE, a função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest será opcional. Quando outro driver chama WdfFdoQueryForInterface, a estrutura copia os valores de interface definidos pelo driver para a estrutura interface do driver solicitante e chama a função de retorno de chamada. Para comunicação unidirecional, você precisará fornecer uma função de retorno de chamada somente se quiser que o driver examine e, possivelmente, modifique os valores de interface antes que a estrutura os retorne ao driver solicitante.

O driver deverá fornecer uma função de retorno de chamada de evento EvtDeviceProcessQueryInterfaceRequest se o driver definir uma interface que dê suporte à comunicação bidirecional (e definir o membro ImportInterface da estrutura WDF_QUERY_INTERFACE_CONFIG como TRUE). A função de retorno de chamada é necessária porque, se ImportInterface for TRUE e outro driver chamar WdfFdoQueryForInterface, a estrutura não copiará a interface definida pelo driver para a estrutura de interface do driver solicitante. Em vez disso, a função de retorno de chamada deve atualizar a estrutura de interface do driver solicitante.

A função de retorno de chamada pode modificar a interface. Em particular, ele pode:

Altere qualquer valor em qualquer membro da interface.
Aloque um contexto específico de instância dinâmica modificando o membro contextual da estrutura interface .

A estrutura chama as funções de retorno de chamada EvtDeviceProcessQueryInterfaceRequest do driver somente para GUIDs que o driver registrou chamando WdfDeviceAddQueryInterface. Portanto, essas funções de retorno de chamada não usam o valor retornado STATUS_NOT_SUPPORTED para relatar GUIDs inesperados. Em vez disso, uma função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest deve retornar STATUS_NOT_SUPPORTED quando determinar que, para um caso específico, não manipulará a interface. Por exemplo, com base nos dados que o driver solicitante fornece, o driver pode determinar que um driver de nível inferior deve atender à solicitação de interface. O valor retornado do STATUS_NOT_SUPPORTED informa à estrutura que o driver não está atendendo à solicitação de interface, mas um driver de nível inferior pode atender a ela.

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

Exemplos

Para definir uma função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest , primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest chamada MyDeviceProcessQueryInterfaceRequest, use o tipo EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST conforme mostrado neste exemplo de código:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Em seguida, implemente a função de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
NTSTATUS
 MyDeviceProcessQueryInterfaceRequest (
    WDFDEVICE  Device,
    LPGUID  InterfaceType,
    PINTERFACE  ExposedInterface,
    PVOID  ExposedInterfaceSpecificData
    )
  {...}

O tipo de função EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST é definido no arquivo de cabeçalho WdfQueryInterface.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers KMDF. Para obter informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.