IKsControl インターフェイスを使用したオーディオプロパティへのアクセス

[アーティクル]
03/11/2024

まれに、特殊なオーディオアプリケーションでは、DeviceTopology API または MMDevice API によって公開されていないオーディオアダプターの特定のハードウェア機能にアクセスするために、IKsControl インターフェイスを使用する必要があります。 IKsControl インターフェイスを使用すると、カーネルストリーミング (KS) デバイスのプロパティ、イベント、メソッドをユーザーモードアプリケーションで使用できるようになります。オーディオアプリケーションにとって最も重要なのは KS プロパティです。 IKsControl インターフェイスは、DeviceTopology API と MMDevice API と組み合わせて使用することで、オーディオアダプターの KS プロパティにアクセスすることができます。

IKsControl インターフェイスは、主に、オーディオハードウェアを管理するためのコントロールパネルアプリケーションを記述するハードウェアベンダーによる使用を目的としています。 IKsControl は、特定のハードウェアデバイスに関連付けられていない汎用オーディオアプリケーションにはあまり役に立ちません。この理由は、ハードウェアベンダーは、デバイスのオーディオプロパティにアクセスするための独自のメカニズムを頻繁に実装するためです。ハードウェア固有のドライバーの癖を隠し、オーディオプロパティにアクセスするための比較的統一されたインターフェイスを提供する DeviceTopology API とは対照的に、アプリケーションは IKsControl を使用してドライバーと直接通信します。 IKsControl の詳細については、Windows DDK のドキュメントを参照してください。

「デバイストポロジ」で説明したように、アダプターデバイスのトポロジのサブユニットは、次の表の左側の列に示す 1 つ以上の関数固有のコントロールインターフェイスをサポートする場合があります。テーブルの右列の各エントリは、左側のコントロールインターフェイスに対応する KS プロパティです。コントロールインターフェイスでは、プロパティへの便利なアクセスが提供されています。ほとんどのオーディオドライバーは、オーディオアダプターのトポロジのサブユニット (KS ノードとも呼ばれます) の関数固有の処理機能を表すために、KS プロパティを使用します。 KS プロパティと KS ノードの詳細については、Windows DDK のドキュメントを参照してください。

コントロールインターフェイス	KSプロパティ
IAudioAutoGainControl	KSPROPERTY_AUDIO_AGC
IAudioBass	KSPROPERTY_AUDIO_BASS
IAudioChannelConfig	KSPROPERTY_AUDIO_CHANNEL_CONFIG
IAudioInputSelector	KSPROPERTY_AUDIO_MUX_SOURCE
IAudioLoudness	KSPROPERTY_AUDIO_LOUDNESS
IAudioMidrange	KSPROPERTY_AUDIO_MID
IAudioMute	KSPROPERTY_AUDIO_MUTE
IAudioOutputSelector	KSPROPERTY_AUDIO_DEMUX_DEST
IAudioPeakMeter	KSPROPERTY_AUDIO_PEAKMETER
IAudioTreble	KSPROPERTY_AUDIO_TREBLE
IAudioVolumeLevel	KSPROPERTY_AUDIO_VOLUMELEVEL
IDeviceSpecificProperty	KSPROPERTY_AUDIO_DEV_SPECIFIC

一部のオーディオアダプターのトポロジには、前の表に記載されていない KS プロパティを持つサブユニットが含まれている場合があります。たとえば、特定のサブユニットの IPart::GetSubType メソッドを呼び出すと、KSNODETYPE_TONE の GUID 値が取得されるとします。このサブタイプ GUID は、サブユニットが次の KS プロパティの 1 つ以上をサポートしていることを示します。

KSPROPERTY_AUDIO_BASS
KSPROPERTY_AUDIO_MID
KSPROPERTY_AUDIO_TREBLE
KSPROPERTY_AUDIO_BASS_BOOST

この一覧の最初の 3 つのプロパティは、前の表に示したコントロールインターフェイスを介してアクセスできますが、KSPROPERTY_AUDIO_BASS_BOOST プロパティには DeviceTopology API に対応するコントロールインターフェイスがありません。ただし、サブユニットがこのプロパティをサポートしている場合は、アプリケーションは IKsControl インターフェイスを使用してこのプロパティにアクセスできます。

サブタイプ KSNODETYPE_TONE のサブユニットの KSPROPERTY_AUDIO_BASS_BOOST プロパティにアクセスするには、次の手順が必要です。

