IMMDeviceEnumerator::GetDefaultAudioEndpoint-Methode (mmdeviceapi.h)

  • Artikel

Die GetDefaultAudioEndpoint-Methode ruft den Standard-Audioendpunkt für die angegebene Datenflussrichtung und -rolle ab.

Syntax

HRESULT GetDefaultAudioEndpoint(
  [in]  EDataFlow dataFlow,
  [in]  ERole     role,
  [out] IMMDevice **ppEndpoint
);

Parameter

[in] dataFlow

Die Datenflussrichtung für das Endpunktgerät. Der Aufrufer sollte diesen Parameter auf einen der beiden folgenden EDataFlow-Enumerationswerte festlegen:

eRender

eCapture

Die Datenflussrichtung für ein Renderinggerät ist eRender. Die Datenflussrichtung für ein Erfassungsgerät ist eCapture.

[in] role

Die Rolle des Endpunktgeräts. Der Aufrufer sollte diesen Parameter auf einen der folgenden ERole-Enumerationswerte festlegen:

eConsole

eMultimedia

eCommunications

Weitere Informationen finden Sie in den Hinweisen.

[out] ppEndpoint

Zeiger auf eine Zeigervariable, in die die Methode die Adresse der IMMDevice-Schnittstelle des Endpunktobjekts für das Standard-Audioendpunktgerät 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 GetDefaultAudioEndpoint-Aufruf fehlschlägt, ist *ppDeviceNULL.

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 ppDevice ist NULL.
E_INVALIDARG
 Der Parameter dataFlow oder die Rolle liegt außerhalb des Bereichs.
E_NOTFOUND
 Es ist kein Gerät verfügbar.
E_OUTOFMEMORY
 Nicht genügend Arbeitsspeicher.

Hinweise

Hinweis

In Windows Vista unterstützt die MMDevice-API Geräterollen , die vom System bereitgestellten Benutzeroberflächenprogramme jedoch nicht. Über die Benutzeroberfläche in Windows Vista kann der Benutzer ein Standardaudiogerät für das Rendern und ein Standardaudiogerät für die Aufnahme auswählen. Wenn der Benutzer das Standardrendering- oder Erfassungsgerät ändert, weist das System diesem Gerät alle drei Geräterollen (eConsole, eMultimedia und eCommunications) zu. Daher wählt GetDefaultAudioEndpoint immer das Standardrendering- oder Erfassungsgerät aus, unabhängig davon, welche Rolle durch den Rollenparameter angegeben wird. In einer zukünftigen Version von Windows kann der Benutzer über die Benutzeroberfläche verschiedenen Geräten einzelne Rollen zuweisen. In diesem Fall hängt die Auswahl eines Rendering- oder Erfassungsgeräts durch GetDefaultAudioEndpoint möglicherweise vom Rollenparameter ab. Daher kann sich das Verhalten einer Audioanwendung ändern, die für die Ausführung in Windows Vista entwickelt wurde, wenn sie in einer zukünftigen Version von Windows ausgeführt wird. Weitere Informationen finden Sie unter Geräterollen in Windows Vista.

Diese Methode ruft das Standardendpunktgerät für die angegebene Datenflussrichtung (Rendering oder Erfassung) und rolle ab. Ein Client kann beispielsweise das Standardkonsolenwiedergabegerät abrufen, indem er den folgenden Aufruf ausgibt:


  hr = pDevEnum->GetDefaultAudioEndpoint(
                   eRender, eConsole, &pDeviceOut);

Im vorherigen Codefragment ist die Variable hr vom Typ HRESULT, pDevEnum ist ein Zeiger auf eine IMMDeviceEnumerator-Schnittstelle , und pDeviceOut ist ein Zeiger auf eine IMMDevice-Schnittstelle .

Ein Windows-System kann eine Kombination von Audioendpunkten wie Desktoplautsprechern, High-Fidelity-Kopfhörern, Desktopmikrofonen, Headsets mit Lautsprechern und Mikrofonen und High-Fidelity-Mehrkanallautsprechern enthalten. Der Benutzer kann den Geräten entsprechende Rollen zuweisen. Beispielsweise kann eine Anwendung, die Sprachkommunikationsstreams verwaltet, GetDefaultAudioEndpoint aufrufen, um die für diese Rolle vorgesehenen Rendering- und Erfassungsgeräte zu identifizieren.

Wenn nur ein einzelnes Rendering- oder Erfassungsgerät verfügbar ist, weist das System diesem Gerät immer alle drei Rendering- oder Erfassungsrollen zu. Wenn die Methode kein Rendering- oder Erfassungsgerät für die angegebene Rolle findet, bedeutet dies, dass überhaupt kein Rendering- oder Erfassungsgerät verfügbar ist. Wenn kein Gerät verfügbar ist, legt die Methode *ppEndpoint = NULL fest und gibt ERROR_NOT_FOUND zurück.

Codebeispiele, die die GetDefaultAudioEndpoint-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

Weitere Informationen

IMMDevice-Schnittstelle

IMMDeviceEnumerator-Schnittstelle