IAudioClient::GetService-Methode (audioclient.h)

Artikel
08/22/2023

Die GetService-Methode greift über das Audioclientobjekt auf zusätzliche Dienste zu.

Syntax

HRESULT GetService(
  [in]  REFIID riid,
  [out] void   **ppv
);

Parameter

[in] riid

Die Schnittstellen-ID für den angeforderten Dienst. Der Client sollte diesen Parameter auf einen der folgenden REFIID-Werte festlegen:

IID_IAudioCaptureClient

IID_IAudioClientDuckingControl

IID_IAudioClock

IID_IAudioRenderClient

IID_IAudioSessionControl

IID_IAudioStreamVolume

IID_IChannelAudioVolume

IID_IMFTrustedOutput

IID_ISimpleAudioVolume

Weitere Informationen finden Sie in den Hinweisen.

[out] ppv

Zeiger auf eine Zeigervariable, in die die Methode die Adresse eines instance der angeforderten 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 GetService-Aufruf fehlschlägt, ist *ppvNULL.

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_POINTER	Der Parameter ppv ist NULL.
E_NOINTERFACE	Die angeforderte Schnittstelle ist nicht verfügbar.
AUDCLNT_E_NOT_INITIALIZED	Der Audiostream wurde nicht initialisiert.
AUDCLNT_E_WRONG_ENDPOINT_TYPE	Der Aufrufer hat versucht, auf eine IAudioCaptureClient-Schnittstelle auf einem Renderingendpunkt oder auf eine IAudioRenderClient-Schnittstelle auf einen Erfassungsendpunkt zuzugreifen.
AUDCLNT_E_DEVICE_INVALIDATED	Das Audioendpunktgerät wurde getrennt, oder die Audiohardware oder die zugehörigen Hardwareressourcen wurden neu konfiguriert, deaktiviert, entfernt oder anderweitig für die Verwendung nicht verfügbar gemacht.
AUDCLNT_E_SERVICE_NOT_RUNNING	Der Windows-Audiodienst wird nicht ausgeführt.

Hinweise

Diese Methode erfordert eine vorherige Initialisierung der IAudioClient-Schnittstelle . Alle Aufrufe dieser Methode schlagen mit dem Fehler AUDCLNT_E_NOT_INITIALIZED fehl, bis der Client den Audiodatenstrom durch erfolgreiches Aufrufen der IAudioClient::Initialize-Methode initialisiert .

Die GetService-Methode unterstützt die folgenden Dienstschnittstellen:

In Windows 7 wurde ein neuer Dienstbezeichner hinzugefügt, IID_IMFTrustedOutput, der die Verwendung von OTA-Objekten (Output Trust Authority) erleichtert. Diese Objekte können innerhalb oder außerhalb des geschützten Medienpfads (PMP) von Media Foundation ausgeführt werden 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. OTAs müssen die IMFTrustedOutput-Schnittstelle implementieren. Durch Übergeben IID_IMFTrustedOutput in GetService kann eine Anwendung einen Zeiger auf die IMFTrustedOutput-Schnittstelle des Objekts abrufen. Weitere Informationen zu geschützten Objekten und IMFTrustedOutput finden Sie unter "Pfad für geschützte Medien" in der Media Foundation SDK-Dokumentation.

Informationen zur Verwendung vertrauenswürdiger Audiotreiber in OTAs finden Sie unter Geschütztes Audio für den Benutzermodus (PUMA).

Beachten Sie, dass die Aktivierung von IMFTrustedOutput über diesen Mechanismus unabhängig davon funktioniert, ob der Aufrufer in PMP ausgeführt wird. Wenn der Aufrufer jedoch nicht in einem geschützten Prozess ausgeführt wird (d. h. der Aufrufer befindet sich nicht im PMP von Media Foundation), funktioniert die Audio-OTA möglicherweise nicht im PMP, und die Schutzeinstellungen sind weniger robust.

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


const IID IID_IAudioCaptureClient  __uuidof(IAudioCaptureClient)

Informationen zum __uuidof-Operator finden Sie in der Windows SDK-Dokumentation.

Um das IAudioClient-Objekt freizugeben und alle zugehörigen Ressourcen freizugeben, muss der Client alle Verweise auf alle Dienstobjekte freigeben, die durch aufrufen von GetService erstellt wurden, zusätzlich zum Aufrufen von Release auf der IAudioClient-Schnittstelle selbst. Der Client muss einen Dienst aus demselben Thread freigeben, der das IAudioClient-Objekt freigibt.

Die Schnittstellen IAudioSessionControl, IAudioStreamVolume, IChannelAudioVolume und ISimpleAudioVolume steuern und überwachen Aspekte von Audiositzungen und Streams im freigegebenen Modus. Diese Schnittstellen funktionieren nicht mit Datenströmen im exklusiven Modus.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	audioclient.h