Parler aux périphériques USB, commencer à se terminer (application UWP)

Cet article fournit une procédure pas à pas de bout en bout de la création d’une application UWP qui parle à un appareil USB.

Utilisez les API Windows Runtime pour écrire des applications UWP qui permettent aux utilisateurs d’accéder à leur périphérique USB périphérique. Ces applications peuvent se connecter à un appareil en fonction de critères spécifiés par l’utilisateur, obtenir des informations sur l’appareil, envoyer des données à l’appareil et obtenir à l’inverse des flux de données à partir de l’appareil et interroger l’appareil pour obtenir des données d’interruption.

Ici, nous décrivons comment votre application UWP peut implémenter ces tâches et établir un lien vers des exemples illustrant l’utilisation de classes incluses dans Windows.Devices.Usb. Nous allons parcourir les fonctionnalités d’appareil requises dans le manifeste de l’application et comment lancer l’application lorsque l’appareil se connecte. Et nous allons montrer comment exécuter une tâche de transfert de données en arrière-plan même lorsque l’application s’interrompt pour économiser la durée de vie de la batterie.

Procédure pas à pas : écriture d’une application UWP pour les périphériques USB

Suivez les étapes décrites dans cet article ou passez directement à l’exemple d’accès de périphérique USB personnalisé. L’exemple complémentaire implémente toutes les étapes ici, mais pour garder les choses en mouvement, nous ne pas parcourir le code. Certaines étapes ont une recherche dans l’exemple de section pour vous aider à trouver le code rapidement. La structure des fichiers sources de l’exemple est simple et plate pour vous permettre de trouver facilement du code sans avoir à explorer plusieurs couches de fichiers sources. Mais vous préférez peut-être diviser et organiser votre propre projet différemment.

Installer le pilote Microsoft WinUSB

Installez le pilote WinUSB fourni par Microsoft en tant que pilote de fonction pour votre appareil.

Démarrage rapide : installation de WinUSB (Winusb.sys)

Vous pouvez installer Winusb.sys de ces façons :

• Lorsque vous connectez votre appareil, vous remarquerez peut-être que Windows charge Winusb.sys automatiquement, car l’appareil est un appareil WinUSB.
• Installez le pilote en spécifiant la classe de périphérique fournie par le système dans Gestionnaire de périphériques.
• Installez le pilote à l’aide d’un INF personnalisé. Vous pouvez obtenir l’INF de l’une des deux manières suivantes :
  • Obtenez l’inf auprès du fournisseur de matériel.
  • Écrivez un INF personnalisé qui référence le fichier Winusb.inf fourni par Microsoft. Pour plus d’informations, consultez l’installation de WinUSB (Winusb.sys).

Obtenir des informations sur votre appareil

Obtenez le GUID de l’interface de l’appareil, l’ID matériel et les informations de classe d’appareil sur votre appareil.

Vous pouvez obtenir ces informations auprès du fabricant de l’appareil.

• Identificateurs de fournisseur et de produit

  Dans Gestionnaire de périphériques, affichez les propriétés de l’appareil. Sous l’onglet Détails , affichez la valeur de la propriété Id matériel. Cette valeur est une combinaison de ces deux identificateurs. Par exemple, pour l’appareil SuperMUTT, l’ID matériel est « USB\VID_045E&PID_F001 » ; l’ID du fournisseur est « 0x045E » et l’ID de produit est « 0xF001 ».

• Codes de classe d’appareil, de sous-classe et de protocole

• GUID de l’interface de l’appareil

Vous pouvez également afficher les informations du Registre. Pour plus d’informations, consultez les entrées du Registre des périphériques USB.

Déterminer si le jeu d’API USB autorise la classe d’appareil, la sous-classe et le protocole

Vous pouvez écrire une application UWP, si la classe d’appareil, la sous-classe et le code de protocole de l’appareil se trouvent dans la liste suivante :

• name:cdcControl, classId:02 * *
• name:physical, classId:05 * *
• name:personalHealthcare, classId:0f 00 00
• name:activeSync, classId:ef 01 01
• name:palmSync, classId:ef 01 02
• name:deviceFirmwareUpdate, classId:fe 01 01
• name:irda, classId:fe 02 00
• name:measurement, classId:fe 03 *
• name:vendorSpecific, classId:ff * *

Créer un projet Visual Studio de base

Créez un projet Visual Studio de base que vous pouvez étendre dans ce didacticiel.

Pour plus d’informations, consultez Bien démarrer avec les applications UWP.

Ajouter des fonctionnalités d’appareil USB au manifeste de l’application

