Méthode IAudioSessionControl ::SetDisplayName (audiopolicy.h)

Article
08/22/2023

La méthode SetDisplayName affecte un nom d’affichage à la session active.

Syntaxe

HRESULT SetDisplayName(
  [in] LPCWSTR Value,
  [in] LPCGUID EventContext
);

Paramètres

[in] Value

Pointeur vers une chaîne de caractères larges terminée par null qui contient le nom d’affichage de la session.

[in] EventContext

Pointeur vers le GUID de contexte d’événement. Si un appel à cette méthode génère un événement de changement de nom, le gestionnaire de session envoie des notifications à tous les clients qui ont inscrit des interfaces IAudioSessionEvents avec le gestionnaire de sessions. Le gestionnaire de sessions inclut la valeur du pointeur EventContext à chaque notification. Lors de la réception d’une notification, un client peut déterminer s’il ou un autre client est la source de l’événement en inspectant la valeur EventContext . Ce schéma dépend du fait que le client sélectionne une valeur pour ce paramètre qui est unique parmi tous les clients de la session. Si l’appelant fournit un pointeur NULL pour ce paramètre, la méthode de notification du client reçoit un pointeur de contexte NULL .

Valeur retournée

Si la méthode réussit, retourne S_OK. En cas d’échec, les codes de retour possibles incluent, sans s’y limiter, les valeurs indiquées dans le tableau suivant.

Code de retour	Description
E_POINTER	La valeur du paramètre est NULL.
AUDCLNT_E_DEVICE_INVALIDATED	Le périphérique de point de terminaison audio a été débranché, ou le matériel audio ou les ressources matérielles associées ont été reconfigurés, désactivés, supprimés ou autrement rendus indisponibles.
AUDCLNT_E_SERVICE_NOT_RUNNING	Le service audio Windows n’est pas en cours d’exécution.

Remarques

Dans Windows Vista, le programme fourni par le système, Sndvol.exe, utilise le nom complet pour étiqueter le contrôle de volume de la session. Si le client n’appelle pas SetDisplayName pour affecter un nom d’affichage à la session, le programme Sndvol utilise un nom généré automatiquement par défaut pour étiqueter la session. Le nom par défaut intègre des informations telles que le titre de la fenêtre ou la ressource de version de l’application audio.

Si un client a plusieurs sessions actives, les noms d’affichage spécifiés par le client sont particulièrement utiles pour distinguer les contrôles de volume pour les différentes sessions.

Dans le cas d’une session interprocesseur, la session ne dispose d’aucune information d’identification, comme un nom d’application ou un ID de processus, à partir desquelles générer un nom d’affichage par défaut. Par conséquent, le client doit appeler SetDisplayName pour éviter d’afficher un nom d’affichage par défaut sans signification.

Le nom d’affichage ne persiste pas au-delà de la durée de vie de l’objet IAudioSessionControl . Ainsi, une fois toutes les références à l’objet libérées, une version créée par la suite de l’objet (avec la même application, le même GUID de session et le même appareil de point de terminaison) aura à nouveau un nom d’affichage généré automatiquement par défaut jusqu’à ce que le client appelle SetDisplayName.

Le client peut récupérer le nom d’affichage de la session en appelant la méthode IAudioSessionControl ::GetDisplayName .

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	audiopolicy.h

Voir aussi

IAudioSessionControl, interface

IAudioSessionControl ::GetDisplayName

IAudioSessionEvents, interface

Share via