Método IMMDevice::Activate (mmdeviceapi.h)

Artigo
03/15/2023

O método Activate cria um objeto COM com a interface especificada.

Sintaxe

HRESULT Activate(
  [in]  REFIID      iid,
  [in]  DWORD       dwClsCtx,
  [in]  PROPVARIANT *pActivationParams,
  [out] void        **ppInterface
);

Parâmetros

[in] iid

O identificador de interface. Esse parâmetro é uma referência a um GUID que identifica a interface que as solicitações de chamador são ativadas. O chamador usará essa interface para se comunicar com o objeto COM. Defina esse parâmetro como um dos seguintes identificadores de interface:

IID_IAudioClient

IID_IAudioEndpointVolume

IID_IAudioMeterInformation

IID_IAudioSessionManager

IID_IAudioSessionManager2

IID_IBaseFilter

IID_IDeviceTopology

IID_IDirectSound

IID_IDirectSound8

IID_IDirectSoundCapture

IID_IDirectSoundCapture8

IID_IMFTrustedOutput

IID_ISpatialAudioClient

IID_ISpatialAudioMetadataClient

Para obter mais informações, consulte Comentários.

[in] dwClsCtx

O contexto de execução no qual o código que gerencia o objeto recém-criado será executado. O chamador pode restringir o contexto definindo esse parâmetro para o OR bit a bit de um ou mais valores de enumeração CLSCTX . Como alternativa, o cliente pode evitar impor restrições de contexto especificando CLSCTX_ALL. Para obter mais informações sobre CLSCTX, consulte a documentação do SDK do Windows.

[in] pActivationParams

Defina como NULL para ativar uma interface IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager ou IDeviceTopology em um dispositivo de ponto de extremidade de áudio. Ao ativar uma interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 no dispositivo, o chamador pode especificar um ponteiro para uma estrutura PROPVARIANT que contém informações de inicialização de fluxo. Para obter mais informações, consulte Comentários.

[out] ppInterface

Ponteiro para uma variável de ponteiro na qual o método grava o endereço da interface especificada pelo parâmetro iid. Por meio desse método, o chamador obtém uma referência contada à interface . O chamador é responsável por liberar a interface, quando ela não é mais necessária, chamando o método Release da interface. Se a chamada Ativar falhar, *ppInterface será NULL.

Retornar valor

Se o método for bem-sucedido, retornará S_OK. Se falhar, os códigos de retorno possíveis incluem, mas não se limitam a, os valores mostrados na tabela a seguir.

Código de retorno	Descrição
E_NOINTERFACE	O objeto não dá suporte ao tipo de interface solicitado.
E_POINTER	O parâmetro ppInterface é NULL.
E_INVALIDARG	O parâmetro pActivationParams deve ser NULL para a interface especificada; ou pActivationParams aponta para dados inválidos.
E_OUTOFMEMORY	Sem memória.
AUDCLNT_E_DEVICE_INVALIDATED	O usuário removeu o dispositivo de ponto de extremidade de áudio ou o dispositivo adaptador ao qual o dispositivo de ponto de extremidade se conecta.

Comentários

Esse método cria um objeto COM com uma interface especificada pelo parâmetro iid . O método é semelhante à função CoCreateInstance do Windows, exceto que o chamador não fornece um CLSID como um parâmetro. Para obter mais informações sobre CoCreateInstance, consulte a documentação SDK do Windows.

Um cliente pode chamar o método Activate da interface IMMDevice para um dispositivo de ponto de extremidade de áudio específico para obter uma referência contada a uma interface nesse dispositivo. O método pode ativar as seguintes interfaces:

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
Ibasefilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
IMFTrustedOutput

Para obter a ID da interface de uma interface, use o operador __uuidof . Por exemplo, a ID da interface de IAudioCaptureClient é definida da seguinte maneira:


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Para obter informações sobre o operador __uuidof, consulte a documentação do SDK do Windows. Para obter informações sobre IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8 e IMFTrustedOutput, consulte a documentação do SDK do Windows.

