Utilisation d’interfaces de périphérique dans les pilotes UMDF

  • Article

Avertissement

UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2.

Les exemples UMDF 1 archivés sont disponibles dans la mise à jour des exemples de pilotes Windows 11, version 22H2 - Mai 2022.

Pour plus d’informations, consultez Prise en main avec UMDF.

Une interface d’appareil est un lien symbolique vers un appareil Plug-and-Play (PnP) qu’une application peut utiliser pour accéder à l’appareil. Une application en mode utilisateur peut passer le nom de lien symbolique de l’interface à un élément d’API, tel que la fonction Microsoft Win32 CreateFile . Pour obtenir le nom de lien symbolique d’une interface d’appareil, l’application en mode utilisateur peut appeler des fonctions SetupDi . Pour plus d’informations sur les fonctions SetupDi, consultez Fonctions d’interface d’appareil SetupDi.

Chaque interface d’appareil appartient à une classe d’interface d’appareil. Par exemple, une pile de pilotes pour un périphérique CD-ROM peut fournir une interface qui appartient à la classe GUID_DEVINTERFACE_CDROM. L’un des pilotes du périphérique CD-ROM enregistre un instance de la classe GUID_DEVINTERFACE_CDROM pour informer le système et les applications qu’un périphérique CD-ROM est disponible. Pour plus d’informations sur les classes d’interface d’appareil, consultez Présentation des interfaces d’appareil.

Inscription d’une interface d’appareil

Pour inscrire une instance d’une classe d’interface de périphérique, un pilote UMDF peut appeler IWDFDevice::CreateDeviceInterface à partir de sa fonction de rappel IDriverEntry::OnDeviceAdd. Si le pilote prend en charge plusieurs instances de l’interface, il peut affecter une chaîne de référence unique à chaque instance.

Activation et désactivation d’une interface d’appareil

Si la création réussit, l’infrastructure active et désactive automatiquement l’interface en fonction de l’état PnP de l’appareil.

En outre, un pilote peut désactiver et réactiver une interface de périphérique si nécessaire. Par exemple, si un pilote détermine que son appareil a cessé de répondre, le pilote peut appeler IWDFDevice::AssignDeviceInterfaceState pour désactiver les interfaces de l’appareil et interdire aux applications d’obtenir de nouveaux handles pour l’interface. (Les handles existants de l’interface ne sont pas affectés.) Si l’appareil devient disponible ultérieurement, le pilote peut appeler À nouveau IWDFDevice::AssignDeviceInterfaceState pour réactiver les interfaces.

Réception de demandes d’accès à une interface d’appareil

Lorsqu’une application demande l’accès à l’interface de périphérique d’un pilote, l’infrastructure appelle la fonction de rappel IQueueCallbackCreate::OnCreateFile du pilote. Le pilote peut appeler IWDFFile::RetrieveFileName pour obtenir le nom du périphérique ou du fichier auquel l’application accède. Si le pilote a spécifié une chaîne de référence lors de l’inscription de l’interface de périphérique, le système d’exploitation inclut la chaîne de référence dans le fichier ou le nom de périphérique retourné par IWDFFile::RetrieveFileName .

Création d’événements d’appareil

Votre pilote UMDF peut créer des événements personnalisés spécifiques au périphérique (appelés événements d’appareil) en appelant IWDFDevice::P ostEvent. Un pilote qui s’est inscrit pour utiliser l’une des interfaces de l’appareil peut recevoir des notifications des événements personnalisés d’un appareil. Les pilotes basés sur UMDF reçoivent ces notifications en fournissant une fonction de rappel IRemoteInterfaceCallbackEvent::OnRemoteInterfaceEvent .

Les événements personnalisés sont propres à l’appareil. Le développeur du pilote qui crée l’événement et le développeur du pilote qui reçoit l’événement doivent comprendre la signification de l’événement.

Accès à l’interface de périphérique d’un autre pilote

Si vous souhaitez que votre pilote UMDF envoie des demandes d’E/S à une interface de périphérique qu’un autre pilote fournit, vous pouvez créer une cible d’E/S distante qui représente l’interface du périphérique.

Tout d’abord, votre pilote doit s’inscrire pour recevoir une notification lorsqu’une interface de périphérique est disponible. Utiliser les étapes suivantes :

  1. Lorsque votre pilote appelle IWDFDriver::CreateDevice, le pilote peut fournir une interface IPnpCallbackRemoteInterfaceNotification . La fonction de rappel IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival de cette interface informe votre pilote quand des interfaces de périphérique sont disponibles.

  2. Une fois que votre pilote a appelé IWDFDriver::CreateDevice, il peut appeler IWDFDevice2::RegisterRemoteInterfaceNotification pour chaque interface de périphérique que le pilote utilisera.

Par la suite, l’infrastructure appelle la fonction de rappel IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival du pilote chaque fois qu’une interface d’appareil spécifiée devient disponible. La fonction de rappel peut appeler IWDFRemoteInterfaceInitialize::GetInterfaceGuid et IWDFRemoteInterfaceInitialize::RetrieveSymbolicLink pour déterminer l’interface d’appareil qui est arrivée.

La fonction de rappel IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival de votre pilote doit généralement effectuer les opérations suivantes :

  1. Appelez IWDFDevice2::CreateRemoteInterface pour créer un objet d’interface distante, en fournissant éventuellement les interfaces IRemoteInterfaceCallbackEvent et IRemoteInterfaceCallbackRemoval .

  2. Appelez IWDFDevice2::CreateRemoteTarget pour créer un objet cible distant, en fournissant éventuellement une interface IRemoteTargetCallbackRemoval .

  3. Appelez IWDFRemoteTarget::OpenRemoteInterface pour connecter l’interface de l’appareil à la cible distante.

    Si l’interface de l’appareil est celle créée par l’énumérateur de périphérique logiciel SWENUM, votre pilote doit appeler OpenRemoteInterface à partir d’un élément de travail. (Par exemple, consultez la fonction QueueUserWorkItem dans le Kit de développement logiciel (SDK) Windows.)

À présent, le pilote peut formater et envoyer des demandes d’E/S à la cible d’E/S distante.

En plus de la fonction de rappel IPnpCallbackRemoteInterfaceNotification::OnRemoteInterfaceArrival , un pilote UMDF peut fournir deux fonctions de rappel supplémentaires pour recevoir des notifications d’événements d’interface de périphérique :