EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST fonction de rappel (wdfqueryinterface.h)

Article
07/16/2024

[S’applique uniquement à KMDF]

La fonction de rappel d’événement evtDeviceProcessQueryInterfaceRequest pilote examine la demande d’accès d’un autre pilote à une interface définie par le pilote, avant que l’infrastructure ne passe l’interface au pilote demandeur.

Syntaxe

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

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

Paramètres

[in] Device

Handle vers un objet d’appareil framework.

[in] InterfaceType

Pointeur vers le GUID qui identifie l’interface définie par le pilote.

[in, out] ExposedInterface

Pointeur vers une structure INTERFACE qui décrit l’interface définie par le pilote et a été fourni par le pilote qui demande l’accès à l’interface.

[in, out] ExposedInterfaceSpecificData

Pointeur vers des informations supplémentaires, facultatives, définies par un pilote et spécifiques à l’interface. Les pilotes basés sur l’infrastructure spécifient cette valeur en fournissantune valeur de paramètreNULLInterfaceSpecificData lors de l’appel WdfFdoQueryForInterface.

Valeur de retour

Si la fonction EvtDeviceProcessQueryInterfaceRequest reçoit un GUID qu’elle prend en charge et si la fonction ne rencontre aucune erreur, elle doit retourner STATUS_SUCCESS ou une autre valeur d’état pour laquelle NT_SUCCESS(status) est égal à TRUE. L’infrastructure continue de transmettre la requête vers le bas de la pile pour voir si des pilotes supplémentaires prennent également en charge l’interface.

La fonction de rappel EvtDeviceProcessQueryInterfaceRequest doit retourner STATUS_NOT_SUPPORTED si elle détermine que, pour un cas particulier, il ne traitera pas l’interface. L’infrastructure continue de transmettre la requête vers le bas de la pile pour voir si un autre pilote prend en charge l’interface. Pour plus d’informations sur cette situation, consultez la section Remarques suivantes.

Si la fonction de rappel rencontre une erreur, elle doit retourner une valeur d’état pour laquelle NT_SUCCESS(status) est égal FALSE. L’infrastructure échoue la demande de l’autre pilote pour l’interface et ne transmet pas la requête dans la pile.

Remarques

Les pilotes basés sur le framework inscrivent une fonction de rappel d’événement EvtDeviceProcessQueryInterfaceRequest en appelant WdfDeviceAddQueryInterface.

Si l’interface définie par le pilote ne prend en charge que la communication unidirectionnelle et définit le membre importInterface de la structure WDF_QUERY_INTERFACE_CONFIG qui décrit l’interface sur FALSE, la fonction de rappel EvtDeviceProcessQueryInterfaceRequest est facultative. Quand un autre pilote appelle WdfFdoQueryForInterface, l’infrastructure copie les valeurs d’interface définies par le pilote dans la structure interface du pilote demandeur, puis appelle la fonction de rappel. Pour la communication unidirectionnelle, vous devez fournir une fonction de rappel uniquement si vous souhaitez que le pilote examine, et éventuellement modifie, les valeurs d’interface avant que l’infrastructure ne les renvoie au pilote demandeur.

Votre pilote doit fournir une fonction de rappel d’événement EvtDeviceProcessQueryInterfaceRequest si le pilote définit une interface qui prend en charge la communication bidirectionnelle (et définit le membre ImportInterface de la structure WDF_QUERY_INTERFACE_CONFIG sur TRUE). La fonction de rappel est requise, car si ImportInterface est TRUE et un autre pilote appelle WdfFdoQueryForInterface, l’infrastructure ne copie pas l’interface définie par le pilote dans la structure d’interface du pilote demandeur. Au lieu de cela, la fonction de rappel doit mettre à jour la structure d’interface du pilote demandeur.

La fonction de rappel peut modifier l’interface. En particulier, il peut :

Modifiez n’importe quelle valeur dans n’importe quel membre de l’interface.
Allouez un contexte spécifique à une instance dynamique en modifiant le membre Context de la structure interface .

L’infrastructure appelle les fonctions de rappel EvtDeviceProcessQueryInterfaceRequest uniquement pour les GUID enregistrés par le pilote en appelant WdfDeviceAddQueryInterface. Par conséquent, ces fonctions de rappel n’utilisent pas la valeur de retour STATUS_NOT_SUPPORTED pour signaler des GUID inattendus. Au lieu de cela, une fonction de rappel EvtDeviceProcessQueryInterfaceRequest doit retourner STATUS_NOT_SUPPORTED lorsqu’elle détermine que, dans un cas particulier, elle ne gère pas l’interface. Par exemple, en fonction des données que le pilote demandeur fournit, votre pilote peut déterminer qu’un pilote de niveau inférieur doit traiter la demande d’interface. La valeur de retour STATUS_NOT_SUPPORTED informe l’infrastructure que votre pilote ne prend pas en charge la demande d’interface, mais qu’un pilote de niveau inférieur peut le traiter.

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

Exemples

Pour définir une EvtDeviceProcessQueryInterfaceRequest fonction de rappel, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une fonction de rappel EvtDeviceProcessQueryInterfaceRequest nommée MyDeviceProcessQueryInterfaceRequest, utilisez le type EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST comme indiqué dans cet exemple de code :

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

Ensuite, implémentez votre fonction de rappel comme suit :

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

Le type de fonction EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST est défini dans le fichier d’en-tête WdfQueryInterface.h. Pour identifier plus précisément les erreurs lorsque vous exécutez les outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes KMDF. Pour plus d’informations sur Use_decl_annotations, consultez annoter le comportement de la fonction.