O parâmetro pActivationParams deve ser NULL para uma chamada Ativar para criar uma interface IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager ou IDeviceTopology para um dispositivo de ponto de extremidade de áudio.

Para uma chamada Ativar para criar uma interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 , o chamador pode, como opção, especificar um valor não NULL para pActivationParams. Nesse caso, pActivationParams aponta para uma estrutura PROPVARIANT que contém informações de inicialização de fluxo. Defina o membro vt da estrutura como VT_BLOB. Defina o membro blob.pBlobData para apontar para uma estrutura DIRECTX_AUDIO_ACTIVATION_PARAMS que contém um GUID de sessão de áudio e sinalizadores de inicialização de fluxo. Defina o membro blob.cbSize como sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Para obter um exemplo de código, consulte Funções de dispositivo para aplicativos DirectShow. Para obter mais informações sobre PROPVARIANT, consulte a documentação do SDK do Windows.

Uma instância de interface IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture ou IDirectSoundCapture8 criada pelo método Activate encapsula um fluxo no dispositivo de ponto de extremidade de áudio. Durante a chamada Ativar , o módulo do sistema DirectSound cria o fluxo chamando o método IAudioClient::Initialize . Se pActivationParams não for NULL, o DirectSound fornecerá o GUID da sessão de áudio e os sinalizadores de inicialização de fluxo da estrutura DIRECTX_AUDIO_ACTIVATION_PARAMS como parâmetros de entrada para a chamada Initialize . Se pActivationParams for NULL, DirectSound definirá os parâmetros AudioSessionGuid e StreamFlags do método Initialize como seus respectivos valores padrão, NULL e 0. Esses valores instruem o método a atribuir o fluxo à sessão específica do processo identificada pelo valor guid da sessão GUID_NULL.

Ativar pode ativar uma interface IDirectSound ou IDirectSound8 somente em um dispositivo de ponto de extremidade de renderização. Ele pode ativar uma interface IDirectSoundCapture ou IDirectSoundCapture8 somente em um dispositivo de ponto de extremidade de captura. Uma chamada Ativar para ativar uma interface IDirectSound ou IDirectSoundCapture8 em um dispositivo de captura ou uma interface IDirectSoundCapture ou IDirectSoundCapture8 em um dispositivo de renderização falha e retorna código de erro E_NOINTERFACE.

No Windows 7, um cliente pode chamar IMMDevice::Activate e especificar, IID_IMFTrustedOutput, para criar um objeto OTA (autoridades de confiança de saída) e recuperar um ponteiro para a interface IMFTrustedOutput do objeto. Os OTAs podem operar dentro ou fora do PMP (caminho de mídia protegido) da Media Foundation e enviar conteúdo fora do pipeline do Media Foundation. Se o chamador estiver fora do PMP, o OTA poderá não operar no PMP e as configurações de proteção serão menos robustas. Para obter informações sobre como usar objetos protegidos para áudio e código de exemplo, consulte PUMA (Áudio do Modo de Usuário Protegido).

Para obter informações gerais sobre objetos protegidos e IMFTrustedOutput, consulte "Caminho da mídia protegida" na documentação do Media Foundation.

Nota Ao usar as interfaces ISpatialAudioClient em um título do XDK (Xbox One Development Kit), você deve primeiro chamar EnableSpatialAudio antes de chamar IMMDeviceEnumerator::EnumAudioEndpoints ou IMMDeviceEnumerator::GetDefaultAudioEndpoint. A falha ao fazer isso resultará em um erro de E_NOINTERFACE sendo retornado da chamada para Ativar. EnableSpatialAudio só está disponível para títulos XDK e não precisa ser chamado para Plataforma Universal do Windows aplicativos em execução no Xbox One, nem para nenhum dispositivo não Xbox One.

Para obter exemplos de código que chamam o método Activate , consulte os seguintes tópicos:

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	mmdeviceapi.h