Método IMMDevice::Activate (mmdeviceapi.h)
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 |
|---|---|
|
O objeto não dá suporte ao tipo de interface solicitado. |
|
O parâmetro ppInterface é NULL. |
|
O parâmetro pActivationParams deve ser NULL para a interface especificada; ou pActivationParams aponta para dados inválidos. |
|
Sem memória. |
|
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
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.
- Renderizando um Stream
- Topologias de dispositivo
- Usando a interface IKsControl para acessar propriedades de áudio
- Eventos de áudio para aplicativos de áudio herdados
- Renderizar som espacial usando objetos de áudio espacial
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 |
Confira também
IAudioEndpointVolume Interface
IAudioMeterInformation Interface
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de