IAudioSessionControl::SetDisplayName method (audiopolicy.h)

The SetDisplayName method assigns a display name to the current session.

Syntax

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

Parameters

[in] Value

Pointer to a null-terminated, wide-character string that contains the display name for the session.

[in] EventContext

Pointer to the event-context GUID. If a call to this method generates a name-change event, the session manager sends notifications to all clients that have registered IAudioSessionEvents interfaces with the session manager. The session manager includes the EventContext pointer value with each notification. Upon receiving a notification, a client can determine whether it or another client is the source of the event by inspecting the EventContext value. This scheme depends on the client selecting a value for this parameter that is unique among all clients in the session. If the caller supplies a NULL pointer for this parameter, the client's notification method receives a NULL context pointer.

Return value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Remarks

In Windows Vista, the system-supplied program, Sndvol.exe, uses the display name to label the volume control for the session. If the client does not call SetDisplayName to assign a display name to the session, the Sndvol program uses a default, automatically generated name to label the session. The default name incorporates information such as the window title or version resource of the audio application.

If a client has more than one active session, client-specified display names are especially helpful for distinguishing among the volume controls for the various sessions.

In the case of a cross-process session, the session has no identifying information, such as an application name or process ID, from which to generate a default display name. Thus, the client must call SetDisplayName to avoid displaying a meaningless default display name.

The display name does not persist beyond the lifetime of the IAudioSessionControl object. Thus, after all references to the object are released, a subsequently created version of the object (with the same application, same session GUID, and same endpoint device) will once again have a default, automatically generated display name until the client calls SetDisplayName.

The client can retrieve the display name for the session by calling the IAudioSessionControl::GetDisplayName method.

Requirements

See also

IAudioSessionControl Interface

IAudioSessionControl::GetDisplayName

IAudioSessionEvents Interface