デバイストポロジ

[アーティクル]
06/13/2023

DeviceTopology API を使用すると、MMDevice API、WASAPI、または EndpointVolume API を介してアクセスすることができないオーディオアダプターのさまざまな内部機能を、クライアントが制御可能になります。

前述のように、MMDevice API、WASAPI、EndpointVolume API は、マイク、スピーカー、ヘッドフォン、他のオーディオ入出力デバイスをオーディオエンドポイントデバイスとしてクライアントに表示します。エンドポイントデバイスモデルを使用すると、クライアントはオーディオデバイスのボリュームコントロールとミュートコントロールに簡単にアクセスすることができます。これらのシンプルなコントロールのみを必要とするクライアントは、オーディオアダプターにおけるハードウェアデバイスの内部トポロジの走査を回避できます。

Windows Vista では、オーディオアプリケーションにより使用されるオーディオデバイスのトポロジが、オーディオエンジンによって自動的に構成されます。したがって、この目的のためにアプリケーションで DeviceTopology API を使用する必要はほとんどありません。たとえば、オーディオアダプターに、ライン入力またはマイクからストリームをキャプチャできるが、両方のエンドポイントデバイスからのストリームを同時にキャプチャできない入力マルチプレクサーが含まれているとします。「排他モードストリーム」で説明されているように、共有モードアプリケーションによるオーディオエンドポイントデバイスの使用を優先するようユーザーが排他モードアプリケーションを有効にしたとします。排他モードアプリケーションがマイクからのストリームの記録を開始した時点で、共有モードアプリケーションがライン入力からのストリームを記録している場合、オーディオエンジンは自動的にマルチプレクサーをライン入力からマイクに切り替えます。これに対し、Windows XP を含む以前のバージョンの Windows では、この例の排他モードアプリケーションが、Windows マルチメディア API の mixerXxx 関数を使用することにより、アダプターデバイスのトポロジを走査して、マルチプレクサーを検出し、マルチプレクサーを構成してマイク入力を選択します。 Windows Vista では、これらの手順は不要になりました。

ただし、一部のクライアントでは、MMDevice API、WASAPI、または EndpointVolume API を介してアクセスすることができないオーディオハードウェアコントロールの種類を明示的に制御する必要があります。これらのクライアントの場合、DeviceTopology API に、アダプターデバイスのトポロジを走査して、デバイス内のオーディオコントロールを検出および管理する機能が用意されています。 DeviceTopology API を使用するアプリケーションは、Windows オーディオポリシーに干渉したり、他のアプリケーションと共有されているオーディオデバイスの内部構成を妨げないように、注意して設計する必要があります。 Windows オーディオポリシーについて詳しくは、「ユーザーモードオーディオコンポーネント」をご覧ください。

DeviceTopology API には、デバイストポロジで次の種類のオーディオコントロールを検出および管理するためのインターフェイスが用意されています。

自動ゲイン制御
低音コントロール
入力セレクター (マルチプレクサー)
ラウドネスコントロール
ミッドレンジコントロール
ミュートコントロール
出力セレクター (デマルチプレクサー)
ピークメーター
高音コントロール
ボリュームコントロール

さらに、DeviceTopology API を使用すると、クライアントはアダプターデバイスに対して、サポートされているストリーム形式に関する情報を照会できます。ヘッダーファイル Devicetopology.h は、DeviceTopology API のインターフェイスを定義します。

次の図は、マイク、ライン入力、CD プレーヤーからオーディオをキャプチャする PCI アダプターの部分に対する、いくつかの接続されたデバイストポロジの例を示しています。

example of four connected device topologies

上の図は、アナログ入力からシステムバスまでのデータパスを示しています。次の各デバイスは、IDeviceTopology インターフェイスを持つデバイストポロジオブジェクトとして表されます。

ウェーブキャプチャデバイス
入力マルチプレクサーデバイス
エンドポイントデバイス A
エンドポイントデバイス B

