EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST fonction de rappel (wdfqueryinterface.h)

Article
08/08/2023

[S’applique uniquement à KMDF]

La fonction de rappel de l’événement EvtDeviceProcessQueryInterfaceRequest d’un pilote examine la demande d’accès d’un autre pilote à une interface définie par le pilote, avant que l’infrastructure 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 d’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 le pilote et spécifiques à l’interface. Les pilotes basés sur l’infrastructure spécifient cette valeur en fournissant une valeur de paramètre interfaceSpecificData non NULL lors de l’appel de WdfFdoQueryForInterface.

Valeur retournée

Si la fonction de rappel 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 status pour laquelle NT_SUCCESS(status) est égal à TRUE. L’infrastructure continue de transmettre la requête dans la pile pour voir si d’autres pilotes prennent également en charge l’interface.

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

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

Remarques

Les pilotes basés sur l’infrastructure 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. Lorsqu’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 modifier, les valeurs d’interface avant que l’infrastructure ne les retourne 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 a la valeur TRUE et qu’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 dynamique instance spécifique en modifiant le membre Context de la structure INTERFACE.

Le framework appelle les fonctions de rappel EvtDeviceProcessQueryInterfaceRequest de votre pilote uniquement pour les GUID que le pilote a enregistrés 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 compte la demande d’interface, mais qu’un pilote de niveau inférieur peut la traiter.

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

Exemples

Pour définir une fonction de rappel EvtDeviceProcessQueryInterfaceRequest , 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 fonction de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’erreurs. Il s’agit d’une exigence pour l’écriture de 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 lors de l’exécution des 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 Annotating Function Behavior.