The Activate method creates a COM object with the specified interface.
public:
HRESULT Activate(
REFIID iid,
DWORD dwClsCtx,
PROPVARIANT *pActivationParams,
void **ppInterface
)
iid
Type: REFIID
[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_IAudioClient2
IID_ISpatialAudioClient
dwClsCtx
Type: DWORD
[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
Type: PROPVARIANT *
[in, optional]
Set to NULL to activate an IAudioClient or an IAudioClient2 interface on an audio endpoint device.
ppInterface
Type: void **
[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.
Type: HRESULT
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_IN_USE | Returned when this method tries to call the Kinect microphone array, and the title has not declared that it needs access to Kinect audio streams by declaring kinectAudio and kinectGameChat as mx:Capability items. See <mx:Capability> for more information. |
| AUDCLNT_E_DEVICE_INVALIDATED | The user has removed either the audio endpoint device or the adapter device that the endpoint device connects to. |
| E_NOINTERFACE | Activate was called with IID_ISpatialAudioClient specified without calling EnableSpatialAudio. |
Refer to WASAPI error codes.
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 code examples that call the Activate method, see the following topics:
HRESULT hr = (EnableSpatialAudio());
ComPtr<IMMDeviceEnumerator> enumerator;
if (SUCCEEDED(hr))
{
hr = (CoCreateInstance(__uuidof(MMDeviceEnumerator), nullptr, CLSCTX_ALL, __uuidof(IMMDeviceEnumerator), &enumerator));
}
ComPtr<IMMDevice> device;
if (SUCCEEDED(hr))
{
hr = (enumerator->GetDefaultAudioEndpoint(eRender, eConsole, &device));
}
ComPtr<ISpatialAudioClient> client;
if (SUCCEEDED(hr))
{
hr = (device->Activate(__uuidof(ISpatialAudioClient), CLSCTX_ALL, nullptr, &client));
}
Header: Declared in mmdeviceapi.h.
Library: Use MMDevApi.lib.