IKsJackDescription

IKsJackDescription インターフェイスは、オーディオアダプター上のデバイスと、外部または内部のエンドポイントデバイス(たとえばマイクや CD プレーヤー)との間で物理的な接続を提供するジャックまたは内部コネクターに関する情報を提供します。

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

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

   control mmsys.cpl

   あるいは、タスクバーの右側にある通知領域のスピーカーアイコンを右クリックし、再生デバイスまたは録音デバイスのいずれかを選択して Mmsys.cpl を実行することもできます。

2. Mmsys.cpl ウィンドウが開いたら、再生デバイスの一覧または録音デバイスの一覧からデバイスを選択し、プロパティをクリックします。
3. プロパティウィンドウが開いたら、全般をクリックします。選択したプロパティページにそのデバイスのジャック情報が表示される場合、そのデバイスは IKsJackDescription インターフェイスをサポートしています。プロパティページに「No jack information is available」というテキストが表示される場合、そのデバイスはこのインターフェイスをサポートしていません。

//-----------------------------------------------------------
// 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 インターフェイスのアドレスを関数が書き込むポインター値を指します。インターフェイスが存在しない場合、関数は *ppJackDesc に NULL を書き込み、エラーコード E_NOINTERFACE を返します。

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

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

メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、以下の表に示す値が含まれますが、これらに限定されません。

複数のチャネルを含むストリームを再生または録音するオーディオエンドポイントデバイスは、複数のジャック(物理コネクター)による接続を必要とする場合があります。

たとえば、6 チャネルのオーディオストリームを再生するサラウンドスピーカーのセットは、3 つのステレオジャックを必要とする場合があります。この例では、1 番目のジャックは前方左と前方右のスピーカー用のチャネルを伝送し、2 番目のジャックは前方中央と低周波効果(サブウーファー)のスピーカー用のチャネルを伝送し、3 番目のジャックは側方左と側方右のスピーカー用のチャネルを伝送します。

このメソッドを呼び出してジャック数を取得した後、各ジャックについて IKsJackDescription::GetJackDescription メソッドを 1 回ずつ呼び出して、ジャックの説明を取得します。

GetJackDescription メソッドは、オーディオジャックの説明を取得します。

メソッドが成功した場合は S_OK を返します。失敗した場合、返される可能性のあるコードには、以下の表に示す値が含まれますが、これらに限定されません。

ユーザーがオーディオエンドポイントデバイスをジャックに差し込む、またはジャックから抜く必要がある場合、オーディオアプリケーションはこのメソッドから取得した説明情報を使用して、ユーザーがジャックを見つけるのを支援できます。この情報には次のものが含まれます。

• コンピューターのシャーシまたは外部ボックス上のジャックの物理的な位置。
• ジャックの色。
• ジャックに使用されている物理コネクターの種類。
• ジャックへのチャネルのマッピング。