Découvrez comment ajouter des fonctionnalités d’appareil USB au manifeste de l’application.

Démarrage rapide : Comment ajouter des fonctionnalités d’appareil USB au manifeste de l’application

Ouvrez votre fichier Package.appxmanifest dans un éditeur de texte et ajoutez l’élément DeviceCapability avec l’attribut Name défini sur « usb », comme illustré dans cet exemple.

Remarque

Vous ne pouvez pas modifier la fonctionnalité d’appareil USB dans Visual Studio. Vous devez cliquer avec le bouton droit sur le fichier Package.appxmanifest dans Explorateur de solutions, puis sélectionner Ouvrir avec..., puis l’éditeur XML (texte). Le fichier s’ouvre en XML brut.

<Capabilities>
  <!--When the device's classId is FF * *, there is a predefined name for the class.
      You can use the name instead of the class id.
      There are also other predefined names that correspond to a classId.-->
  <m2:DeviceCapability Name="usb">
    <!--SuperMutt Device-->
    <m2:Device Id="vidpid:045E 0611">
      <!--<wb:Function Type="classId:ff * *"/>-->
      <m2:Function Type="name:vendorSpecific"/>
    </m2:Device>
  </m2:DeviceCapability>
</Capabilities>

Recherchez-le dans l’exemple : les fonctionnalités de l’appareil USB se trouvent dans le fichier Package.appxmanifest.

Ouvrir l’appareil pour la communication

Étendez l’application pour ouvrir l’appareil pour la communication.

Démarrage rapide : Comment se connecter à un appareil USB (application UWP)

1. Recherchez l’appareil en créant une chaîne AQS (Advanced Query Syntax) qui contient des critères de recherche pour rechercher l’appareil dans la collection d’appareils énumérées.
2. Ouvrez l’appareil de l’une des deux manières suivantes :

   • En passant l’AQS à FindAllAsync et en récupérant l’objet DeviceInformation pour l’appareil.

     Pour plus d’informations, consultez Démarrage rapide : énumération des appareils couramment utilisés.

   • En utilisant un objet DeviceWatcher pour détecter quand l’appareil est ajouté ou supprimé du système.

     1. Passez l’AQS à CreateWatcher et obtenez un objet DeviceWatcher.
     2. Inscrire des gestionnaires d’événements sur l’objet DeviceWatcher .
     3. Obtenez l’objet DeviceInformation pour l’appareil dans votre gestionnaire d’événements Ajouté.
     4. Démarrez et arrêtez l’objet DeviceWatcher .

     Pour plus d’informations, consultez Comment obtenir des notifications si des appareils sont ajoutés, supprimés ou modifiés.

3. Obtenez l’instance de l’appareil à partir de la propriété DeviceInformation.Id.
4. Appelez FromIdAsync en passant la chaîne d’instance de l’appareil et obtenez l’objet UsbDevice.

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario1_DeviceConnect.

Étudier la disposition de votre périphérique USB

Étudiez la disposition de votre périphérique USB.

Passez en revue les concepts USB de base sur la configuration de l’appareil et l’exécution des transferts de données : concepts pour tous les développeurs USB.

Affichez le descripteur de configuration de l’appareil, les descripteurs d’interface pour chaque autre paramètre pris en charge et leurs descripteurs de point de terminaison. En utilisant USBView, vous pouvez parcourir tous les contrôleurs USB et les périphériques USB connectés à eux, et également inspecter la configuration de l’appareil.

Obtenir et afficher les descripteurs USB dans l’interface utilisateur

Étendez l’application pour obtenir et afficher les descripteurs USB dans l’interface utilisateur.

Démarrage rapide : Comment obtenir des descripteurs USB (application UWP)

• Obtenez le descripteur d’appareil en obtenant la valeur UsbDevice.DeviceDescriptor.

• Obtenez le descripteur de configuration en obtenant la valeur UsbConfiguration.ConfigurationDescriptor.

  • Obtenez le descripteur de configuration complet défini en obtenant la propriété UsbConfiguration.Descriptors.

• Obtenez le tableau d’interfaces au sein de la configuration en obtenant la propriété UsbConfiguration.UsbInterfaces.

• Obtenez le tableau des autres paramètres en obtenant UsbInterface.InterfaceSettings.

• Dans le paramètre alternatif actif, énumérez les canaux et obtenez les points de terminaison associés.

  Ces objets représentent les descripteurs de point de terminaison :

  • UsbBulkInEndpointDescriptor
  • UsbBulkOutEndpointDescriptor
  • UsbInterruptInEndpointDescriptor
  • UsbInterruptOutEndpointDescriptor

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario5_UsbDescriptors.

