Noms conviviaux pour les appareils de point de terminaison audio

Dans Windows Vista, Windows Server 2008 et versions ultérieures de Windows, le sous-système audio prend en charge la notion d’appareil de point de terminaison audio, par exemple les haut-parleurs, les casques, les microphones et les lecteurs DE CD. Ce concept de points de terminaison audio permet de créer des applications audio conviviales qui ont des interfaces utilisateur qui font référence aux appareils de point de terminaison que les utilisateurs manipulent directement. Ces points de terminaison ont des noms conviviaux tels que « haut-parleurs », « casque », « microphone » et « lecteur CD » que les applications peuvent afficher dans leurs interfaces utilisateur. Pour plus d’informations sur les appareils de point de terminaison, consultez Périphériques de point de terminaison audio.

Le sous-système audio modélise un appareil Plug-and-Play (PnP) sur une carte audio en tant que filtre KS. Les flux de données entrent et quittent le filtre via des broches KS. Une broche de pont est une broche KS via laquelle un appareil de point de terminaison audio se connecte à un filtre KS. Pour plus d’informations sur les broches de pont, consultez Graphiques de filtre audio.

Le sous-système audio obtient des informations sur un appareil de point de terminaison audio en examinant les propriétés de la broche de pont à laquelle l’appareil de point de terminaison se connecte. L’une de ces propriétés est la propriété de catégorie d’épingle (KSPROPERTY_PIN_CATEGORY).

Pour chaque filtre KS, le pilote d’adaptateur fournit une table de structures PCPIN_DESCRIPTOR qui décrivent les propriétés des broches KS sur le filtre. Le GUID de la catégorie d’épingle est stocké dans le membre KsPinDescriptor.Category de la structure PCPIN_DESCRIPTOR. Pour une broche de pont, la valeur du GUID de catégorie de broche indique le type de point de terminaison qui se connecte à la broche de pont. Par exemple, le GUID de catégorie de broche KSNODETYPE_MICROPHONE indique que la broche de pont se connecte à un microphone, le GUID KSNODETYPE_SPEAKER indique que la broche de pont se connecte aux haut-parleurs, etc. Les GUID KSNODETYPE_XXX sont définis dans le fichier d’en-tête Ksmedia.h.

En outre, le PCPIN_DESCRIPTOR inclut un GUID qui peut être utilisé pour identifier l’épingle par un nom unique. Ce GUID de nom d’épingle est stocké dans le membre KsPinDescriptor.Name de la structure PCPIN_DESCRIPTOR. Ce GUID de nom est utilisé par la propriété (KSPROPERTY_PIN_NAME) pour associer un nom convivial trouvé dans le Registre à l’épingle.

Le sous-système audio appelle la propriété KSPROPERTY_PIN_NAME pour associer un nom convivial à un point de terminaison audio. KS gère cette requête en recherchant d’abord une chaîne Unicode dans le Registre décrivant le GUID KsPinDescriptor.Name . Si KS ne trouve pas d’entrée, il recherche dans le Registre une chaîne Unicode décrivant le GUID KsPinDescriptor.Category .

À compter de Mise à jour d'octobre 2018 de Windows 10, version 1809, lors de la recherche dans le Registre, KS recherche d’abord une entrée dans la clé logicielle de l’appareil. Il est créé par l’INF via une section AddReg référencée par la section [Modèles] de l’INF du pilote de périphérique. La section AddReg construit ces entrées à l’aide de la clé HKR\MediaCategories. Cela permet au développeur de pilotes de créer des noms conviviaux spécifiques à l’appareil pour les GUID Nom et Catégorie, que le GUID soit propre ou non à l’appareil.

Si aucune entrée n’a été installée dans la clé logicielle de l’appareil ou si le pilote s’exécute sur un système d’exploitation antérieur à Windows 10 version 1809, KS vérifie la clé de Registre MediaCategories. Cette deuxième clé est traitée comme un espace de nom global. À compter de Windows 10 version 1809, cet espace est réservé aux définitions globales et ne doit pas être modifié par de nouveaux pilotes. La modification des entrées sous cette clé ne sera pas prise en charge dans une version ultérieure du système d’exploitation.

Les périphériques audio qui exposent des broches avec des GUID de catégories standard doivent inclure /ont besoin de la KS de la boîte de réception. INF ou KSCAPTUR. Inscription de nom INF dans l’INF de votre appareil. Ces INF de boîte de réception contiennent des définitions de noms conviviaux par défaut pour les GUID de catégorie prédéfinis que votre pilote peut souhaiter remplir. Il s’agit des mêmes GUID que dans le membre KsPinDescriptor.Category de la structure PCPIN_DESCRIPTOR. Par exemple, le GUID de catégorie KSNODETYPE_MICROPHONE’entrée a le nom convivial « microphone » associé et le GUID de catégorie KSNODETYPE_SPEAKER entrée a le nom convivial associé « speakers », etc.