トポロジ図では、アダプターデバイス (ウェーブキャプチャデバイスと入力マルチプレクサーデバイス) とエンドポイントデバイスが組み合わせられます。オーディオデータは、デバイス間の接続を介して、あるデバイスから次のデバイスに渡されます。接続の両側に、データがデバイスへの出入り時に通過するコネクタ (図では Con というラベルが付いています) があります。

図の左端では、ライン入力とマイクジャックからの信号がエンドポイントデバイスに入ります。

ウェーブキャプチャデバイスと入力マルチプレクサーデバイス内には、ストリーム処理関数があります。これは、DeviceTopology API の用語ではサブユニットと呼ばれます。上の図には、次の種類のサブユニットが示されています。

ボリュームコントロール (ラベル Vol)
ミュートコントロール (ラベル Mute)
マルチプレクサー (または入力セレクター、ラベル MUX)
アナログデジタルコンバーター (ラベル ADC)

ボリューム、ミュート、マルチプレクサーのサブユニットの設定はクライアントによって制御することができます。DeviceTopology API は、それらを制御するための制御インターフェイスをクライアントに提供します。この例では、ADC サブユニットに制御設定がありません。したがって、DeviceTopology API は ADC の制御インターフェイスを提供しません。

DeviceTopology API の用語では、コネクタとサブユニットは同じ一般カテゴリ (パーツ) に属しています。すべてのパーツは、コネクタかサブユニットかに関係なく、共通の関数セットを提供します。 DeviceTopology API は、コネクタとサブユニットに共通する汎用関数を表す IPart インターフェイスを実装します。この API は、コネクタとサブユニットの特定の側面を表す IConnector インターフェイスと ISubunit インターフェイスを実装します。

DeviceTopology API は、オーディオドライバーがオペレーティングシステムに公開してこれらのデバイスを表すカーネルストリーミング (KS) フィルターから、ウェーブキャプチャデバイスと入力マルチプレクサーデバイスのトポロジを構築します。 (オーディオアダプタードライバーは、これらのフィルターのハードウェア依存部分を表す IMiniportWaveXxx インターフェイスと IMiniportTopology インターフェイスを実装します。これらのインターフェイスと KS フィルターについて詳しくは、Windows DDK のドキュメントをご覧ください)。

DeviceTopology API は、上の図のエンドポイントデバイス A と B を表す単純なトポロジを構築します。エンドポイントデバイスのデバイストポロジは、単一のコネクタで構成されています。このトポロジは、エンドポイントデバイスのプレースホルダーにすぎず、オーディオデータを処理するためのサブユニットは含まれていません。事実、アダプターデバイスには、クライアントアプリケーションがオーディオ処理を制御するために使用するすべてのサブユニットが含まれています。エンドポイントデバイスのデバイストポロジは、主にアダプターデバイスのデバイストポロジを探索するための開始点として機能します。

デバイストポロジ内の 2 つの部分間の内部接続は、リンクと呼ばれます。 DeviceTopology API には、デバイストポロジ内のある部分から次の部分へのリンクを走査するためのメソッドが用意されています。この API には、デバイストポロジ間の接続を走査するためのメソッドも用意されています。

接続されているデバイストポロジのセットの探索を開始するため、クライアントアプリケーションによってオーディオエンドポイントデバイスの IDeviceTopology インターフェイスがアクティブ化されます。エンドポイントデバイスのコネクタは、オーディオアダプター内のコネクタまたはネットワークに接続します。エンドポイントがオーディオアダプター上のデバイスに接続する場合、DeviceTopology API のメソッドを使用すると、接続の反対側にあるアダプターデバイスの IDeviceTopology インターフェイスへの参照を取得することにより、アプリケーションはエンドポイントからアダプターへの接続をステップ実行できます。一方、ネットワークにはデバイストポロジがありません。ネットワーク接続は、システムにリモートでアクセスしているクライアントにオーディオストリームをパイプします。

