EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST funzione di callback (wdfqueryinterface.h)

Articolo
02/27/2024

[Si applica solo a KMDF]

La funzione di callback dell'evento EvtDeviceProcessQueryInterfaceRequest di un driver esamina la richiesta di accesso a un'interfaccia definita dal driver di un altro driver, prima che il framework passi l'interfaccia al driver richiedente.

Sintassi

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

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

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] InterfaceType

Puntatore al GUID che identifica l'interfaccia definita dal driver.

[in, out] ExposedInterface

Puntatore a una struttura INTERFACE che descrive l'interfaccia definita dal driver ed è stato fornito dal driver che richiede l'accesso all'interfaccia.

[in, out] ExposedInterfaceSpecificData

Puntatore a informazioni aggiuntive, facoltative, definite dal driver e specifiche dell'interfaccia. I driver basati su framework specificano questo valore specificando un valore del parametro InterfaceSpecificData diverso da NULL quando si chiama WdfFdoQueryForInterface.

Valore restituito

Se la funzione di callback EvtDeviceProcessQueryInterfaceRequest riceve un GUID supportato e, se la funzione non rileva errori, deve restituire STATUS_SUCCESS o un altro valore di stato per il quale NT_SUCCESS(status) è uguale a TRUE. Il framework continua a passare la richiesta verso il basso dello stack per verificare se anche altri driver supportano l'interfaccia.

La funzione di callback EvtDeviceProcessQueryInterfaceRequest deve restituire STATUS_NOT_SUPPORTED se determina che, per un caso specifico, non funzionerà l'interfaccia. Il framework continua a passare la richiesta allo stack per verificare se un altro driver supporta l'interfaccia. Per altre informazioni su questa situazione, vedere la sezione Osservazioni seguente.

Se la funzione di callback rileva un errore, deve restituire un valore di stato per il quale NT_SUCCESS(status) è uguale a FALSE. Il framework non riesce la richiesta dell'altro driver per l'interfaccia e non passa la richiesta allo stack.

Commenti

I driver basati su framework registrano una funzione di callback degli eventi EvtDeviceProcessQueryInterfaceRequest chiamando WdfDeviceAddQueryInterface.

Se l'interfaccia definita dal driver supporta solo la comunicazione unidirezionale e imposta il membro ImportInterface della struttura WDF_QUERY_INTERFACE_CONFIG che descrive l'interfaccia su FALSE, la funzione di callback EvtDeviceProcessQueryInterfaceRequest è facoltativa. Quando un altro driver chiama WdfFdoQueryForInterface, il framework copia i valori di interfaccia definiti dal driver nella struttura INTERFACE del driver richiedente e quindi chiama la funzione di callback. Per la comunicazione unidirezionale, è necessario fornire una funzione di callback solo se si vuole che il driver esamini ed eventualmente modifichi i valori di interfaccia prima che il framework li restituisca al driver richiedente.

Il driver deve fornire una funzione di callback degli eventi EvtDeviceProcessQueryInterfaceRequest se il driver definisce un'interfaccia che supporta la comunicazione bidirezionale e imposta il membro ImportInterface della struttura WDF_QUERY_INTERFACE_CONFIG su TRUE. La funzione di callback è necessaria perché, se ImportInterface è TRUE e un altro driver chiama WdfFdoQueryForInterface, il framework non copia l'interfaccia definita dal driver nella struttura di interfaccia del driver richiedente. La funzione di callback deve invece aggiornare la struttura dell'interfaccia del driver richiedente.

La funzione di callback può modificare l'interfaccia. In particolare, può:

Modificare qualsiasi valore in qualsiasi membro dell'interfaccia.
Allocare un contesto specifico dell'istanza dinamica modificando il membro Context della struttura INTERFACE .

Il framework chiama le funzioni di callback EvtDeviceProcessQueryInterfaceRequest del driver solo per i GUID registrati chiamando WdfDeviceAddQueryInterface. Pertanto, queste funzioni di callback non usano il valore restituito STATUS_NOT_SUPPORTED per segnalare GUID imprevisti. Al contrario, una funzione di callback EvtDeviceProcessQueryInterfaceRequest deve restituire STATUS_NOT_SUPPORTED quando determina che, per un caso specifico, non gestirà l'interfaccia. Ad esempio, in base ai dati forniti dal driver richiedente, il driver potrebbe determinare che un driver di livello inferiore deve eseguire la richiesta di interfaccia. Il valore restituito STATUS_NOT_SUPPORTED indica al framework che il driver non sta servendo la richiesta di interfaccia, ma un driver di livello inferiore potrebbe eseguirne il servizio.

Per altre informazioni sulle interfacce definite dal driver, vedere Using Driver-Defined Interfaces.For more information about driver-defined interfaces, see Using Driver-Defined Interfaces.

Esempio

Per definire una funzione di callback EvtDeviceProcessQueryInterfaceRequest , è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione di callback EvtDeviceProcessQueryInterfaceRequest denominata MyDeviceProcessQueryInterfaceRequest, usare il tipo di EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST come illustrato nell'esempio di codice seguente:

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Implementare quindi la funzione di callback come indicato di seguito:

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

Il tipo di funzione EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST è definito nel file di intestazione WdfQueryInterface.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver KMDF. Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.