struttura WDF_QUERY_INTERFACE_CONFIG (wdfqueryinterface.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

La struttura WDF_QUERY_INTERFACE_CONFIG descrive un'interfaccia definita dal driver.

Sintassi

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;

Members

Size

Dimensione, in byte, della struttura.

Interface

Puntatore a una struttura INTERFACE che descrive l'interfaccia definita dal driver.

InterfaceType

Puntatore al GUID che identifica l'interfaccia.

Nota

Quando si introduce una nuova versione di un'interfaccia esistente, creare un nuovo GUID anziché rivedere i campi Dimensioni o Versione della struttura INTERFACE . Per altre info, vedi Uso delle interfacce Driver-Defined.

SendQueryToParentStack

Se TRUE e se il driver specifica un oggetto dispositivo che rappresenta un oggetto dispositivo fisico (PDO) quando chiama WdfDeviceAddQueryInterface, il framework invia richieste per l'interfaccia all'inizio dello stack di driver del dispositivo padre. Se questo membro è FALSE o se l'oggetto dispositivo non rappresenta un PDO, il framework non invia richieste allo stack del dispositivo padre. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

EvtDeviceProcessQueryInterfaceRequest

Puntatore alla funzione di callback dell'evento EvtDeviceProcessQueryInterfaceRequest del driver, che viene chiamata quando un altro driver richiede l'interfaccia.

ImportInterface

Se TRUE, l'interfaccia supporta la comunicazione bidirezionale tra il driver e i driver che richiedono l'interfaccia.

Se questo membro è FALSE, l'interfaccia supporta la comunicazione unidirezionale dal driver ai driver che richiedono l'interfaccia.

Commenti

La struttura WDF_QUERY_INTERFACE_CONFIG viene usata come input per il metodo WdfDeviceAddQueryInterface .

Per ogni interfaccia definita dal driver esportata dal driver, è necessario allocare una struttura WDF_QUERY_INTERFACE_CONFIG che rappresenta l'interfaccia. Altri driver possono richiedere l'accesso all'interfaccia chiamando WdfFdoQueryForInterface.

Se si vuole che l'interfaccia supporti la comunicazione bidirezionale tra il driver richiedente e il driver, impostare il membro ImportInterface su TRUE. Se ImportInterface è TRUE, la struttura fornita dal driver richiedente può contenere dati che il driver può leggere. In questo caso:

È necessaria la funzione di callback EvtDeviceProcessQueryInterfaceRequest e deve inizializzare la struttura di interfaccia fornita dal driver richiedente.
Poiché la funzione di callback EvtDeviceProcessQueryInterfaceRequest fornisce l'interfaccia al driver richiedente, il membro Interface di WDF_QUERY_INTERFACE_CONFIG può essere NULL. Se si specifica un puntatore non NULL , il framework verifica che le dimensioni e i valori di versione forniti dal driver richiedente siano uguali o maggiori dei valori nella struttura INTERFACE registrata. Se uno di questi valori è più piccolo, il framework rifiuta la richiesta. Se non si specifica un valore per Interface, la funzione di callback EvtDeviceProcessQueryInterfaceRequest deve verificare tali valori.

Se si vuole che l'interfaccia supporti solo la comunicazione unidirezionale dal driver al driver richiedente, impostare ImportInterface su FALSE. La struttura di interfaccia fornita dal driver richiedente può ricevere solo i dati forniti dal driver. In questo caso:

La funzione di callback EvtDeviceProcessQueryInterfaceRequest è facoltativa.
Il membro Interface non può essere NULL. Il framework verifica che il GUID, le dimensioni e i valori della versione forniti dal driver richiedente corrispondano a quelli forniti e il framework rifiuta la richiesta se i valori non corrispondono. Se i valori sono validi, il framework inizializza la struttura di interfaccia fornita dal driver richiedente usando i valori forniti per Interface.

Inoltre, il membro Interface può essere NULL se il valore del membro SendQueryToParentStack è TRUE.

Se il membro Interface è diverso da NULL, il framework copia il valore nello spazio di archiviazione interno. Pertanto, il driver può allocare la struttura INTERFACE nello spazio di archiviazione temporaneo locale.

Quando il driver chiama WdfDeviceAddQueryInterface, può associare l'interfaccia a un oggetto dispositivo framework che rappresenta un oggetto dispositivo funzionale (FDO) o un oggetto dispositivo fisico (PDO). Se il driver associa l'interfaccia a un PDO, può impostare il membro SendQueryToParentStack della struttura WDF_QUERY_INTERFACE_CONFIG su TRUE. Quando il framework intercetta una richiesta per l'interfaccia, controlla il membro SendQueryToParentStack e, se è impostato su TRUE, il framework invia la richiesta all'inizio dello stack di driver dell'elemento padre del PDO. Di conseguenza, la richiesta si sposta verso il basso di due stack di driver: prima, lo stack che contiene il driver che richiede l'interfaccia e, in secondo luogo, lo stack dell'elemento padre del dispositivo dell'interfaccia.

Il framework fornisce due metodi di riferimento/dereferenziazione che è possibile usare con le interfacce specificando i relativi indirizzi per i membri InterfaceReference e InterfaceDereference della struttura INTERFACE . Per altre informazioni su questi metodi, vedere WdfDeviceInterfaceReferenceNoOp e WdfDeviceInterfaceDereferenceNoOp.

I driver devono inizializzare questa struttura chiamando WDF_QUERY_INTERFACE_CONFIG_INIT.

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.