DeviceTopology API は、オーディオアダプター内のハードウェアデバイスのトポロジにのみアクセスできます。図の左端にある外部デバイスと右端のソフトウェアコンポーネントは、API の範囲を超えています。図の両側の破線は、DeviceTopology API の制限を表しています。クライアントは API を使用し、入力ジャックからシステムバスに拡張されるデータパスを探索することができますが、API はこれらの境界を越えて侵入することはできません。

前の図の各コネクタには、コネクタが行う接続の種類を示す接続の種類が関連付けられています。したがって、接続の両側のコネクタは、常に同じ種類の接続になります。接続の種類は、ConnectorType 列挙値 (Physical_External、Physical_Internal、Software_Fixed、Software_IO、Network) で示されます。入力マルチプレクサーデバイスとエンドポイントデバイス A およびエンドポイントデバイス B の間の接続は、種類が Physical_External です。つまり、接続は外部デバイス (言い換えると、ユーザーがアクセス可能なオーディオジャック) への物理的な接続を表します。内部 CD プレーヤーからのアナログ信号への接続は、種類 Physical_Internal です。これは、システムシャーシ内に設置されている補助デバイスへの物理的な接続を示しています。ウェーブキャプチャデバイスと入力マルチプレクサーデバイスの間の接続は、種類 Software_Fixed です。これは、固定されており、ソフトウェア制御下で構成できない永続的な接続を示しています。最後に、図の右側にあるシステムバスへの接続は種類 Software_IO です。これは、接続のデータ I/O がソフトウェア制御下の DMA エンジンによって実装されていることを示しています。 (この図には、ネットワーク接続の種類の例は含まれていません)。

クライアントは、エンドポイントデバイスでデータパスの走査を開始します。まず、「オーディオデバイスの列挙」で説明されているように、エンドポイントデバイスを表す IMMDevice インターフェイスをクライアントが取得します。エンドポイントデバイスの IDeviceTopology インターフェイスを取得するため、クライアントはパラメーター iid を REFIID IID_IDeviceTopology に設定して、IMMDevice::Activate メソッドを呼び出します。

前の図の例では、入力マルチプレクサーデバイスに、ライン入力およびマイクジャックから取得されたキャプチャストリームのすべてのハードウェアコントロール (ボリューム、ミュート、マルチプレクサー) が含まれています。次のコード例は、回線入力またはマイクのエンドポイントデバイスの IMMDevice インターフェイスから、入力マルチプレクサーデバイスの IDeviceTopology インターフェイスを取得する方法を示しています。

//-----------------------------------------------------------
// The input argument to this function is a pointer to the
// IMMDevice interface of an endpoint device. The function
// outputs a pointer (counted reference) to the
// IDeviceTopology interface of the adapter device that
// connects to the endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

const IID IID_IDeviceTopology = __uuidof(IDeviceTopology);
const IID IID_IPart = __uuidof(IPart);

HRESULT GetHardwareDeviceTopology(
            IMMDevice *pEndptDev,
            IDeviceTopology **ppDevTopo)
{
    HRESULT hr = S_OK;
    IDeviceTopology *pDevTopoEndpt = NULL;
    IConnector *pConnEndpt = NULL;
    IConnector *pConnHWDev = NULL;
    IPart *pPartConn = NULL;

    // Get the endpoint device's IDeviceTopology interface.

    hr = pEndptDev->Activate(
                      IID_IDeviceTopology, CLSCTX_ALL,
                      NULL, (void**)&pDevTopoEndpt);
    EXIT_ON_ERROR(hr)

    // The device topology for an endpoint device always
    // contains just one connector (connector number 0).

    hr = pDevTopoEndpt->GetConnector(0, &pConnEndpt);
    EXIT_ON_ERROR(hr)

    // Use the connector in the endpoint device to get the
    // connector in the adapter device.

    hr = pConnEndpt->GetConnectedTo(&pConnHWDev);
    EXIT_ON_ERROR(hr)

    // Query the connector in the adapter device for
    // its IPart interface.

    hr = pConnHWDev->QueryInterface(
                         IID_IPart, (void**)&pPartConn);
    EXIT_ON_ERROR(hr)

    // Use the connector's IPart interface to get the
    // IDeviceTopology interface for the adapter device.

    hr = pPartConn->GetTopologyObject(ppDevTopo);

Exit:
    SAFE_RELEASE(pDevTopoEndpt)
    SAFE_RELEASE(pConnEndpt)
    SAFE_RELEASE(pConnHWDev)
    SAFE_RELEASE(pPartConn)

    return hr;
}