Envoyer des transferts de contrôle USB définis par le fournisseur

Étendez l’application pour envoyer des transferts de contrôle USB définis par le fournisseur.

Démarrage rapide : Envoi d’une demande de transfert de contrôle USB (application UWP)

1. Obtenez la commande du fournisseur à partir de la spécification matérielle de l’appareil.
2. Créez un objet UsbSetupPacket et remplissez le paquet d’installation en définissant différentes propriétés.
3. Démarrez une opération asynchrone pour envoyer le transfert de contrôle par ces méthodes en fonction de la direction du transfert :
   • SendControlInTransferAsync
   • SendControlOutTransferAsync

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario2_ControlTransfer.

Lire ou écrire des données en bloc

Étendez l’application pour lire ou écrire des données en bloc.

Démarrage rapide : Comment envoyer une demande de transfert en bloc USB (application UWP)

1. Obtenez l’objet de canal en bloc (UsbBulkOutPipe ou UsbBulkInPipe).
2. Configurez le canal en bloc pour définir les paramètres de stratégie.
3. Configurez le flux de données à l’aide de l’objet DataReader ou DataWriter.
4. Démarrez une opération de transfert asynchrone en appelant DataReader.LoadAsync ou DataWriter.StoreAsync.
5. Obtenez les résultats de l’opération de transfert.

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario4_BulkPipes.

Obtenir des données d’interruption matérielle

Étendez l’application pour obtenir des données d’interruption matérielle.

Démarrage rapide : Comment envoyer une demande de transfert d’interruption USB (application UWP)

1. Obtenez l’objet de canal d’interruption (UsbInterruptInPipe ou UsbInterruptOutPipe).
2. Implémentez le gestionnaire d’interruptions pour l’événement DataReceived .
3. Inscrivez le gestionnaire d’événements pour commencer à recevoir des données.
4. Annulez l’inscription du gestionnaire d’événements pour arrêter la réception de données.

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario3_InterruptPipes.

Sélectionner un paramètre d’interface qui n’est pas actif actuellement

Étendez l’application pour sélectionner un paramètre d’interface qui n’est pas actif actuellement.

Démarrage rapide : Comment sélectionner un paramètre d’interface USB (application UWP)

Lorsque l’appareil est ouvert pour la communication, l’interface par défaut et son premier paramètre sont sélectionnés. Si vous souhaitez modifier ce paramètre, procédez comme suit :

1. Obtenez le paramètre actif d’une interface USB à l’aide de la valeur UsbInterfaceSetting.Selected.
2. Définissez un paramètre d’interface USB en démarrant une opération asynchrone en appelant UsbInterfaceSetting.SelectSettingAsync.

Fermer l’appareil

Étendez l’application pour fermer l’appareil.

Démarrage rapide : Comment se connecter à un appareil USB (application UWP)

Une fois l’objet UsbDevice terminé, fermez l’appareil.

Les applications C++ doivent libérer la référence à l’aide du mot clé delete . Les applications C#/VB doivent appeler la méthode UsbDevice.Dispose. Les applications JavaScript doivent appeler UsbDevice.Close.

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario1_DeviceConnect.

Créer un package de métadonnées d’appareil

Créez un package de métadonnées d’appareil pour l’application.

Outil : Assistant Création de métadonnées d’appareil

• Si le Kit de pilotes Windows (WDK) est installé, ouvrez la création des métadonnées>de périphérique de pilote.>
• Si le Kit de développement logiciel (SDK) autonome est installé, l’outil se trouve à <install_path>\bin\x86\DeviceMetadataWizardexe.

Associez votre application à l’appareil en suivant les étapes de l’Assistant. Entrez ces informations sur votre appareil :

• Dans la page Informations sur l’appareil, entrez le nom du modèle, le fabricant et la description.
• Dans la page Informations matérielles, entrez l’ID matériel de votre appareil.

Pour déclarer l’application en tant qu’application privilégiée pour votre appareil, suivez ces instructions :

1. Dans la page Informations sur l’application, dans le groupe d’applications privilégiés, entrez le nom du package, le nom du serveur de publication et l’ID d’application UWP.

   

   Remarque

   Ne cochez pas l’option de pilote personnalisé Access.

2. Ouvrez l’onglet Terminer . Cochez la case Copier les packages dans le magasin de métadonnées local de votre système.

3. Connectez l’appareil, dans Panneau de configuration, ouvrez Afficher les appareils et imprimantes et vérifiez que l’icône de l’appareil est correcte.

Recherchez-le dans l’exemple : consultez le dossier DeviceMetadata.

