EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST fonction de rappel (wdfqueryinterface.h)

[S’applique uniquement à KMDF]

La fonction de rappel d’é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 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 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 de retour

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 d’état pour laquelle NT_SUCCESS(status) a la valeur 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 servira 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 suivante.

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

Remarques

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

Si l’interface définie par le pilote prend en charge uniquement 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 une 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 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 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, elle 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 de contexte de la structure INTERFACE .
L’infrastructure appelle les fonctions de rappel EvtDeviceProcessQueryInterfaceRequest de votre pilote uniquement pour les GUID que le pilote a inscrits 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, pour un cas particulier, il ne gère pas l’interface. Par exemple, en fonction des données que fournit le pilote demandeur, 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 Utilisation des 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 fonctions de rappel aide l’analyse du code pour les pilotes, le vérificateur de pilote statique (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 La 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.

Configuration requise

   
Plateforme cible Universal
Version KMDF minimale 1.0
En-tête wdfqueryinterface.h (inclure Wdf.h)
IRQL PASSIVE_LEVEL

Voir aussi

INTERFACE

WDF_QUERY_INTERFACE_CONFIG

WdfDeviceAddQueryInterface

WdfFdoQueryForInterface