前のコード例の GetHardwareDeviceTopology 関数は、次の手順を実行して、入力マルチプレクサーデバイスの IDeviceTopology インターフェイスを取得します。

IMMDevice::Activate メソッドを呼び出して、エンドポイントデバイスの IDeviceTopology インターフェイスを取得します。
前の手順で取得した IDeviceTopology インターフェイスを使用して、IDeviceTopology::GetConnector メソッドを呼び出し、エンドポイントデバイスの単一コネクタ (コネクタ番号 0) の IConnector インターフェイスを取得します。
前の手順で取得した IConnector インターフェイスを使用して、IConnector::GetConnectedTo メソッドを呼び出し、入力マルチプレクサーデバイスのコネクタの IConnector インターフェイスを取得します。
前の手順で取得した IConnector インターフェイスの IPart インターフェイスに対してクエリを実行します。
前の手順で取得した IPart インターフェイスを使用して、IPart::GetTopologyObject メソッドを呼び出し、入力マルチプレクサーデバイスの IDeviceTopology インターフェイスを取得します。

前の図のマイクからユーザーが録音可能にするには、クライアントアプリケーションでマルチプレクサーがマイク入力を選択していることを確認する必要があります。次のコード例は、クライアントがマルチプレクサーを見つけるまで、マイクからデータパスを走査する方法を示しています。その後、マイク入力を選択するようプログラミングします。

//-----------------------------------------------------------
// The input argument to this function is a pointer to the
// IMMDevice interface for a capture endpoint device. The
// function traverses the data path that extends from the
// endpoint device to the system bus (for example, PCI)
// or external bus (USB). If the function discovers a MUX
// (input selector) in the path, it selects the MUX input
// that connects to the stream from the endpoint device.
//-----------------------------------------------------------
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

const IID IID_IDeviceTopology = __uuidof(IDeviceTopology);
const IID IID_IPart = __uuidof(IPart);
const IID IID_IConnector = __uuidof(IConnector);
const IID IID_IAudioInputSelector = __uuidof(IAudioInputSelector);