Implémenter l’activation de lecture automatique

Étendez l’application en implémentant l’activation de lecture automatique pour lancer l’application lorsque l’appareil se connecte au système.

Démarrage rapide : Inscrire une application pour un appareil de lecture automatique

Vous pouvez ajouter des fonctionnalités de lecture automatique afin que l’application démarre lorsque l’appareil se connecte au système. Vous pouvez activer la lecture automatique pour toutes les applications UWP (privilégiées ou autrement).

1. Dans votre package de métadonnées d’appareil, vous devez spécifier la façon dont l’appareil doit répondre à une notification de lecture automatique. Sous l’onglet Informations Windows, sélectionnez l’option d’application d’appareil UWP et entrez les informations d’application comme indiqué ici :

2. Dans le manifeste de l’application, ajoutez la déclaration d’appareil de lecture automatique et les informations de lancement, comme indiqué ici :

   

3. Dans la méthode OnActivated de la classe App, vérifiez si l’appareil a activé l’application. Si c’est le cas, la méthode reçoit une valeur de paramètre DeviceEventArgs qui contient la valeur de la propriété DeviceInformation.Id . Il s’agit de la même valeur décrite dans Ouvrir l’appareil pour la communication.

Recherchez-le dans l’exemple : consultez les fichiers nommés Lecture automatique. Pour JavaScript, consultez default.js.

Implémenter une tâche en arrière-plan

Étendez l’application pour implémenter une tâche en arrière-plan qui peut effectuer des transferts de longueur vers l’appareil, tels que la mise à jour du microprogramme sans que l’application soit suspendue.

Pour implémenter une tâche en arrière-plan, vous avez besoin de deux classes.

La classe de tâche en arrière-plan implémente l’interface IBackgroundTask et contient le code réel que vous créez pour synchroniser ou mettre à jour votre appareil périphérique. La classe de tâche en arrière-plan s’exécute lorsque la tâche en arrière-plan se déclenche et à partir du point d’entrée fourni dans le manifeste d’application de votre application.

Remarque

Infrastructure des tâches en arrière-plan de l’appareil fournie par Windows 8.1. Pour plus d’informations sur les tâches en arrière-plan Windows, consultez Prise en charge de votre application avec des tâches en arrière-plan.

Classe de tâche en arrière-plan

1. Implémente l’interface IBackgroundTask requise par l’infrastructure de tâches en arrière-plan Windows.
2. Obtient l’instance DeviceUseDetails passée à la classe dans la méthode Run et utilise cette instance pour signaler la progression à l’application Microsoft Store et s’inscrire aux événements d’annulation.
3. La méthode Run appelle également les méthodes OpenDevice et WriteToDeviceAsync privées qui implémentent le code de synchronisation d’appareil en arrière-plan.

L’application UWP inscrit et déclenche une tâche en arrière-plan DeviceUseTrigger. L’inscription, le déclencheur et la progression de l’application sur une tâche en arrière-plan.

Remarque

L’exemple de code suivant peut être appliqué à la tâche en arrière-plan DeviceServicingTrigger en utilisant les objets correspondants. La seule différence entre les deux objets déclencheurs et leurs API correspondantes est les vérifications de stratégie effectuées par Windows.

1. Crée des objets DeviceUseTrigger et BackgroundTaskRegistration.
2. Vérifie si des tâches en arrière-plan ont été précédemment inscrites par cet exemple d’application et les annule en appelant la méthode Unregister sur la tâche.
3. Inscrit la tâche en arrière-plan qui se synchronise avec l’appareil. La méthode SetupBackgroundTask est appelée à partir de la méthode SyncWithDeviceAsync à l’étape suivante.
   1. Initialise DeviceUseTrigger et l’enregistre pour une utilisation ultérieure.
   2. Crée un objet BackgroundTaskBuilder et utilise ses propriétés et méthodes Name, TaskEntryPoint et SetTrigger pour inscrire l’objet DeviceUseTrigger de l’application et le nom de la tâche en arrière-plan. La propriété TaskEntryPoint de l’objet BackgroundTaskBuilder est définie sur le nom complet de la classe de tâche en arrière-plan qui sera exécutée lorsque la tâche en arrière-plan est déclenchée.
   3. S’inscrit aux événements d’achèvement et de progression à partir de la tâche en arrière-plan afin que l’application Microsoft Store puisse fournir des mises à jour d’achèvement et de progression à l’utilisateur.
