Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

IMMDevice::Activate method

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

Syntax


HRESULT Activate(
  [in]   REFIID iid,
  [in]   DWORD dwClsCtx,
  [in]   PROPVARIANT *pActivationParams,
  [out]  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_IAudioSessionManager2

IID_IBaseFilter

IID_IDeviceTopology

IID_IDirectSound

IID_IDirectSound8

IID_IDirectSoundCapture

IID_IDirectSoundCapture8

IID_IMFTrustedOutput

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 codeDescription
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:

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, IDirectSoundCapture8, and IMFTrustedOutput 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 IDirectSoundCapture8 interface on a capture device or an IDirectSoundCapture or IDirectSoundCapture8 interface on a rendering device fails and returns error code E_NOINTERFACE.

In Windows 7, a client can call IMMDevice::Activate and specify, IID_IMFTrustedOutput, to create an output trust authorities (OTA) object and retrieve a pointer to the object's IMFTrustedOutput interface. OTAs can operate inside or outside the Media Foundation's protected media path (PMP) and send content outside the Media Foundation pipeline. If the caller is outside PMP, then the OTA may not operate in the PMP, and the protection settings are less robust. For information about using protected objects for audio and example code, see Protected User Mode Audio (PUMA).

For general information about protected objects and IMFTrustedOutput, see "Protected Media Path" in Media Foundation documentation.

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

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Mmdeviceapi.h

See also

IAudioClient Interface
IAudioEndpointVolume Interface
IAudioMeterInformation Interface
IAudioSessionManager Interface
IDeviceTopology Interface
IMMDevice Interface

 

 

Community Additions

Show:
© 2014 Microsoft