Propriétés de l’appareil (API audio principales)
Pendant le processus d’énumération des appareils de point de terminaison audio , une application cliente peut interroger les objets de point de terminaison pour leurs propriétés d’appareil. Les propriétés de l’appareil sont exposées dans l’implémentation de l’API MMDevice de l’interface IPropertyStore. Étant donné une référence à l’interface IMMDevice d’un objet de point de terminaison, un client peut obtenir une référence au magasin de propriétés de l’objet de point de terminaison en appelant la méthode IMMDevice ::OpenPropertyStore.
Les clients peuvent lire ces propriétés, mais ne doivent pas les définir. Les valeurs de propriété sont stockées sous forme de structures PROPVARIANT.
Le gestionnaire de points de terminaison définit les propriétés de base de l’appareil pour les points de terminaison. Le gestionnaire de points de terminaison est le composant Windows responsable de la détection de la présence d’appareils de point de terminaison audio.
Chaque identificateur de propriété PKEY_Xxx dans la liste suivante est une constante de type PROPERTYKEY définie dans le fichier d’en-tête Functiondiscoverykeys_devpkey.h. Tous les appareils de point de terminaison audio ont ces propriétés d’appareil.
| Propriété | Description |
|---|---|
| PKEY_DeviceInterface_FriendlyName | Nom convivial de la carte audio à laquelle l’appareil de point de terminaison est attaché (par exemple, « Adaptateur audio XYZ »). |
| PKEY_Device_DeviceDesc | Description de l’appareil de point de terminaison (par exemple, « Haut-parleurs »). |
| PKEY_Device_FriendlyName | Nom convivial de l’appareil de point de terminaison (par exemple, « Haut-parleurs (adaptateur audio XYZ) »). |
| PKEY_Device_InstanceId | Stocke le point de terminaison audio identificateur d’instance d’appareil. La valeur peut également être utilisée via méthode IMMDevice ::GetId. Pour plus d’informations sur cette propriété, consultez chaînes d’ID de point de terminaison et DEVPKEY_Device_InstanceId. |
| PKEY_Device_ContainerId | Stocke l’identificateur de conteneur de l’appareil PnP qui implémente le point de terminaison audio. Pour plus d’informations sur cette propriété, consultez DEVPKEY_Device_ContainerId. |
Certains appareils de point de terminaison audio peuvent avoir des propriétés supplémentaires qui n’apparaissent pas dans la liste précédente. Pour plus d’informations sur les propriétés supplémentaires, consultez propriétés du point de terminaison audio.
Pour plus d’informations sur PROPERTYKEY, consultez la documentation système de propriétés Windows.
L’exemple de code suivant imprime les noms complets de tous les appareils de point de terminaison de rendu audio dans le système :
//-----------------------------------------------------------
// This function enumerates all active (plugged in) audio
// rendering endpoint devices. It prints the friendly name
// and endpoint ID string of each endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres) \
if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk) \
if ((punk) != NULL) \
{ (punk)->Release(); (punk) = NULL; }
const CLSID CLSID_MMDeviceEnumerator = __uuidof(MMDeviceEnumerator);
const IID IID_IMMDeviceEnumerator = __uuidof(IMMDeviceEnumerator);
void PrintEndpointNames()
{
HRESULT hr = S_OK;
IMMDeviceEnumerator *pEnumerator = NULL;
IMMDeviceCollection *pCollection = NULL;
IMMDevice *pEndpoint = NULL;
IPropertyStore *pProps = NULL;
LPWSTR pwszID = NULL;
hr = CoCreateInstance(
CLSID_MMDeviceEnumerator, NULL,
CLSCTX_ALL, IID_IMMDeviceEnumerator,
(void**)&pEnumerator);
EXIT_ON_ERROR(hr)
hr = pEnumerator->EnumAudioEndpoints(
eRender, DEVICE_STATE_ACTIVE,
&pCollection);
EXIT_ON_ERROR(hr)
UINT count;
hr = pCollection->GetCount(&count);
EXIT_ON_ERROR(hr)
if (count == 0)
{
printf("No endpoints found.\n");
}
// Each loop prints the name of an endpoint device.
for (ULONG i = 0; i < count; i++)
{
// Get pointer to endpoint number i.
hr = pCollection->Item(i, &pEndpoint);
EXIT_ON_ERROR(hr)
// Get the endpoint ID string.
hr = pEndpoint->GetId(&pwszID);
EXIT_ON_ERROR(hr)
hr = pEndpoint->OpenPropertyStore(
STGM_READ, &pProps);
EXIT_ON_ERROR(hr)
PROPVARIANT varName;
// Initialize container for property value.
PropVariantInit(&varName);
// Get the endpoint's friendly-name property.
hr = pProps->GetValue(
PKEY_Device_FriendlyName, &varName);
EXIT_ON_ERROR(hr)
// GetValue succeeds and returns S_OK if PKEY_Device_FriendlyName is not found.
// In this case vartName.vt is set to VT_EMPTY.
if (varName.vt != VT_EMPTY)
{
// Print endpoint friendly name and endpoint ID.
printf("Endpoint %d: \"%S\" (%S)\n",
i, varName.pwszVal, pwszID);
}
CoTaskMemFree(pwszID);
pwszID = NULL;
PropVariantClear(&varName);
SAFE_RELEASE(pProps)
SAFE_RELEASE(pEndpoint)
}
SAFE_RELEASE(pEnumerator)
SAFE_RELEASE(pCollection)
return;
Exit:
printf("Error!\n");
CoTaskMemFree(pwszID);
SAFE_RELEASE(pEnumerator)
SAFE_RELEASE(pCollection)
SAFE_RELEASE(pEndpoint)
SAFE_RELEASE(pProps)
}
La macro FAILED de l’exemple de code précédent est définie dans le fichier d’en-tête Winerror.h.
Dans l’exemple de code précédent, la pourcorps de boucle dans la fonction PrintEndpointNames appelle la méthode IMMDevice ::GetId pour obtenir la chaîne d’ID de point de terminaison pour l’appareil de point de terminaison audio représenté par l’instance d’interface IMMDevice. La chaîne identifie de manière unique l’appareil par rapport à tous les autres appareils de point de terminaison audio du système. Un client peut utiliser la chaîne d’ID de point de terminaison pour créer une instance de l’appareil de point de terminaison audio ultérieurement ou dans un autre processus en appelant la méthode IMMDeviceEnumerator ::GetDevice. Les clients doivent traiter le contenu de la chaîne d’ID de point de terminaison comme opaque. Autrement dit, les clients ne doivent pas tenter d’analyser le contenu de la chaîne pour obtenir des informations sur l’appareil. La raison est que le format de chaîne n’est pas défini et peut passer d’une implémentation de l’API MMDevice à la suivante.
Les noms d’appareils conviviaux et les chaînes d’ID de point de terminaison obtenues par la fonction PrintEndpointNames dans l’exemple de code précédent sont identiques aux noms d’appareils conviviaux et aux chaînes d’ID de point de terminaison fournies par DirectSound pendant l’énumération de l’appareil. Pour plus d’informations, consultez événements audio pour les applications audio héritées.
Dans l’exemple de code précédent, la fonction PrintEndpointNames appelle la fonction CoCreateInstance pour créer un énumérateur pour les appareils de point de terminaison audio du système. Sauf si le programme appelant a appelé précédemment la fonction CoInitialize ou Fonction CoInitializeEx pour initialiser la bibliothèque COM, l’appel CoCreateInstance échoue. Pour plus d’informations sur CoCreateInstance, CoInitializeet CoInitializeEx, consultez la documentation du KIT de développement logiciel (SDK) Windows.
Pour plus d’informations sur l'IMMDeviceEnumerator, IMMDeviceCollectionet les interfaces IMMDevice, consultez 'API MMDevice.