> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IAudioStateMonitor::RegisterCallback method

> IAudioStateMonitor::RegisterCallback method

# IAudioStateMonitor::RegisterCallback method

Registers a callback function that the system will call when the audio level of the streams that are associated with the [IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) changes.

## Syntax

```cpp theme={null}
HRESULT RegisterCallback(
  AudioStateMonitorCallback *callback,
  void *context,
  [out] AudioStateMonitorRegistration *registration
);
```

### Parameters

*callback*\
Type: AudioStateMonitorCallback\*

A pointer to the callback function that is called by the system when there is a change in the audio level of the streams associated with  [IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor).

*context*\
Type: void\*

A pointer to the app-defined context data that will be passed into the function specified in the *callback* parameter.

*registration* \[out]\
Type: AudioStateMonitorRegistration\*

A 64-bit integer that identifies the callback registration. To unregister the function specified in the *callback* parameter, pass this value into [IAudioStateMonitor::UnregisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback).

### Return value

Type: HRESULT

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.

| Return code                             | Description                                  |
| --------------------------------------- | -------------------------------------------- |
| <dl> <dt> **E\_OUTOFMEMORY**</dt> </dl> | The provided callback pointer is null.<br /> |

## Remarks

Consider the following scenario, where a game chooses to play GameMedia audio only when it is known that the audio will not be muted by the OS due to policy. In order to achieve this, the game registers for SoundLevel notifications for the [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) stream category on the default console endpoint. If the SoundLevel for this category is set to 'Muted' then the game will stop playback of its GameMedia stream. If the SoundLevel is set to anything else, the game chooses to play its GameMedia stream.

```cpp theme={null}
// global variables 
winrt::com_ptr<IAudioStateMonitor> g_audioStateMonitor; 
AudioStateMonitorRegistrationHandle g_registration = 0; 

// Returns true if the GameMedia stream should be disabled, false if it should be 
// enabled. 
bool IsSoundLevelMuted(_In_ IAudioStateMonitor* audioStateMonitor) 
{ 
return (audioStateMonitor->GetSoundLevel() == AudioStateMonitorSoundLevel::Muted); 
} 

HRESULT StartTrackingSoundLevel() 
{ 
// Create an AudioStateMonitor and register for callbacks from it. 
HRESULT hr = RegisterForSoundLevelChanges(); 
if (SUCCEEDED(hr)) 
{ 
// Check the current sound level and determine if the GameMedia stream should 
// be enabled. 
bool disableGameMediaStream = IsSoundLevelMuted(g_audioStateMonitor.get()); 

// Add code here that enables or disables the GameMedia stream based on the 
// value of the boolean. 
} 
return hr; 
} 

HRESULT RegisterForSoundLevelChanges() 
{ 
HRESULT hr = S_OK; 

// Create a new AudioStateMonitor for the GameMedia category, if needed, and 
// register for callbacks. 
if (m_audioStateMonitor == nullptr) 
{ 
hr = CreateRenderAudioStateMonitorForCategoryAndDeviceRole( 
AudioCategory_GameMedia, ERole::eConsole, g_audioStateMonitor.put()); 
if (SUCCEEDED(hr)) 
{ 
// Optional "context" parameter is not used in this example, 
// and is set to nullptr. 
hr = g_audioStateMonitor->RegisterCallback(OnAudioStateMonitorCallback, nullptr, &g_registration); 
} 
} 

if (FAILED(hr)) 
{ 
// g_audioStateMonitor is a smart pointer, so if an IAudioStateMonitor was 
// allocated, setting the smart pointer to null invokes the Release method 
// which will decrement its usage count and ensure that the object is properly 
// destroyed. 
g_audioStateMonitor = nullptr; 
} 
return hr; 
} 

// Unregister callbacks on program shutdown 
void UnregisterForSoundLevelChanges() 
{ 
if (g_audioStateMonitor != nullptr) 
{ 
if (g_registration) 
{ 
g_audioStateMonitor->UnregisterCallback(g_registration); 
} 

// g_audioStateMonitor is a smart pointer, so setting it to null 
// invokes the Release method to decrement its usage count. 
g_audioStateMonitor = nullptr; 
} 
} 

void OnAudioStateMonitorCallback(_In_ IAudioStateMonitor* audioStateMonitor, _In_opt_ void* context) 
{ bool disableGameMediaStream = IsSoundLevelMuted(audioStateMonitor); 

// Add code here that enables or disables the GameMedia stream based on the value 
// of the boolean. 
} 
```

## Requirements

**Header:** Audiostatemonitorapi.h

**Supported platforms:** Windows, XBOX One family consoles and XBOX Series consoles

## See also

[IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor)

[About WASAPI](https://learn.microsoft.com/windows/desktop/CoreAudio/wasapi)


## Related topics

- [IAudioStateMonitor::UnregisterCallback method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback.md)
- [IAudioStateMonitor::GetSoundLevel method](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel.md)
- [IAudioStateMonitor interface](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [AudioStateMonitorRegistrationHandle](/reference/audio/audiostatemonitor/types/audiostatemonitorregistrationhandle.md)
- [AudioStateMonitor](/reference/audio/audiostatemonitor/audiostatemonitor_members.md)