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

[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 interface estrutura 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, específicas da interface. Os drivers baseados em estrutura especificam esse valor fornecendo um valor de parâmetroNULL nãoInterfaceSpecificData ao chamar WdfFdoQueryForInterface.

Valor de retorno

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 de status para o qual NT_SUCCESS(status) é igual a VERDADEIRO. 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 de 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.

Observações

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

Se a interface definida pelo driver dá suporte apenas à comunicação unidirecional e define o ImportInterface membro da estrutura WDF_QUERY_INTERFACE_CONFIG que descreve a interface para FALSE, a função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest é opcional. Quando outro driver chama WdfFdoQueryForInterface, a estrutura copia os valores de interface definidos pelo driver para a estrutura interface do 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 da interface antes que a estrutura as retorne ao driver solicitante.

O driver deve 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 para true). A função de retorno de chamada é necessária porque, se ImportInterface for true e outras chamadas de driver WdfFdoQueryForInterface, a estrutura não copiará a interface definida pelo driver na 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 de Contexto da estrutura interface do .

A estrutura chama as funções de retorno de chamada EvtDeviceProcessQueryInterfaceRequest do driver apenas 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, ela 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 STATUS_NOT_SUPPORTED informa à estrutura que o driver não está atendendo à solicitação de interface, mas um driver de nível inferior pode ausiná-la.

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

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 encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada EvtDeviceProcessQueryInterfaceRequest denominada 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 sua 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.

Requisitos

Requisito	Valor
da Plataforma de Destino	Universal
versão mínima do KMDF	1.0
cabeçalho	wdfqueryinterface.h (inclua Wdf.h)
IRQL	PASSIVE_LEVEL

Consulte também

de INTERFACE do

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface