IMMDevice::Activate-Methode (mmdeviceapi.h)

Artikel
03/04/2024

Die Activate-Methode erstellt ein COM-Objekt mit der angegebenen Schnittstelle.

Syntax

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

Parameter

[in] iid

Der Schnittstellenbezeichner. Dieser Parameter ist ein Verweis auf eine GUID, die die Vom Aufrufer angeforderte Schnittstelle identifiziert. Der Aufrufer verwendet diese Schnittstelle, um mit dem COM-Objekt zu kommunizieren. Legen Sie diesen Parameter auf einen der folgenden Schnittstellenbezeichner fest:

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

Weitere Informationen finden Sie in den Hinweisen.

[in] dwClsCtx

Der Ausführungskontext, in dem der Code ausgeführt wird, der das neu erstellte Objekt verwaltet. Der Aufrufer kann den Kontext einschränken, indem er diesen Parameter auf den bitweisen OR eines oder mehrerer CLSCTX-Enumerationswerte festlegt. Alternativ kann der Client kontextbezogene Einschränkungen vermeiden, indem er CLSCTX_ALL angibt. Weitere Informationen zu CLSCTX finden Sie in der Windows SDK-Dokumentation.

[in] pActivationParams

Legen Sie auf NULL fest, um eine IAudioClient-, IAudioEndpointVolume-, IAudioMeterInformation-, IAudioSessionManager- oder IDeviceTopology-Schnittstelle auf einem Audioendpunktgerät zu aktivieren. Beim Aktivieren einer IBaseFilter-, IDirectSound-, IDirectSound8-, IDirectSoundCapture- oder IDirectSoundCapture8-Schnittstelle auf dem Gerät kann der Aufrufer einen Zeiger auf eine PROPVARIANT-Struktur angeben, die Informationen zur Streaminitialisierung enthält. Weitere Informationen finden Sie in den Hinweisen.

[out] ppInterface

Zeiger auf eine Zeigervariable, in die die Methode die Adresse der durch parameter iid angegebenen Schnittstelle schreibt. Mit dieser Methode erhält der Aufrufer einen gezählten Verweis auf die Schnittstelle. Der Aufrufer ist für das Freigeben der Schnittstelle verantwortlich, wenn sie nicht mehr benötigt wird, indem die Release-Methode der Schnittstelle aufgerufen wird. Wenn der Aktivierungsaufruf fehlschlägt, ist *ppInterfaceNULL.

Rückgabewert

Wenn die Methode erfolgreich ist, wird S_OK zurückgegeben. Wenn ein Fehler auftritt, können mögliche Rückgabecodes die in der folgenden Tabelle gezeigten Werte umfassen, sind jedoch nicht darauf beschränkt.

Rückgabecode	Beschreibung
E_NOINTERFACE	Das Objekt unterstützt den angeforderten Schnittstellentyp nicht.
E_POINTER	Der Parameter ppInterface ist NULL.
E_INVALIDARG	Der pActivationParams-Parametermuss null für die angegebene Schnittstelle sein. oder pActivationParams verweist auf ungültige Daten.
E_OUTOFMEMORY	Nicht genügend Arbeitsspeicher.
AUDCLNT_E_DEVICE_INVALIDATED	Der Benutzer hat entweder das Audioendpunktgerät oder das Adaptergerät entfernt, mit dem das Endpunktgerät eine Verbindung herstellt.

Hinweise

Diese Methode erstellt ein COM-Objekt mit einer Schnittstelle, die durch den iid-Parameter angegeben wird. Die Methode ähnelt der Windows CoCreateInstance-Funktion , mit der Ausnahme, dass der Aufrufer keine CLSID als Parameter bereitstellt. Weitere Informationen zu CoCreateInstance finden Sie in der Windows SDK-Dokumentation.

Ein Client kann die Activate-Methode der IMMDevice-Schnittstelle für ein bestimmtes Audioendpunktgerät aufrufen, um einen gezählten Verweis auf eine Schnittstelle auf diesem Gerät abzurufen. Die -Methode kann die folgenden Schnittstellen aktivieren:

IAudioClient
IAudioEndpointVolume
IAudioMeterInformation
IAudioSessionManager
IAudioSessionManager2
IBaseFilter
IDeviceTopology
IDirectSound
IDirectSound8
IDirectSoundCapture
IDirectSoundCapture8
IMFTrustedOutput

Verwenden Sie den Operator __uuidof , um die Schnittstellen-ID für eine Schnittstelle abzurufen. Die Schnittstellen-ID von IAudioCaptureClient ist beispielsweise wie folgt definiert:


const IID IID_IAudioClient  __uuidof(IAudioCaptureClient)

Informationen zum __uuidof-Operator finden Sie in der Windows SDK-Dokumentation. Informationen zu IBaseFilter, IDirectSound, IDirectSound8, IDirectSoundCapture, IDirectSoundCapture8 und IMFTrustedOutput finden Sie in der Windows SDK-Dokumentation.