IConnector::GetDeviceIdConnectedTo メソッド、または IDeviceTopology::GetDeviceId メソッドを呼び出して、アダプターデバイスを識別するデバイス ID 文字列を取得します。この文字列はエンドポイント ID 文字列に似ていますが、エンドポイントデバイスではなくアダプターデバイスを識別する点が異なります。アダプターデバイスとエンドポイントデバイスの違いの詳細については、「オーディオエンドポイントデバイス」を参照してください。
デバイス ID 文字列を使用して IMMDeviceEnumerator::GetDevice メソッドを呼び出すことで、アダプターデバイスの IMMDevice インターフェイスを取得します。この IMMDevice インターフェイスは、「IMMDevice インターフェイス」で説明されているインターフェイスと同じですが、エンドポイントデバイスではなくアダプターデバイスを表しています。
パラメーター iid を REFIID IID_IKsControl に設定して IMMDevice::Activate メソッドを呼び出すことによって、サブユニットの IKsControl インターフェイスを取得します。この Activate メソッドでサポートされるインターフェイス (アダプターデバイス用) は、エンドポイントデバイス用の Activate メソッドでサポートされるインターフェイスとは異なる点に注意してください。特に、アダプターデバイス用の Activate メソッドでは、IKsControl がサポートされています。
IPart::GetLocalId メソッドを呼び出して、サブユニットのローカル ID を取得します。
KS プロパティ要求を作成します。要求に必要な KS ノード ID は、前の手順で取得したローカル ID の 16 ビットの最下位ビットに含まれています。
IKsControl::KsProperty メソッドを呼び出して、KS プロパティ要求をオーディオドライバーに送信します。このメソッドの詳細については、Windows DDK ドキュメントを参照してください。

次のコード例では、サブタイプ KSNODETYPE_TONE のサブユニットから KSPROPERTY_AUDIO_BASS_BOOST プロパティの値を取得します。

//-----------------------------------------------------------
// This function calls the IKsControl::Property method to get
// the value of the KSPROPERTY_AUDIO_BASS_BOOST property of
// a subunit. Parameter pPart should point to a part that is
// a subunit with a subtype GUID value of KSNODETYPE_TONE.
//-----------------------------------------------------------
#define PARTID_MASK 0x0000ffff
#define EXIT_ON_ERROR(hres)  \
              if (FAILED(hres)) { goto Exit; }
#define SAFE_RELEASE(punk)  \
              if ((punk) != NULL)  \
                { (punk)->Release(); (punk) = NULL; }

const IID IID_IKsControl = __uuidof(IKsControl);

HRESULT GetBassBoost(IMMDeviceEnumerator *pEnumerator,
                     IPart *pPart, BOOL *pbValue)
{
    HRESULT hr;
    IDeviceTopology *pTopology = NULL;
    IMMDevice *pPnpDevice = NULL;
    IKsControl *pKsControl = NULL;
    LPWSTR pwszDeviceId = NULL;

    if (pEnumerator == NULL || pPart == NULL || pbValue == NULL)
    {
        return E_INVALIDARG;
    }

    // Get the topology object for the adapter device that contains
    // the subunit represented by the IPart interface.
    hr = pPart->GetTopologyObject(&pTopology);
    EXIT_ON_ERROR(hr)

    // Get the device ID string that identifies the adapter device.
    hr = pTopology->GetDeviceId(&pwszDeviceId);
    EXIT_ON_ERROR(hr)

    // Get the IMMDevice interface of the adapter device object.
    hr = pEnumerator->GetDevice(pwszDeviceId, &pPnpDevice);
    EXIT_ON_ERROR(hr)

    // Activate an IKsControl interface on the adapter device object.
    hr = pPnpDevice->Activate(IID_IKsControl, CLSCTX_ALL, NULL, (void**)&pKsControl);
    EXIT_ON_ERROR(hr)

    // Get the local ID of the subunit (contains the KS node ID).
    UINT localId = 0;
    hr = pPart->GetLocalId(&localId);
    EXIT_ON_ERROR(hr)

    KSNODEPROPERTY_AUDIO_CHANNEL ksprop;
    ZeroMemory(&ksprop, sizeof(ksprop));
    ksprop.NodeProperty.Property.Set = KSPROPSETID_Audio;
    ksprop.NodeProperty.Property.Id = KSPROPERTY_AUDIO_BASS_BOOST;
    ksprop.NodeProperty.Property.Flags = KSPROPERTY_TYPE_GET | KSPROPERTY_TYPE_TOPOLOGY;
    ksprop.NodeProperty.NodeId = localId & PARTID_MASK;
    ksprop.Channel = 0;

    // Send the property request.to the device driver.
    BOOL bValue = FALSE;
    ULONG valueSize;
    hr = pKsControl->KsProperty(
                         &ksprop.NodeProperty.Property, sizeof(ksprop),
                         &bValue, sizeof(bValue), &valueSize);
    EXIT_ON_ERROR(hr)

    *pbValue = bValue;

Exit:
    SAFE_RELEASE(pTopology)
    SAFE_RELEASE(pPnpDevice)
    SAFE_RELEASE(pKsControl)
    CoTaskMemFree(pwszDeviceId);
    return hr;
}

