Méthode IAudioSessionControl ::SetDisplayName (audiopolicy.h)
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 |
|---|---|
|
La valeur du paramètre est NULL. |
|
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. |
|
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