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

# CreateRenderAudioStateMonitorForCategoryAndDeviceRole

> CreateRenderAudioStateMonitorForCategoryAndDeviceRole

# CreateRenderAudioStateMonitorForCategoryAndDeviceRole

\[Algumas informações estão relacionadas a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento comercial. A Microsoft não oferece garantias, expressas ou implícitas, com relação às informações fornecidas aqui.]

Cria uma nova instância de [IAudioStateMonitor](/pt-BR/reference/audio/audiostatemonitor/interfaces/iaudiostatemonitor) que monitora o nível de áudio de todos os fluxos de renderização de áudio na categoria especificada e com a função especificada.

## Sintaxe

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

### Parâmetros

*category*\
Tipo: AUDIO\_STREAM\_CATEGORY

Um membro da enumeração <a href="https://learn.microsoft.com/en-us/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category" target="_blank">AUDIO\_STREAM\_CATEGORY</a> que especifica a categoria dos fluxos de renderização de áudio a serem monitorados.

*role*\
Tipo: ERole

Um membro da enumeração <a href="https://learn.microsoft.com/en-us/windows/desktop/api/mmdeviceapi/ne-mmdeviceapi-erole" target="_blank">ERole</a> que especifica a função dos fluxos de renderização de áudio a serem monitorados.

*audioStateMonitor* \_Out\_\
Tipo: IAudioStateMonitor\*\*

Esse parâmetro de saída é preenchido com o objeto `IAudioStateMonitor` criado.

### Valor de retorno

Se o método for bem-sucedido, ele retornará `S\_OK`.

## Comentários

Esta é uma das funções que criam e retornam uma instância de AudioStateMonitor.

Há quatro variantes para fluxos de captura e para fluxos de renderização que determinam se um processo pode realizar uma das seguintes ações para uma determinada função:

* Capturar ou renderizar qualquer áudio de qualquer categoria
* Capturar ou renderizar áudio de uma categoria específica
* Capturar ou renderizar áudio de uma categoria específica, para um ponto de extremidade específico\
  O ponto de extremidade pode ser especificado usando a ID `MMDevice` (obtida usando `IMMDevice::GetId()`) ou usando a ID `SWD` dele (obtida usando `Windows.Devices.Enumeration` ou `Windows.Media.Devices.MediaDevice`)
* Capturar ou renderizar áudio de uma categoria específica para o ponto de extremidade padrão

Considere o cenário a seguir, em que um jogo opta por reproduzir áudio GameMedia somente quando se sabe que o áudio não será silenciado pelo sistema operacional devido a uma política. Para isso, o jogo se registra para receber notificações de SoundLevel para a categoria de fluxo [AudioCategory\_GameMedia](https://learn.microsoft.com/windows/desktop/api/audiosessiontypes/ne-audiosessiontypes-audio_stream_category) no ponto de extremidade de console padrão. Se o SoundLevel dessa categoria estiver definido como 'Muted', o jogo interromperá a reprodução do fluxo GameMedia. Se o SoundLevel estiver definido como qualquer outro valor, o jogo optará por reproduzir o fluxo 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. 
} 
```

## Requisitos

**Cabeçalho:** Audiostatemonitorapi.h

**Biblioteca:** Windows.Media.MediaControl.lib

**Plataformas compatíveis:** Windows, consoles da família XBOX One e consoles XBOX Series

## Confira também

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

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

[WASAPI](/pt-BR/build/console-features/audio/overviews/wasapi-overview)

[Visão geral do áudio](/pt-BR/build/console-features/audio/overviews/audio)


## Related topics

- [CreateRenderAudioStateMonitorForCategoryAndDeviceRole](/reference/audio/audiostatemonitor/functions/createrenderaudiostatemonitorforcategoryanddevicerole.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)