Der pActivationParams-Parameter sollte null für einen Activate-Aufruf sein, um eine IAudioClient-, IAudioEndpointVolume-, IAudioMeterInformation-, IAudioSessionManager- oder IDeviceTopology-Schnittstelle für ein Audioendpunktgerät zu erstellen.

Für einen Activate-Aufruf zum Erstellen einer IBaseFilter-, IDirectSound8-, IDirectSoundCapture- oder IDirectSoundCapture8-Schnittstelle kann der Aufrufer als Option einen Wert ohne NULL für pActivationParams angeben. In diesem Fall verweist pActivationParams auf eine PROPVARIANT-Struktur , die Daten zur Streaminitialisierung enthält. Legen Sie das vt-Element der Struktur auf VT_BLOB fest. Legen Sie den Blob.pBlobData-Member so fest, dass er auf eine DIRECTX_AUDIO_ACTIVATION_PARAMS-Struktur verweist, die eine Audiositzungs-GUID und Streaminitialisierungsflags enthält. Legen Sie das blob.cbSize-Element auf sizeof(DIRECTX_AUDIO_ACTIVATION_PARAMS) fest. Ein Codebeispiel finden Sie unter Geräterollen für DirectShow-Anwendungen. Weitere Informationen zu PROPVARIANT finden Sie in der Windows SDK-Dokumentation.

Eine IBaseFilter-, IDirectSound-, IDirectSound8-, IDirectSoundCapture- oder IDirectSoundCapture8-Schnittstelle instance, die von der Activate-Methode erstellt wird, kapselt einen Stream auf dem Audioendpunktgerät. Während des Activate-Aufrufs erstellt das DirectSound-Systemmodul den Stream durch Aufrufen der IAudioClient::Initialize-Methode . Wenn pActivationParams nicht NULL ist, stellt DirectSound die Audiositzungs-GUID und Streaminitialisierungsflags aus der DIRECTX_AUDIO_ACTIVATION_PARAMS-Struktur als Eingabeparameter für den Initialize-Aufruf bereit. Wenn pActivationParamsNULL ist, legt DirectSound die Parameter AudioSessionGuid und StreamFlags der Initialize-Methode auf ihre jeweiligen Standardwerte NULL und 0 fest. Diese Werte weisen die -Methode an, den Stream der prozessspezifischen Sitzung zuzuweisen, die durch den Sitzungs-GUID-Wert GUID_NULL identifiziert wird.

Activate kann eine IDirectSound - oder IDirectSound8-Schnittstelle nur auf einem Renderingendpunktgerät aktivieren. Eine IDirectSoundCapture - oder IDirectSoundCapture8-Schnittstelle kann nur auf einem Erfassungsendpunktgerät aktiviert werden. Ein Activate-Aufruf zum Aktivieren einer IDirectSound- oder IDirectSoundCapture8-Schnittstelle auf einem Erfassungsgerät oder einer IDirectSoundCapture- oder IDirectSoundCapture8-Schnittstelle auf einem Renderinggerät schlägt fehl und gibt Fehlercode E_NOINTERFACE zurück.

In Windows 7 kann ein Client IMMDevice::Activate aufrufen und IID_IMFTrustedOutput angeben, um ein OTA-Objekt (Output Trust Authorities) zu erstellen und einen Zeiger auf die IMFTrustedOutput-Schnittstelle des Objekts abzurufen. OTAs können innerhalb oder außerhalb des geschützten Medienpfads (PMP) der Media Foundation arbeiten und Inhalte außerhalb der Media Foundation-Pipeline senden. Wenn sich der Aufrufer außerhalb von PMP befindet, funktioniert die OTA möglicherweise nicht im PMP, und die Schutzeinstellungen sind weniger robust. Informationen zur Verwendung von geschützten Objekten für Audio und Beispielcode finden Sie unter Geschütztes Benutzermodus-Audio (PUMA).

Allgemeine Informationen zu geschützten Objekten und IMFTrustedOutput finden Sie unter "Pfad für geschützte Medien" in der Media Foundation-Dokumentation.

Hinweis Wenn Sie die ISpatialAudioClient-Schnittstellen in einem XDK-Titel (Xbox One Development Kit) verwenden, müssen Sie zuerst EnableSpatialAudio aufrufen, bevor Sie IMMDeviceEnumerator::EnumAudioEndpoints oder IMMDeviceEnumerator::GetDefaultAudioEndpoint aufrufen. Andernfalls wird ein E_NOINTERFACE Fehler vom Aufruf von Activate zurückgegeben. EnableSpatialAudio ist nur für XDK-Titel verfügbar und muss weder für Universelle Windows-Plattform Apps aufgerufen werden, die auf Xbox One ausgeführt werden, noch für Nicht-Xbox One-Geräte.

Codebeispiele, die die Activate-Methode aufrufen, finden Sie in den folgenden Themen:

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	mmdeviceapi.h