HRESULT SelectCaptureDevice(IMMDevice *pEndptDev)
{
    HRESULT hr = S_OK;
    DataFlow flow;
    IDeviceTopology *pDeviceTopology = NULL;
    IConnector *pConnFrom = NULL;
    IConnector *pConnTo = NULL;
    IPart *pPartPrev = NULL;
    IPart *pPartNext = NULL;
    IAudioInputSelector *pSelector = NULL;

    if (pEndptDev == NULL)
    {
        EXIT_ON_ERROR(hr = E_POINTER)
    }

    // Get the endpoint device's IDeviceTopology interface.
    hr = pEndptDev->Activate(
                      IID_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);
    SAFE_RELEASE(pDeviceTopology)
    EXIT_ON_ERROR(hr)

    // Make sure that this is a capture device.
    hr = pConnFrom->GetDataFlow(&flow);
    EXIT_ON_ERROR(hr)

    if (flow != Out)
    {
        // Error -- this is a rendering device.
        EXIT_ON_ERROR(hr = AUDCLNT_E_WRONG_ENDPOINT_TYPE)
    }

    // Outer loop: Each iteration traverses the data path
    // through a device topology starting at the input
    // connector and ending at the output connector.
    while (TRUE)
    {
        BOOL bConnected;
        hr = pConnFrom->IsConnected(&bConnected);
        EXIT_ON_ERROR(hr)

        // Does this connector connect to another device?
        if (bConnected == FALSE)
        {
            // This is the end of the data path that
            // stretches from the endpoint device to the
            // system bus or external bus. Verify that
            // the connection type is Software_IO.
            ConnectorType  connType;
            hr = pConnFrom->GetType(&connType);
            EXIT_ON_ERROR(hr)

            if (connType == Software_IO)
            {
                break;  // finished
            }
            EXIT_ON_ERROR(hr = E_FAIL)
        }

        // Get the connector in the next device topology,
        // which lies on the other side of the connection.
        hr = pConnFrom->GetConnectedTo(&pConnTo);
        EXIT_ON_ERROR(hr)
        SAFE_RELEASE(pConnFrom)

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

        // Inner loop: Each iteration traverses one link in a
        // device topology and looks for input multiplexers.
        while (TRUE)
        {
            PartType parttype;
            UINT localId;
            IPartsList *pParts;

            // Follow downstream link to next part.
            hr = pPartPrev->EnumPartsOutgoing(&pParts);
            EXIT_ON_ERROR(hr)

            hr = pParts->GetPart(0, &pPartNext);
            pParts->Release();
            EXIT_ON_ERROR(hr)

            hr = pPartNext->GetPartType(&parttype);
            EXIT_ON_ERROR(hr)

            if (parttype == Connector)
            {
                // We've reached the output connector that
                // lies at the end of this device topology.
                hr = pPartNext->QueryInterface(
                                  IID_IConnector,
                                  (void**)&pConnFrom);
                EXIT_ON_ERROR(hr)

                SAFE_RELEASE(pPartPrev)
                SAFE_RELEASE(pPartNext)
                break;
            }

            // Failure of the following call means only that
            // the part is not a MUX (input selector).
            hr = pPartNext->Activate(
                              CLSCTX_ALL,
                              IID_IAudioInputSelector,
                              (void**)&pSelector);
            if (hr == S_OK)
            {
                // We found a MUX (input selector), so select
                // the input from our endpoint device.
                hr = pPartPrev->GetLocalId(&localId);
                EXIT_ON_ERROR(hr)

                hr = pSelector->SetSelection(localId, NULL);
                EXIT_ON_ERROR(hr)

                SAFE_RELEASE(pSelector)
            }

            SAFE_RELEASE(pPartPrev)
            pPartPrev = pPartNext;
            pPartNext = NULL;
        }
    }

Exit:
    SAFE_RELEASE(pConnFrom)
    SAFE_RELEASE(pConnTo)
    SAFE_RELEASE(pPartPrev)
    SAFE_RELEASE(pPartNext)
    SAFE_RELEASE(pSelector)
    return hr;
}

DeviceTopology API は、前の図のようなマルチプレクサーをカプセル化するための IAudioInputSelector インターフェイスを実装します。 (IAudioOutputSelector インターフェイスは、デマルチプレクサーをカプセル化します)。前のコード例では、SelectCaptureDevice 関数の内部ループは、見つかった各サブユニットを照会して、サブユニットがマルチプレクサーであるかどうかを検出します。サブユニットがマルチプレクサーの場合、関数は IAudioInputSelector::SetSelection メソッドを呼び出して、エンドポイントデバイスからストリームに接続する入力を選択します。

前のコード例では、外側のループの各イテレーションが 1 つのデバイストポロジを走査します。前の図のデバイストポロジを走査するとき、最初のイテレーションは入力マルチプレクサーデバイスを走査し、2 番目のイテレーションはウェーブキャプチャデバイスを走査します。この関数は、図の右端にあるコネクタに到達すると終了します。終了は、接続の種類 Software_IO を持つコネクタを関数が検出したときに発生します。この接続の種類は、アダプターデバイスがシステムバスに接続するポイントを識別します。