4. La méthode Private SyncWithDeviceAsync inscrit la tâche en arrière-plan qui se synchronise avec l’appareil et démarre la synchronisation en arrière-plan.

   1. Appelle la méthode SetupBackgroundTask de l’étape précédente et inscrit la tâche en arrière-plan qui se synchronise avec l’appareil.

   2. Appelle la méthode StartSyncBackgroundTaskAsync privée qui démarre la tâche en arrière-plan.

   3. Ferme le handle de l’application sur l’appareil pour s’assurer que la tâche en arrière-plan est en mesure d’ouvrir l’appareil au démarrage.

      Remarque

      La tâche en arrière-plan doit ouvrir l’appareil pour effectuer la mise à jour afin que l’application Microsoft Store doit fermer ses connexions à l’appareil avant d’appeler RequestAsync

   4. Appelle la méthode RequestAsync de l’objet DeviceUseTrigger qui démarre déclenche la tâche en arrière-plan et retourne l’objet DeviceTriggerResults de RequestAsync utilisé pour déterminer si la tâche en arrière-plan a démarré correctement.

      Remarque

      Windows vérifie pour s’assurer que toutes les vérifications de politique d’initiation de tâche nécessaires ont été effectuées. Si toutes les vérifications de stratégie sont terminées, l’opération de mise à jour s’exécute désormais en tant que tâche en arrière-plan en dehors de l’application du Microsoft Store, ce qui permet à l’application d’être suspendue en toute sécurité pendant que l’opération est en cours. Windows appliquera également toutes les exigences d’exécution et annulera la tâche d’arrière-plan si ces exigences ne sont plus remplies.

   5. Utilise l’objet DeviceTriggerResults retourné à partir de StartSyncBackgroundTaskAsync pour déterminer si la tâche en arrière-plan a démarré correctement. Une instruction switch est utilisée pour inspecter le résultat de DeviceTriggerResults.

5. Implémente un gestionnaire d’événements OnSyncWithDeviceProgress privé qui met à jour l’interface utilisateur de l’application avec la progression de la tâche en arrière-plan.
6. Implémente un gestionnaire d’événements OnSyncWithDeviceCompleted privé pour gérer la transition des tâches en arrière-plan vers l’application de premier plan lorsque la tâche en arrière-plan est terminée.
   1. Utilise la méthode CheckResults de l’objet BackgroundTaskCompletedEventArgs pour déterminer si des exceptions ont été levées par la tâche en arrière-plan.
   2. L’application rouverte l’appareil à utiliser par l’application de premier plan maintenant que la tâche en arrière-plan est terminée et met à jour l’interface utilisateur pour avertir l’utilisateur.
7. Implémente les gestionnaires d’événements click de bouton privé à partir de l’interface utilisateur pour démarrer et annuler la tâche en arrière-plan.
   1. Le gestionnaire d’événements de Sync_Click privé appelle la méthode SyncWithDeviceAsync décrite dans les étapes précédentes.
   2. Le gestionnaire d’événements de CancelSync_Click privé appelle la méthode CancelSyncWithDevice privée pour annuler la tâche en arrière-plan.
8. La méthode CancelSyncWithDevice privée annule les inscriptions et annule les synchronisations d’appareils actifs afin que l’appareil puisse être rouvert à l’aide de la méthode Unregister sur l’objet BackgroundTaskRegistration.

Recherchez-le dans l’exemple : consultez les fichiers nommés Scenario7_Sync fichiers. La classe d’arrière-plan est implémentée dans IoSyncBackgroundTask.

Exécuter le kit de certification des applications Windows

Exécutez le kit de certification des applications Windows.

Utilisation du Kit de certification des applications Windows

Recommandé. L’exécution du kit de certification des applications Windows vous permet de vous assurer que votre application répond aux exigences du Microsoft Store. Vous devez l’exécuter chaque fois que vous ajoutez des fonctionnalités majeures à votre application.

Exemples connexes

• Exemple d’accès d’appareil USB personnalisé
• Exemple de contrôle CDC USB
• Exemple d’appareil USB de mise à jour du microprogramme

Interface utilisateur de l’application UWP, début à terminer (XAML)

En savoir plus sur la conception de l’interface utilisateur de l’application UWP.

Feuille de route pour les applications UWP utilisant C# et Visual Basic et Feuille de route pour les applications UWP à l’aide de C++

En savoir plus sur la création d’applications UWP à l’aide de C++, C# ou Visual Basic en général.

Programmation asynchrone (applications UWP)

Découvrez comment rendre vos applications réactives lorsqu’elles fonctionnent, ce qui peut prendre beaucoup de temps.

API importantes

• Windows.Devices.Usb
• Windows.Devices.Enumeration
• Windows.Devices.Background