WDF_QUERY_INTERFACE_CONFIG structure (wdfqueryinterface.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La structure WDF_QUERY_INTERFACE_CONFIG décrit une interface définie par le pilote.

Syntaxe

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;

Membres

Size

Taille, en octets, de cette structure.

Interface

Pointeur vers une structure INTERFACE qui décrit l’interface définie par le pilote.

InterfaceType

Pointeur vers le GUID qui identifie l’interface.

Notes

Lors de l’introduction d’une nouvelle version d’une interface existante, créez un GUID au lieu de réviser les champs Taille ou Version de la structure INTERFACE . Pour plus d’informations, consultez Utilisation d’interfaces Driver-Defined.

SendQueryToParentStack

Si la valeur est TRUE et si votre pilote spécifie un objet de périphérique qui représente un objet de périphérique physique (PDO) lorsqu’il appelle WdfDeviceAddQueryInterface, l’infrastructure envoie des demandes pour l’interface en haut de la pile de pilotes du périphérique parent. Si ce membre a la valeur FALSE ou si l’objet d’appareil ne représente pas un PDO, l’infrastructure n’envoie pas de demandes à la pile de l’appareil parent. Pour plus d'informations, consultez la section Notes qui suit.

EvtDeviceProcessQueryInterfaceRequest

Pointeur vers la fonction de rappel d’événement EvtDeviceProcessQueryInterfaceRequest de votre pilote, qui est appelée lorsqu’un autre pilote demande l’interface.

ImportInterface

Si la valeur est TRUE, l’interface prend en charge la communication bidirectionnelle entre votre pilote et les pilotes qui demandent l’interface.

Si ce membre a la valeur FALSE, l’interface prend en charge la communication unidirectionnelle entre votre pilote et les pilotes qui demandent l’interface.

Remarques

La structure WDF_QUERY_INTERFACE_CONFIG est utilisée comme entrée dans la méthode WdfDeviceAddQueryInterface .

Pour chaque interface définie par le pilote que votre pilote exporte, vous devez allouer une structure WDF_QUERY_INTERFACE_CONFIG qui représente l’interface. D’autres pilotes peuvent demander l’accès à l’interface en appelant WdfFdoQueryForInterface.

Si vous souhaitez que votre interface prend en charge la communication bidirectionnelle entre le pilote demandeur et votre pilote, définissez le membre ImportInterface sur TRUE. Si ImportInterface a la valeur TRUE, la structure fournie par le pilote demandeur peut contenir des données que votre pilote peut lire. Dans ce cas :

La fonction de rappel EvtDeviceProcessQueryInterfaceRequest est requise et doit initialiser la structure d’interface que fournit le pilote demandeur.
Étant donné que la fonction de rappel EvtDeviceProcessQueryInterfaceRequest fournit l’interface au pilote demandeur, le membre d’interface de WDF_QUERY_INTERFACE_CONFIG peut être NULL. Si vous fournissez un pointeur non NULL , l’infrastructure vérifie que les valeurs de taille et de version que le pilote demandeur fournit sont égales ou supérieures aux valeurs de votre structure INTERFACE inscrite. Si l’une de ces valeurs est plus petite, l’infrastructure rejette la demande. Si vous ne fournissez pas de valeur pour Interface, votre fonction de rappel EvtDeviceProcessQueryInterfaceRequest doit vérifier ces valeurs.

Si vous souhaitez que votre interface ne prend en charge que la communication unidirectionnelle entre votre pilote et le pilote demandeur, définissez ImportInterface sur FALSE. La structure d’interface que fournit le pilote demandeur peut recevoir uniquement les données que votre pilote fournit. Dans ce cas :

La fonction de rappel EvtDeviceProcessQueryInterfaceRequest est facultative.
Le membre Interface ne peut pas être NULL. L’infrastructure vérifie que les valeurs de GUID, de taille et de version que le pilote demandeur fournit correspondent à celles que vous avez fournies, et l’infrastructure rejette la demande si les valeurs ne correspondent pas. Si les valeurs sont valides, l’infrastructure initialise la structure d’interface que le pilote demandeur fournit à l’aide des valeurs que vous fournissez pour Interface.

En outre, le membre Interface peut être NULL si la valeur du membre SendQueryToParentStack est TRUE.

Si le membre Interface n’est pas NULL, l’infrastructure copie la valeur dans l’espace de stockage interne. Par conséquent, le pilote peut allouer la structure INTERFACE dans un espace de stockage local temporaire.

Lorsque votre pilote appelle WdfDeviceAddQueryInterface, il peut associer l’interface à un objet de périphérique d’infrastructure qui représente un objet d’appareil fonctionnel (FDO) ou un objet de périphérique physique (PDO). Si le pilote associe l’interface à un PDO, il peut définir le membre SendQueryToParentStack de la structure WDF_QUERY_INTERFACE_CONFIG sur TRUE. Lorsque le framework intercepte une demande pour l’interface, il vérifie le membre SendQueryToParentStack et, s’il est défini sur TRUE, l’infrastructure envoie la demande en haut de la pile de pilotes du parent de l’AOP. Par conséquent, la requête descend de deux piles de pilotes : premièrement, la pile qui contient le pilote qui demande l’interface et, deuxièmement, la pile du parent de l’appareil de l’interface.

L’infrastructure fournit deux méthodes de référence/déréférencement que vous pouvez utiliser avec vos interfaces en spécifiant leurs adresses pour les membres InterfaceReference et InterfaceDereference de la structure INTERFACE . Pour plus d’informations sur ces méthodes, consultez WdfDeviceInterfaceReferenceNoOp et WdfDeviceInterfaceDereferenceNoOp.

Les pilotes doivent initialiser cette structure en appelant WDF_QUERY_INTERFACE_CONFIG_INIT.

Pour plus d’informations sur les interfaces définies par le pilote, consultez Utilisation d’interfaces Driver-Defined.