> ## 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.

# CreateCaptureAudioStateMonitorForCategoryAndDeviceRole

> CreateCaptureAudioStateMonitorForCategoryAndDeviceRole

# CreateCaptureAudioStateMonitorForCategoryAndDeviceRole

建立 [IAudioStateMonitor](/zh-TW/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) 的新執行個體，以監視指定類別且具有指定角色之所有音訊擷取串流的音訊層級。

## 語法

```cpp theme={null}
HRESULT WINAPI CreateCaptureAudioStateMonitorForCategoryAndDeviceRole(
  AUDIO_STREAM_CATEGORY category,
  ERole role,
  _Out_ IAudioStateMonitor **audioStateMonitor
);
```

### 參數

*category*\
類型: AUDIO\_STREAM\_CATEGORY

**AUDIO\_STREAM\_CATEGORY** 列舉的成員，指定要監視的音訊擷取串流類別。

*role*\
類型: ERole

<a href="https://learn.microsoft.com/en-us/windows/desktop/api/mmdeviceapi/ne-mmdeviceapi-erole" target="_blank">ERole</a> 列舉的成員，指定要監視的音訊擷取串流角色。

*audioStateMonitor* \_Out\_\
類型: IAudioStateMonitor\*\*

此輸出參數會填入所建立的 `IAudioStateMonitor` 物件。

### 傳回值

如果方法成功，會傳回 `S\_OK`。

## 備註

這是建立並傳回 `AudioStateMonitor` 執行個體的函式之一。

擷取串流和轉譯串流各有四種變化，用來判斷處理序是否能針對指定角色執行下列其中一項：

* 擷取或轉譯任何類別的任何音訊
* 擷取或轉譯特定類別的音訊
* 擷取或轉譯特定類別的音訊，並傳送到特定端點。\
  端點可以使用 `MMDevice` ID (使用 `IMMDevice::GetId()` 取得) 指定，或使用其 `SWD` ID (使用 `Windows.Devices.Enumeration` 或 `Windows.Media.Devices.MediaDevice` 取得) 指定
* 擷取或轉譯特定類別的音訊，並傳送到預設端點

請考慮下列案例：遊戲只有在確知音訊不會因 OS 原則而被靜音時，才會啟用遊戲內的 GameChat 功能。為此，遊戲會在預設通訊端點上，註冊 [AudioCategory\_GameChat](https://learn.microsoft.com/windows/win32/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) 串流類別的 SoundLevel 通知。

如果此類別的 SoundLevel 設定為 'Muted'，遊戲會停止其 GameChat 工作階段。如果 SoundLevel 設定為其他任何值，遊戲會選擇啟用其 GameChat 串流。

下列程式碼範例示範遊戲如何為此案例建立適當的 `IAudioStateMonitor` 物件。

```cpp theme={null}
HRESULT RegisterForSoundLevelChanges() 
{ 
HRESULT hr = S_OK; 

// Create a new AudioStateMonitor for the GameChat category, if needed, and 
// register for callbacks. 
if (m_audioStateMonitor == nullptr) 
{ 
hr = CreateCaptureAudioStateMonitorForCategoryAndDeviceRole( 
AudioCategory_GameChat, ERole::eCommunications, 
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, &m_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; 
} 
```

## 需求

**標頭：** Audiostatemonitorapi.h

**程式庫：** Windows.Media.MediaControl.lib

**支援的平台：** Windows、XBOX One 系列主機和 XBOX Series 主機

## 另請參閱

[AUDIO\_STREAM\_CATEGORY](https://learn.microsoft.com/windows/win32/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category)

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

[WASAPI](/zh-TW/build/console-features/audio/overviews/wasapi-overview)


## Related topics

- [CreateCaptureAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createcaptureaudiostatemonitorforcategoryanddevicerole.md)
- [IAudioStateMonitor interface](/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [AudioStateMonitor](/reference/audio/audiostatemonitor/audiostatemonitor_members.md)
- [Interfaz IAudioStateMonitor](/es/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)
- [IAudioStateMonitor 接口](/zh-CN/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor.md)