Les GUID et les noms conviviaux pour les GUID catégorie et nom sont stockés dans le Registre. Pour chaque paire GUID-nom dans le Registre, la chaîne GUID est utilisée comme sous-clé sous la clé MediaCategories. Sous la clé GUID, le nom convivial contient une valeur de chaîne Unicode sous la variable « Name ».

Si aucun des noms conviviaux et des catégories d’épingles définis par le sous-système audio ne décrit correctement votre appareil, vous pouvez définir vos propres GUID de catégorie et de nom et leur associer des noms conviviaux dans votre INF. Pour vous assurer que votre GUID de catégorie d’épingles est unique, utilisez un utilitaire tel que Uuidgen.exe pour générer le GUID. Ensuite, modifiez le fichier INF qui installe votre carte audio pour écrire le GUID de la catégorie d’épingle et le nom convivial dans le registre. L’exemple de code suivant montre un fragment d’un fichier INF qui ajoute deux GUID de catégorie d’épingles et leurs noms conviviaux associés au Registre :

[Manufacturer]
MyOEMName=Unicorn,NTamd64

[Unicorn.NTamd64]
MyDeviceName=MyDevice,Root\MyDevice

[MyDevice.NT]
Include=ks.inf, kscaptur.inf
Needs=KS.Registration, KSCAPTUR.Registration.NT
CopyFiles=MyDevice.CopyFiles
AddReg=PinNameRegistration

...

[PinNameRegistration]
HKR,%MediaCategories%\%GUID.MyNewEndpointCategory%,Name,,%Name.MyNewEndpointCategory%
HKR,%MediaCategories%\%GUID.MyNewEndpointName%,Name,,%Name.MyNewEndpointName%

...

[Strings]
MyOEMName="Unicorns Inc."
MyDeviceName="Sparkly Unicorn"
MediaCategories="MediaCategories"

GUID.MyNewEndpointCategory="{B72FBD1A-4634-4240-B207-0E6B52F3701C}"
GUID.MyNewEndpoint_2="{71DD3A5D-E303-49A0-ACEE-908634AA9520}"

Name.MyNewEndpointCategory="Unicorn"
Name.MyNewEndpointName="Fred the Unicorn"

Les deux chaînes GUID ont été générées par Uuidgen.exe.

Les applications peuvent accéder aux propriétés d’un appareil de point de terminaison audio à l’aide de l’interface IPropertyStore de l’appareil. L’interface utilise les clés de propriété définies dans les fichiers d’en-tête Functiondiscoverykeys_devpkey.h et Mmdeviceapi.h pour identifier les propriétés. Une application peut utiliser la clé de propriété PKEY_Device_FriendlyName pour récupérer le nom convivial d’un appareil de point de terminaison. Pour les interfaces utilisateur à espace limité, une version plus courte du nom convivial peut être récupérée à l’aide de la clé de propriété PKEY_Device_DeviceDesc . Pour plus d’informations sur ces clés de propriété, consultez IMMDevice::OpenPropertyStore.

Une interface IPropertyStore instance gère un magasin de propriétés persistant pour un appareil de point de terminaison audio. Le magasin de propriétés copie sa valeur initiale pour la clé de propriété PKEY_Device_DeviceDesc à partir de la chaîne de nom conviviale associée au GUID de catégorie de broche KS dans le Registre. Les applications peuvent lire la valeur de propriété PKEY_Device_DeviceDesc (chaîne de nom) à partir du magasin de propriétés, mais elles ne peuvent pas modifier la valeur. Toutefois, les utilisateurs peuvent modifier le nom à l’aide du panneau de configuration multimédia Windows, Mmsys.cpl. Par exemple, dans Windows Vista, vous pouvez utiliser les étapes suivantes pour modifier le nom d’un appareil de point de terminaison de rendu :

1. Pour exécuter Mmsys.cpl, ouvrez une fenêtre d’invite de commandes et entrez la commande suivante :

   mmsys.cpl
   

   (Vous pouvez également exécuter Mmsys.cpl en cliquant avec le bouton droit sur l’icône du haut-parleur dans la zone de notification, qui se trouve sur le côté droit de la barre des tâches, puis en cliquant sur Périphériques de lecture.)

2. Cliquez sur le nom d’un appareil de rendu, puis sur Propriétés.

3. Dans le Fenêtre Propriétés, cliquez sur l’onglet Général. Le nom convivial doit apparaître dans une zone de texte en haut de la feuille de propriétés. Vous pouvez modifier le nom convivial, puis enregistrer vos modifications en cliquant sur OK.

Les étapes précédentes modifient le nom convivial stocké dans le magasin de propriétés pour l’appareil de point de terminaison audio. Ces étapes n’ont aucun effet sur les noms conviviaux associés à d’autres appareils de point de terminaison audio qui appartiennent à la même catégorie de broche KS. Ils n’ont pas non plus d’effet sur un composant qui peut interroger KS directement pour obtenir un nom.