IKsJackDescription-Schnittstelle (devicetopology.h)

Artikel
08/23/2023

Die IKsJackDescription-Schnittstelle stellt Informationen zu den Buchsen oder internen Anschlüssen bereit, die eine physische Verbindung zwischen einem Gerät an einem Audioadapter und einem externen oder internen Endpunktgerät (z. B. mikrofon oder CD-Player) bereitstellen. Der Client ruft einen Verweis auf die IKsJackDescription-Schnittstelle eines Teils ab, indem er die IPart::Activate-Methode aufruft, wobei der Parameter refiid auf REFIID IID_IKsJackDescription festgelegt ist. Der Aufruf von IPart::Activate ist nur erfolgreich, wenn das Teil die IKsJackDescription-Schnittstelle unterstützt. Nur ein Teilobjekt, das einen Connector mit einem Physical_External oder Physical_Internal Verbindungstyp darstellt, unterstützt diese Schnittstelle.

Die meisten Windows-Audioadaptertreiber unterstützen das Windows-Treibermodell (WINDOWS Driver Model, WDM) und verwenden Kernelstreamingeigenschaften (KS), um die Hardwarebeschreibungsparameter in Connectors (als KS-Pins bezeichnet) darzustellen. Die IKsJackDescription-Schnittstelle bietet bequemen Zugriff auf die KSPROPERTY_JACK_DESCRIPTION-Eigenschaft eines Connectors für ein Endpunktgerät. Weitere Informationen zu KS-Eigenschaften und KS-Pins finden Sie in der Windows DDK-Dokumentation.

Vererbung

Die IKsJackDescription-Schnittstelle erbt von der IUnknown-Schnittstelle . IKsJackDescription verfügt auch über folgende Arten von Membern:

Methoden

Die IKsJackDescription-Schnittstelle verfügt über diese Methoden.


IKsJackDescription::GetJackCount Die GetJackCount-Methode ruft die Anzahl der Buchsen ab, die zum Herstellen einer Verbindung mit einem Audioendpunktgerät erforderlich sind.
IKsJackDescription::GetJackDescription Die GetJackDescription-Methode ruft eine Beschreibung einer Audiobuchse ab.

Hinweise

Wenn ein Audioendpunktgerät die IKsJackDescription-Schnittstelle unterstützt, zeigt die Windows-Multimedia-Systemsteuerung Mmsys.cpl die Klinkeninformationen an. Führen Sie die folgenden Schritte aus, um die Jack-Informationen anzuzeigen:

Um Mmsys.cpl auszuführen, öffnen Sie ein Eingabeaufforderungsfenster, und geben Sie den folgenden Befehl ein:
steuern mmsys.cpl

Alternativ können Sie Mmsys.cpl ausführen, indem Sie im Infobereich, der sich rechts auf der Taskleiste befindet, mit der rechten Maustaste auf das Lautsprechersymbol klicken und entweder Wiedergabegeräte oder Aufzeichnungsgeräte auswählen.
Nachdem das fenster Mmsys.cpl geöffnet wird, wählen Sie ein Gerät entweder aus der Liste der Wiedergabegeräte oder der Liste der Aufzeichnungsgeräte aus, und klicken Sie auf Eigenschaften.
Wenn das Eigenschaftenfenster geöffnet wird, klicken Sie auf Allgemein. Wenn auf der ausgewählten Eigenschaftenseite die Klinkeninformationen für das Gerät angezeigt werden, unterstützt das Gerät die IKsJackDescription-Schnittstelle . Wenn auf der Eigenschaftenseite der Text "Keine Klinkeninformationen verfügbar" angezeigt wird, unterstützt das Gerät die Schnittstelle nicht.

Das folgende Codebeispiel zeigt, wie Sie die IKsJackDescription-Schnittstelle für ein Audioendpunktgerät abrufen:

//-----------------------------------------------------------
// Get the IKsJackDescription interface that describes the
// audio jack or jacks that the endpoint device plugs into.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

