> ## 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 接口

> IAudioStateMonitor 接口

# IAudioStateMonitor 接口

提供各种方法,让桌面应用和游戏能够发现其音频流的音量级别何时被系统修改。这包括以下场景:

* 当音频应用在后台播放时,得知游戏媒体流何时被静音;或
* 当 VOIP 通话在后台开始时,得知何时应停止游戏聊天音频流。

提供各种方法,让桌面应用和游戏能够确定其音频流的音量级别何时被系统修改。这包括以下场景:游戏或应用需要确定以下信息:

* 因音频应用在后台播放而游戏媒体流被静音的时间点
* 因 VoIP 通话在后台开始而应停止游戏聊天音频流的时间点

可以对呈现流和捕获流的音量级别进行检查和监视。可按类别、音频终结点或设备角色来选择要监视的流。可在创建新流之前先检查该流将具有的音量级别。

此 API 等同于 [Windows.Media.Audio.AudiostateMonitor 类](https://learn.microsoft.com/uwp/api/windows.media.audio.audiostatemonitor);该类可供 UWP 应用使用,但不适用于桌面应用和游戏。UWP 应用无法使用此接口。

## Members

**IAudioStateMonitor** 接口继承自 [IUnknown](https://learn.microsoft.com/windows/desktop/api/unknwn/nn-unknwn-iunknown) 接口,同时还具有以下类型的成员:

### Methods

**IAudioStateMonitor** 接口具有以下方法:

| 方法                                                                                                        | 说明                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| [GetSoundLevel](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-getsoundlevel)           | 获取与 **IAudioStateMonitor** 关联的流的当前音量级别                                                                                                 |
| [RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback)     | 注册一个回调函数;当与 **IAudioStateMonitor** 关联的流的音频级别发生变化时,系统将调用该函数                                                                             |
| [UnregisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-unregistercallback) | 注销之前通过 [IAudioStateMonitor::RegisterCallback](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor-registercallback) 注册的回调 |

## Remarks

若要获取此接口的实例,请调用下列方法之一:

* [CreateCaptureAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitor)
* [CreateCaptureAudioStateMonitorForCategory](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategory)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceId](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddeviceid)
* [CreateCaptureAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddevicerole)
* [CreateRenderAudioStateMonitor](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitor)
* [CreateRenderAudioStateMonitorForCategory](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategory)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceId](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddeviceid)
* [CreateRenderAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddevicerole)

以下示例代码演示了这样一个场景:游戏为其 [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) 类别中的音频呈现流注册音频级别通知。

如果此类别的音量级别为静音,则游戏将停止播放其游戏媒体流。如果音量级别设为任何其他值,则播放该游戏媒体流。

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

// Returns true if the GameMedia stream is to be disabled, false if it's to 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 whether the GameMedia stream is to be enabled.
        bool disableGameMediaStream = IsSoundLevelMuted(g_audioStateMonitor.get());

        // Here, add code that enables or disables the GameMedia stream 
        // according to 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, &amp;g_registration);
        }
    }

    if (FAILED(hr))
    {
        // g_audioStateMonitor is a smart pointer, so if an IAudioStateMonitor 
        // was allocated, then setting the smart pointer to null invokes the
        // Release method, which will decrement its usage count and ensure that 
        // the object is destroyed properly.
        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
        // will invoke 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 
    // according to the value of the Boolean.
}
```

## Requirements

**头文件:** Audiostatemonitorapi.h

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

## See also

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