IKsJackDescription インターフェイス (devicetopology.h)

[アーティクル]
08/23/2023

IKsJackDescription インターフェイスは、オーディオアダプター上のデバイスと外部または内部のエンドポイントデバイス (マイクや CD プレーヤーなど) との間の物理的な接続を提供するジャックまたは内部コネクタに関する情報を提供します。クライアントは、パラメーター refiid が REFIID IID_IKsJackDescriptionに設定された IPart::Activate メソッドを呼び出すことによって、パーツの IKsJackDescription インターフェイスへの参照を取得します。 IPart::Activate の呼び出しは、パーツが IKsJackDescription インターフェイスをサポートしている場合にのみ成功します。このインターフェイスは、Physical_ExternalまたはPhysical_Internal接続の種類を持つコネクタを表すパーツオブジェクトのみがサポートされます。

ほとんどの Windows オーディオアダプタードライバーは、Windows ドライバーモデル (WDM) をサポートし、カーネルストリーミング (KS) プロパティを使用して、コネクタ (KS ピンと呼ばれます) のハードウェア記述パラメーターを表します。 IKsJackDescription インターフェイスを使用すると、エンドポイントデバイスへのコネクタの KSPROPERTY_JACK_DESCRIPTION プロパティに簡単にアクセスできます。 KS プロパティと KS ピンの詳細については、Windows DDK のドキュメントを参照してください。

継承

IKsJackDescription インターフェイスは、IUnknown インターフェイスから継承します。 IKsJackDescription には、次の種類のメンバーもあります。

メソッド

IKsJackDescription インターフェイスには、これらのメソッドがあります。


IKsJackDescription::GetJackCount GetJackCount メソッドは、オーディオエンドポイントデバイスに接続するために必要なジャックの数を取得します。
IKsJackDescription::GetJackDescription GetJackDescription メソッドは、オーディオジャックの説明を取得します。

解説

オーディオエンドポイントデバイスが IKsJackDescription インターフェイスをサポートしている場合、Windows マルチメディアコントロールパネル Mmsys.cpl はジャック情報を表示します。ジャック情報を表示するには、次の手順に従います。

Mmsys.cpl を実行するには、コマンドプロンプトウィンドウを開き、次のコマンドを入力します。
コントロール mmsys.cpl

または、タスクバーの右側にある通知領域のスピーカーアイコンを右クリックし、[ 再生デバイス ] または [ 録音デバイス] を選択して、Mmsys.cpl を実行することもできます。
[Mmsys.cpl] ウィンドウが開いたら、再生デバイスの一覧または記録デバイスの一覧からデバイスを選択し、[ プロパティ] をクリックします。
プロパティウィンドウが開いたら、[ 全般] をクリックします。選択したプロパティページにデバイスのジャック情報が表示される場合、デバイスは IKsJackDescription インターフェイスをサポートします。プロパティページに "No jack information is available" というテキストが表示される場合、デバイスはインターフェイスをサポートしていません。

次のコード例は、オーディオエンドポイントデバイスの IKsJackDescription インターフェイスを取得する方法を示しています。

//-----------------------------------------------------------
// 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;
}

前のコード例では、GetJackInfo 関数は 2 つのパラメーターを受け取ります。入力パラメーター pDevice は 、エンドポイントデバイスの IMMDevice インターフェイスを指します。出力パラメーター ppJackDesc は、インターフェイスが存在する場合、関数が対応する IKsJackDescription インターフェイスのアドレスを書き込むポインター値を指します。インターフェイスが存在しない場合、関数は NULL を*ppJackDesc に書き込み、エラーコード E_NOINTERFACEを返します。

前のコード例では、 IMMDevice::Activate を呼び出すと、エンドポイントデバイスの IDeviceTopology インターフェイスが取得されます。エンドポイントデバイスのデバイストポロジには、アダプターデバイスに接続する 1 つのコネクタ (コネクタ番号 0) が含まれています。この接続の反対側では、アダプターデバイスのコネクタは、エンドポイントデバイスが接続するオーディオジャックまたはジャックを表します。 IDeviceTopology::GetConnector メソッドを呼び出すと、エンドポイントデバイス上のコネクタの IConnector インターフェイスが取得され、IConnector::GetConnectedTo メソッド呼び出しによってアダプターデバイス上の対応するコネクタが取得されます。最後に、 IConnector::QueryInterface メソッド呼び出しはアダプターデバイスのコネクタの IPart インターフェイスを取得し、 IPart::Activate メソッド呼び出しはコネクタの IKsJackDescription インターフェイスが存在する場合は取得します。

要件


サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	devicetopology.h

IKsJackDescription インターフェイス (devicetopology.h)

継承

メソッド

解説

要件

関連項目

フィードバック

フィードバック

その他のリソース