> ## 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 方法

> IAudioStateMonitor::RegisterCallback 方法

# IAudioStateMonitor::RegisterCallback 方法

注册一个回调函数;当与 [IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) 关联的流的音频级别发生变化时,系统将调用该函数。

## Syntax

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

### Parameters

*callback*\
Type: AudioStateMonitorCallback\*

指向回调函数的指针;当与 [IAudioStateMonitor](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) 关联的流的音频级别发生变化时,系统将调用该函数。

*context*\
Type: void\*

指向应用定义的上下文数据的指针;该数据将被传递给 *callback* 参数指定的函数。

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

一个 64 位整数,用于标识回调注册。若要注销 *callback* 参数指定的函数,请将此值传递给 [IAudioStateMonitor::UnregisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback)。

### Return value

Type: HRESULT

如果方法成功,则返回 S\_OK。如果失败,可能的返回代码包括(但不限于)下表中列出的值。

| 返回代码                                    | 说明                   |
| --------------------------------------- | -------------------- |
| <dl> <dt> **E\_OUTOFMEMORY**</dt> </dl> | 提供的回调指针为 null。<br /> |

## Remarks

请思考以下场景:游戏仅在明确知道操作系统不会因策略而将音频静音时,才选择播放 GameMedia 音频。为此,游戏在默认主机终结点上为 [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) 流类别注册 SoundLevel 通知。如果此类别的 SoundLevel 被设置为 “Muted”,游戏将停止播放其 GameMedia 流;如果 SoundLevel 是其他任何值,游戏将选择播放其 GameMedia 流。

```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

**头文件:** Audiostatemonitorapi.h

**支持的平台:** Windows、XBOX One 系列主机和 XBOX Series 主机

## See also

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

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


## Related topics

- [IAudioStateMonitor::UnregisterCallback 方法](/zh-CN/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback.md)
- [IAudioStateMonitor::GetSoundLevel 方法](/zh-CN/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel.md)
- [IAudioStateMonitor 接口](/zh-CN/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [AudioStateMonitorRegistrationHandle](/zh-CN/reference/audio/audiostatemonitor/types/audiostatemonitorregistrationhandle.md)
- [AudioStateMonitor](/zh-CN/reference/audio/audiostatemonitor/audiostatemonitor_members.md)