前のコード例の IPart::GetPartType メソッドの呼び出しは、現在のパーツがコネクタかオーディオ処理サブユニットかを示す IPartType 列挙値を取得します。

前のコード例の内部ループは、IPart::EnumPartsOutgoing メソッドを呼び出すことにより、あるパーツから次のパーツへのリンクをステップ実行します。 (逆方向にステップ実行するための IPart::EnumPartsIncoming メソッドもあります)。このメソッドは、すべての発信パーツのリストを含む IPartsList オブジェクトを取得します。ただし、SelectCaptureDevice 関数がキャプチャデバイスで発生すると予想されるどのパーツにも、必ず送信パーツが 1 つだけ存在します。したがって、IPartsList::GetPart の後続の呼び出しでは、必ずリストの最初のパーツ (パーツ番号 0) が要求されます。これは、この関数がリスト内の唯一のパーツであると想定しているためです。

その前提条件が無効なトポロジが SelectCaptureDevice 関数で検出された場合、この関数はデバイスを正しく構成できない可能性があります。このようなエラーを回避するため、より汎用的なバージョンの関数で以下の処理が行われる場合があります。

IPartsList::GetCount メソッドを呼び出して、発信パーツの数を決定します。
送信パーツごとに IPartsList::GetPart を呼び出し、パーツから続くデータパスの走査を開始します。

一部のパーツには、クライアントが設定または取得できるハードウェアコントロールが関連付けられていますが、必ずしもすべてではありません。特定のパーツに、0 個、1 個、または 1 個以上のハードウェアコントロールが存在する場合があります。ハードウェアコントロールは、以下のインターフェイスペアで表されます。

すべてのハードウェアコントロールに共通のメソッドを持つ汎用コントロールインターフェイス IControlInterface。
特定の種類のハードウェアコントロール (ボリュームコントロールなど) のコントロールパラメーターを公開する関数固有のインターフェイス (IAudioVolumeLevel など)。

パーツのハードウェアコントロールを列挙するため、クライアントは最初に IPart::GetControlInterfaceCount メソッドを呼び出して、パーツに関連付けられているハードウェアコントロールの数を決定します。次に、クライアントは IPart::GetControlInterface メソッドに対して一連の呼び出しを行って、各ハードウェアコントロールの IControlInterface インターフェイスを取得します。最後に、クライアントは IControlInterface::GetIID メソッドを呼び出してインターフェイス ID を取得することにより、各ハードウェアコントロールの関数固有のインターフェイスを取得します。クライアントは、この ID で IPart::Activate メソッドを呼び出して、関数固有のインターフェイスを取得します。

コネクタであるパーツは、次の関数固有のコントロールインターフェイスのいずれかをサポートしている可能性があります。

サブユニットであるパーツは、次の関数固有のコントロールインターフェイスの 1 つ以上をサポートしている可能性があります。

基になるハードウェアコントロールにデバイス固有のコントロール値があり、前の一覧にある他の関数固有のインターフェイスでコントロールを適切に表すことができない場合のみ、パーツで IDeviceSpecificProperty インターフェイスがサポートされます。通常、デバイス固有のプロパティは、パーツの種類、パーツのサブタイプ、パーツ名などの情報からプロパティ値の意味を推測できるクライアントにのみ役立ちます。クライアントは、IPart::GetPartType、IPart::GetSubType、および IPart::GetName メソッドを呼び出すことによって、この情報を取得できます。

プログラミングガイド

次の方法で共有

デバイストポロジ

フィードバック

その他のリソース

次の方法で共有

デバイス トポロジ

関連トピック

フィードバック

その他のリソース

デバイストポロジ