Share via

IMMDevice::Activate

  • Article
Previous Next

IMMDevice::Activate

The Activate method creates a COM object with the specified interface.

HRESULT Activate(
  REFIID  iid,
  DWORD  dwClsCtx,
  PROPVARIANT  *pActivationParams,
  void  **ppInterface
);

Parameters

iid

[in]  The interface identifier. This parameter is a reference to a GUID that identifies the interface that the caller requests be activated. The caller will use this interface to communicate with the COM object. Set this parameter to one of the following interface identifiers:

IID_IAudioClient

IID_IAudioEndpointVolume

IID_IAudioMeterInformation

IID_IAudioSessionManager

IID_IBaseFilter

IID_IDeviceTopology

IID_IDirectSound

IID_IDirectSound8

IID_IDirectSoundCapture

IID_IDirectSoundCapture8

For more information, see Remarks.

dwClsCtx

[in]  The execution context in which the code that manages the newly created object will run. The caller can restrict the context by setting this parameter to the bitwise OR of one or more CLSCTX enumeration values. Alternatively, the client can avoid imposing any context restrictions by specifying CLSCTX_ALL. For more information about CLSCTX, see the Windows SDK documentation.

pActivationParams

[in]  Set to NULL to activate an IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or IDeviceTopology interface on an audio endpoint device. When activating an IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 interface on the device, the caller can specify a pointer to a PROPVARIANT structure that contains stream-initialization information. For more information, see Remarks.

ppInterface

[out]  Pointer to a pointer variable into which the method writes the address of the interface specified by parameter iid. Through this method, the caller obtains a counted reference to the interface. The caller is responsible for releasing the interface, when it is no longer needed, by calling the interface's Release method. If the Activate call fails, *ppInterface is NULL.

Return Value

If the method succeeds, it returns S_OK. If it fails, possible return codes include, but are not limited to, the values shown in the following table.

Return code Description
E_NOINTERFACE The object does not support the requested interface type.
E_POINTER Parameter ppInterface is NULL.
E_INVALIDARG The pActivationParams parameter must be NULL for the specified interface; or pActivationParams points to invalid data.
E_OUTOFMEMORY Out of memory.
AUDCLNT_E_DEVICE_INVALIDATED The user has removed either the audio endpoint device or the adapter device that the endpoint device connects to.

Remarks

This method creates a COM object with an interface that is specified by the iid parameter. The method is similar to the Windows CoCreateInstance function, except that the caller does not supply a CLSID as a parameter. For more information about CoCreateInstance, see the Windows SDK documentation.

A client can call the Activate method of the IMMDevice interface for a particular audio endpoint device to obtain a counted reference to an interface on that device. The method can activate the following interfaces:

  • IAudioClient
  • IAudioEndpointVolume
  • IAudioMeterInformation
  • IAudioSessionManager
  • IBaseFilter
  • IDeviceTopology
  • IDirectSound
  • IDirectSound8
  • IDirectSoundCapture
  • IDirectSoundCapture8

To obtain the interface ID for an interface, use the __uuidof operator. For example, the interface ID of IAudioCaptureClient is defined as follows:

const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

For information about the __uuidof operator, see the Windows SDK documentation. For information about IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, and IDirectSoundCapture8, see the Windows SDK documentation.

The pActivationParams parameter should be NULL for an Activate call to create an IAudioClient, IAudioEndpointVolume, IAudioMeterInformation, IAudioSessionManager, or IDeviceTopology interface for an audio endpoint device.

For an Activate call to create an IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 interface, the caller can, as an option, specify a non-NULL value for pActivationParams. In this case, pActivationParams points to a PROPVARIANT structure that contains stream-initialization information. Set the vt member of the structure to VT_BLOB. Set the blob.pBlobData member to point to a DIRECTX_AUDIO_ACTIVATION_PARAMS structure that contains an audio session GUID and stream-initialization flags. Set the blob.cbSize member to sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS). For a code example, see Device Roles for DirectShow Applications. For more information about PROPVARIANT, see the Windows SDK documentation.

An IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, or IDirectSoundCapture8 interface instance that is created by the Activate method encapsulates a stream on the audio endpoint device. During the Activate call, the DirectSound system module creates the stream by calling the IAudioClient::Initialize method. If pActivationParams is non-NULL, DirectSound supplies the audio session GUID and stream-initialization flags from the DIRECTX_AUDIO_ACTIVATION_PARAMS structure as input parameters to the Initialize call. If pActivationParams is NULL, DirectSound sets the Initialize method's AudioSessionGuid and StreamFlags parameters to their respective default values, NULL and 0—these values instruct the method to assign the stream to the process-specific session that is identified by the session GUID value GUID_NULL.

Activate can activate an IDirectSound or IDirectSound8 interface only on a rendering endpoint device. It can activate an IDirectSoundCapture or IDirectSoundCapture8 interface only on a capture endpoint device. An Activate call to activate an IDirectSound or IDirectSound8 interface on a capture device or an IDirectSoundCapture or IDirectSoundCapture8 interface on a rendering device fails and returns error code E_NOINTERFACE.

For code examples that call the Activate method, see the following topics:

Requirements

Client: Windows Vista

Header: Include Mmdeviceapi.h.

See Also

Previous Next