HRESULT GetJackInfo(IMMDevice *pDevice,
                    IKsJackDescription **ppJackDesc)
{
    HRESULT hr = S_OK;
    IDeviceTopology *pDeviceTopology = NULL;
    IConnector *pConnFrom = NULL;
    IConnector *pConnTo = NULL;
    IPart *pPart = NULL;
    IKsJackDescription *pJackDesc = NULL;

    if (NULL != ppJackDesc)
    {
        *ppJackDesc = NULL;
    }
    if (NULL == pDevice || NULL == ppJackDesc)
    {
        return E_POINTER;
    }

    // Get the endpoint device's IDeviceTopology interface.
    hr = pDevice->Activate(__uuidof(IDeviceTopology), CLSCTX_ALL,
                           NULL, (void**)&pDeviceTopology);
    EXIT_ON_ERROR(hr)

    // The device topology for an endpoint device always
    // contains just one connector (connector number 0).
    hr = pDeviceTopology->GetConnector(0, &pConnFrom);
    EXIT_ON_ERROR(hr)

    // Step across the connection to the jack on the adapter.
    hr = pConnFrom->GetConnectedTo(&pConnTo);
    if (HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) == hr)
    {
        // The adapter device is not currently active.
        hr = E_NOINTERFACE;
    }
    EXIT_ON_ERROR(hr)

    // Get the connector's IPart interface.
    hr = pConnTo->QueryInterface(__uuidof(IPart), (void**)&pPart);
    EXIT_ON_ERROR(hr)

    // Activate the connector's IKsJackDescription interface.
    hr = pPart->Activate(CLSCTX_INPROC_SERVER,
                         __uuidof(IKsJackDescription), (void**)&pJackDesc);
    EXIT_ON_ERROR(hr)

    *ppJackDesc = pJackDesc;

Exit:
    SAFE_RELEASE(pDeviceTopology)
    SAFE_RELEASE(pConnFrom)
    SAFE_RELEASE(pConnTo)
    SAFE_RELEASE(pPart)
    return hr;
}

Im vorherigen Codebeispiel akzeptiert die GetJackInfo-Funktion zwei Parameter. Der Eingabeparameter pDevice verweist auf die IMMDevice-Schnittstelle eines Endpunktgeräts. Der Ausgabeparameter ppJackDesc zeigt auf einen Zeigerwert, in den die Funktion die Adresse der entsprechenden IKsJackDescription-Schnittstelle schreibt, sofern die Schnittstelle vorhanden ist. Wenn die Schnittstelle nicht vorhanden ist, schreibt die Funktion NULL in *ppJackDesc und gibt den Fehlercode E_NOINTERFACE zurück.

Im vorherigen Codebeispiel ruft der Aufruf von IMMDevice::Activate die IDeviceTopology-Schnittstelle des Endpunktgeräts ab. Die Gerätetopologie eines Endpunktgeräts enthält einen einzelnen Connector (Connectornummer 0), der eine Verbindung mit dem Adaptergerät herstellt. Auf der anderen Seite dieser Verbindung stellt der Stecker auf dem Adaptergerät die Audiobuchse dar, an die das Endpunktgerät angeschlossen ist. Der Aufruf der IDeviceTopology::GetConnector-Methode ruft die IConnector-Schnittstelle des Connectors auf dem Endpunktgerät ab, und der IConnector::GetConnectedTo-Methodenaufruf ruft den entsprechenden Connector auf dem Adaptergerät ab. Schließlich ruft der IConnector::QueryInterface-Methodenaufruf die IPart-Schnittstelle des Connectors des Adaptergeräts ab, und der Aufruf der IPart::Activate-Methode ruft die IKsJackDescription-Schnittstelle des Connectors ab, sofern vorhanden.

Anforderungen


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

Weitere Informationen

Kernaudioschnittstellen

DeviceTopology-API

IPart::Activate

Freigeben über