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

  • Artículo

El método Activate crea un objeto COM con la interfaz especificada.

Sintaxis

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

Parámetros

[in] iid

Identificador de interfaz. Este parámetro es una referencia a un GUID que identifica la interfaz que solicita el autor de la llamada. El autor de la llamada usará esta interfaz para comunicarse con el objeto COM. Establezca este parámetro en uno de los siguientes identificadores de interfaz:

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 obtener más información, vea la sección Comentarios.

[in] dwClsCtx

Contexto de ejecución en el que se ejecutará el código que administra el objeto recién creado. El autor de la llamada puede restringir el contexto estableciendo este parámetro en el OR bit a bit de uno o varios valores de enumeración CLSCTX . Como alternativa, el cliente puede evitar imponer restricciones de contexto especificando CLSCTX_ALL. Para obtener más información sobre CLSCTX, consulte la documentación de Windows SDK.

[in] pActivationParams

Se establece en NULL para activar una interfaz IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager o IDeviceTopology en un dispositivo de punto de conexión de audio. Al activar una interfaz IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture o IDirectSoundCapture8 en el dispositivo, el autor de la llamada puede especificar un puntero a una estructura PROPVARIANT que contiene información de inicialización de flujo. Para obtener más información, vea la sección Comentarios.

[out] ppInterface

Puntero a una variable de puntero en la que el método escribe la dirección de la interfaz especificada por el parámetro iid. A través de este método, el autor de la llamada obtiene una referencia contada a la interfaz . El autor de la llamada es responsable de liberar la interfaz, cuando ya no es necesario, llamando al método Release de la interfaz. Si se produce un error en la llamada Activate , *ppInterface es NULL.

Valor devuelto

Si el método se realiza correctamente, devuelve S_OK. Si se produce un error, los códigos de retorno posibles incluyen, entre otros, los valores que se muestran en la tabla siguiente.

Código devuelto Descripción
E_NOINTERFACE
 El objeto no admite el tipo de interfaz solicitado.
E_POINTER
 El parámetro ppInterface es NULL.
E_INVALIDARG
 El parámetro pActivationParams debe ser NULL para la interfaz especificada; o pActivationParams apunta a datos no válidos.
E_OUTOFMEMORY
 Memoria insuficiente
AUDCLNT_E_DEVICE_INVALIDATED
 El usuario ha quitado el dispositivo de punto de conexión de audio o el dispositivo de adaptador al que se conecta el dispositivo de punto de conexión.

Comentarios

Este método crea un objeto COM con una interfaz especificada por el parámetro iid . El método es similar a la función Windows CoCreateInstance , salvo que el autor de la llamada no proporciona un CLSID como parámetro. Para obtener más información sobre CoCreateInstance, consulte la documentación de Windows SDK.

Un cliente puede llamar al método Activate de la interfaz IMMDevice para un dispositivo de punto de conexión de audio determinado para obtener una referencia contada a una interfaz en ese dispositivo. El método puede activar las siguientes interfaces:

Para obtener el identificador de interfaz de una interfaz, use el operador __uuidof . Por ejemplo, el identificador de interfaz de IAudioCaptureClient se define de la siguiente manera:

const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Para obtener información sobre el operador __uuidof, consulte la documentación de Windows SDK. Para obtener información sobre IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8 y IMFTrustedOutput, consulte la documentación de Windows SDK.

El parámetro pActivationParams debe ser NULL para una llamada Activate para crear una interfaz IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager o IDeviceTopology para un dispositivo de punto de conexión de audio.

Para una llamada Activate para crear una interfaz IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture o IDirectSoundCapture8, el autor de la llamada puede, como opción, especificar un valor no NULL para pActivationParams. En este caso, pActivationParams apunta a una estructura PROPVARIANT que contiene información de inicialización de flujo. Establezca el miembro vt de la estructura en VT_BLOB. Establezca el miembro blob.pBlobData para que apunte a una estructura de DIRECTX_AUDIO_ACTIVATION_PARAMS que contiene un GUID de sesión de audio y marcas de inicialización de secuencias. Establezca el miembro blob.cbSize en sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). Para obtener un ejemplo de código, consulte Roles de dispositivo para aplicaciones directShow. Para obtener más información sobre PROPVARIANT, consulte la documentación de Windows SDK.

Una instancia de interfaz IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture o IDirectSoundCapture8 creada por el método Activate encapsula una secuencia en el dispositivo de punto de conexión de audio. Durante la llamada Activate , el módulo del sistema DirectSound crea la secuencia llamando al método IAudioClient::Initialize . Si pActivationParams no es NULL, DirectSound proporciona el GUID de sesión de audio y las marcas de inicialización de secuencia de la estructura DIRECTX_AUDIO_ACTIVATION_PARAMS como parámetros de entrada a la llamada Initialize . Si pActivationParams es NULL, DirectSound establece los parámetros AudioSessionGuid y StreamFlags del método Initialize en sus respectivos valores predeterminados, NULL y 0. Estos valores indican al método que asigne la secuencia a la sesión específica del proceso identificada por el valor de GUID de sesión GUID_NULL.

Activar puede activar una interfaz IDirectSound o IDirectSound8 solo en un dispositivo de extremo de representación. Puede activar una interfaz IDirectSoundCapture o IDirectSoundCapture8 solo en un dispositivo de punto de conexión de captura. Se produce un error en una llamada Activate para activar una interfaz IDirectSound o IDirectSoundCapture8 en un dispositivo de captura o una interfaz IDirectSoundCapture o IDirectSoundCapture8 en un dispositivo de representación y se devuelve el código de error E_NOINTERFACE.

En Windows 7, un cliente puede llamar a IMMDevice::Activate y especificar, IID_IMFTrustedOutput, para crear un objeto de autoridades de confianza de salida (OTA) y recuperar un puntero a la interfaz IMFTrustedOutput del objeto. Los OTA pueden funcionar dentro o fuera de la ruta de acceso de medios protegida (PMP) de Media Foundation y enviar contenido fuera de la canalización de Media Foundation. Si el autor de la llamada está fuera de PMP, es posible que el OTA no funcione en el PMP y la configuración de protección sea menos sólida. Para obtener información sobre el uso de objetos protegidos para el audio y el código de ejemplo, vea Audio en modo de usuario protegido (PUMA).

Para obtener información general sobre los objetos protegidos y IMFTrustedOutput, vea "Ruta de acceso a medios protegidas" en la documentación de Media Foundation.

Nota Al usar las interfaces ISpatialAudioClient en un título del Kit de desarrollo de Xbox One (XDK), primero debes llamar a EnableSpatialAudio antes de llamar a IMMDeviceEnumerator::EnumAudioEndpoints o IMMDeviceEnumerator::GetDefaultAudioEndpoint. Si no lo hace, se producirá un error de E_NOINTERFACE que se devuelve de la llamada a Activate. EnableSpatialAudio solo está disponible para los títulos XDK y no es necesario llamar a para Plataforma universal de Windows aplicaciones que se ejecutan en Xbox One ni para ningún dispositivo que no sea Xbox One.
 
Para obtener ejemplos de código que llaman al método Activate , consulte los temas siguientes:

Requisitos

Requisito Value
Cliente mínimo compatible Windows Vista [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado mmdeviceapi.h

Consulte también

IAudioClient (interfaz)

IAudioEndpointVolume (interfaz)

IAudioMeterInformation (interfaz)

Interfaz IAudioSessionManager

IDeviceTopology (Interfaz)

IMMDevice (Interfaz)