前のコード例では、GetBassBoost 関数は次の 3 つのパラメーターを受け取ります。

pEnumerator は、オーディオエンドポイント列挙子の IMMDeviceEnumerator インターフェイスを指します。
pPart は、 KSNODETYPE_TONE のサブタイプを持つサブユニットの IPart インターフェイスを指します。
pbValue は、関数がプロパティ値を書き込む BOOL 変数を指します。

プログラムは、IPart::GetSubType を呼び出して、サブユニットのサブタイプが KSNODETYPE_TONE であることを判断した後にのみ、GetBassBoost を呼び出します。低音ブーストが有効な場合、プロパティ値は TRUE です。低音ブーストが無効になっている場合は、FALSE です。

GetBassBoost 関数の先頭で、IPart::GetTopologyObject メソッドを呼び出すと、KSNODETYPE_TONE サブユニットを含むアダプターデバイスの IDeviceTopology インターフェイスを取得します。 IDeviceTopology::GetDeviceId メソッドの呼び出しは、アダプターデバイスを識別するデバイス ID 文字列を取得します。 IMMDeviceEnumerator::GetDevice メソッドの呼び出しは、入力パラメーターとしてデバイス ID 文字列を受け取り、アダプターデバイスの IMMDevice インターフェイスを取得します。次に、IMMDevice::Activate メソッドの呼び出しによって、サブユニットの IKsControl インターフェイスを取得します。 IKsControl インターフェイスの詳細については、Windows DDK のドキュメントを参照してください。

次に、前のコード例では、低音ブーストプロパティを記述する KSNODEPROPERTY_AUDIO_CHANNEL 構造体が作成されます。このコード例では、構造体へのポインターを IKsControl::KsProperty メソッドに渡します。このメソッドは、構造体内の情報を使用してプロパティ値を取得します。 KSNODEPROPERTY_AUDIO_CHANNEL 構造体と IKsControl::KsProperty メソッドの詳細については、Windows DDK のドキュメントを参照してください。

オーディオハードウェアは、通常、オーディオストリーム内の各チャネルに個別の低音ブースト状態を割り当てます。原則として, 低音ブーストは、一部のチャンネルで有効にでき、それ以外のチャネルでは無効になります。 KSNODEPROPERTY_AUDIO_CHANNEL 構造体には、チャネル番号を指定する Channel メンバーが含まれています。ストリームに N 個のチャネルが含まれている場合、チャネルには 0 から N— 1 の番号が付けられます。前のコード例では、チャネル 0 のみの低音ブーストプロパティの値を取得します。この実装では、すべてのチャネルの低音ブーストプロパティが同じ状態に一様に設定されていることを暗黙的に想定しています。したがって、ストリームの低音ブーストプロパティ値を特定するには、チャネル 0 の低音ブーストプロパティを読み取るのみで十分です。この仮定と整合させるために、低音ブーストプロパティを設定するための対応する関数は、すべてのチャネルを同じ低音ブーストプロパティ値に設定します。これらは合理的な規則ですが、すべてのハードウェアベンダーが必ずしも従っているわけではありません。たとえば、ベンダーは、フルレンジスピーカーを駆動するチャネルに対してのみ低音ブーストを有効にするコントロールパネルアプリケーションを提供する場合があります。 (フルレンジスピーカーは、低音から高音まで、全範囲のサウンドを再生することができます。) その場合、前のコード例で取得したプロパティ値は、ストリームの低音ブースト状態を正確に表していない可能性があります。

前の表に示したコントロールインターフェイスを使用するクライアントは、IPart::RegisterControlChangeCallback メソッドを呼び出して、コントロールパラメーターの値が変更されたときの通知を登録できます。 IKsControl インターフェイスでは、プロパティ値が変更されたときの通知をクライアントが登録するための同様の手段は提供されないことに注意してください。 IKsControl がプロパティ変更通知をサポートしている場合、別のアプリケーションがプロパティ値を変更したときにアプリケーションに通知される可能性があります。ただし、IPart 通知によって監視される一般的に使用されるコントロールとは異なり、IKsControl によって管理されるプロパティは、主にハードウェアベンダーが使用することを目的としており、これらのプロパティはベンダーによって作成されたコントロールパネルアプリケーションによってのみ変更される可能性があります。アプリケーションが別のアプリケーションによって行われたプロパティの変更を検出する必要がある場合は、IKsControl を介してプロパティ値を定期的にポーリングすることで、変更を検出することができます。

プログラミングガイド

次の方法で共有

IKsControl インターフェイスを使用したオーディオプロパティへのアクセス

フィードバック

その他のリソース

次の方法で共有

IKsControl インターフェイスを使用したオーディオ プロパティへのアクセス

関連トピック

フィードバック

その他のリソース

IKsControl インターフェイスを使用したオーディオプロパティへのアクセス