EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST funzione di callback (wdfqueryinterface.h)

Articolo
07/16/2024

[Si applica solo a KMDF]

La funzione di callback di un driver EvtDeviceProcessQueryInterfaceRequest 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 e fornita 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 nullNULLInterfaceSpecificData valore del parametro quando si chiama WdfFdoQueryForInterface.

Valore restituito

Se l'EvtDeviceProcessQueryInterfaceRequest funzione di callback 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(stato) è 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 EvtDeviceProcessQueryInterfaceRequest funzione di callback deve restituire STATUS_NOT_SUPPORTED se determina che, per un caso specifico, non verrà usata l'interfaccia. Il framework continua a passare la richiesta verso il basso dello 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(stato) è uguale a FALSE. Il framework non riesce la richiesta dell'altro driver per l'interfaccia e non passa la richiesta allo stack.

Osservazioni

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 di WDF_QUERY_INTERFACE_CONFIG che descrive l'interfaccia per FALSE, l'EvtDeviceProcessQueryInterfaceRequest funzione di callback è 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 dell'interfaccia prima che il framework li restituisca al driver richiedente.

Il driver deve fornire un EvtDeviceProcessQueryInterfaceRequest funzione di callback degli eventi 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 dell'interfaccia del driver richiedente. Al contrario, la funzione di callback deve 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 di .

Il framework chiama le funzioni di callback del driver EvtDeviceProcessQueryInterfaceRequest solo per i GUID registrati dal driver chiamando WdfDeviceAddQueryInterface. Pertanto, queste funzioni di callback non usano il valore restituito STATUS_NOT_SUPPORTED per segnalare GUID imprevisti. Al contrario, un EvtDeviceProcessQueryInterfaceRequest funzione di callback 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 informa il 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.

Esempi

Per definire un EvtDeviceProcessQueryInterfaceRequest funzione di callback, è prima necessario 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 usando i tipi di funzione di callback consente di l'analisi del codice per i driver, del driver statico (SDV) e altri strumenti di verifica rilevano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire un EvtDeviceProcessQueryInterfaceRequest funzione di callback 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 segue:

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

Il tipo di funzione EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST viene 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 assicura 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 i tipi di ruolo della funzione per i driver KMDF. Per informazioni su Use_decl_annotations, vedere l'annotazione del comportamento della funzione.