IAudioProcessingObjectNotifications2

APO エンドポイント通知およびシステム エフェクト通知に関する一般的なオーディオ関連の通知を登録して受け取るために、クライアントによって実装されます。このインターフェイスは、現在のデバイスで実行されている Windows のバージョンでサポートされる通知の種類を判別する機能を追加します。

オーディオ ドライバーに同梱できるオーディオ処理オブジェクト (APO) 向けの Windows 11 API の詳細については、Windows 11 APIs for Audio Processing Objects を参照してください。

APO エンドポイント通知およびシステム エフェクト通知の通知コールバックを受け取るためにクライアントが登録できるよう、システムによって呼び出されます。このメソッドは、現在のデバイスで実行されている Windows のバージョンでサポートされる通知の種類を判別するために使用できるパラメーターを追加します。

HRESULT。

次の例は、GetAppNotificationRegistrationInfo2 の一般的な実装を示しています。この例では、maxApoNotificationTypeSupported パラメーターの値を確認して、対象とする通知が現在のデバイスで実行されている Windows のバージョンでサポートされているかどうかを判別し、サポートされている場合はそれらの通知を登録します。

STDMETHODIMP SampleApo::GetApoNotificationRegistrationInfo2(
    UINT32 maxApoNotificationTypeSupported,
    APO_NOTIFICATION_DESCRIPTOR** apoNotificationDescriptorsReturned,
    DWORD* count)
{

    *apoNotificationDescriptorsReturned = nullptr;

    *count = 0;

    // この関数を呼び出す前に、メンバー変数 m_device が既に初期化されている必要があります。
    // これは通常、IAudioProcessingObject::Initialize の実装内で、
    // APOInitSystemEffects3::pDeviceCollection を使用してコレクション内の最後の IMMDevice を取得することで行います。

    RETURN_HR_IF_NULL(E_FAIL, m_device);

    if(maxApoNotificationTypeSupported >= APO_NOTIFICATION_TYPE_MICROPHONE_BOOST)
    {

        // APO_NOTIFICATION_DESCRIPTOR の配列を返すことで、対象とする通知を OS に通知します。
        constexpr DWORD numDescriptors = 3;
        wil::unique_cotaskmem_ptr<APO_NOTIFICATION_DESCRIPTOR[]> apoNotificationDescriptors;
        apoNotificationDescriptors.reset(static_cast<APO_NOTIFICATION_DESCRIPTOR*>(
        CoTaskMemAlloc(sizeof(APO_NOTIFICATION_DESCRIPTOR) * numDescriptors)));
        RETURN_IF_NULL_ALLOC(apoNotificationDescriptors);

        // この APO は、オーディオ エンドポイントの音量レベルが変化したときに通知を受け取ることを望んでいます。
        // APO_NOTIFICATION_DESCRIPTOR::audioEndpointVolume 要素は、APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME と
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2 の両方の通知でオーディオ エンドポイントを指定するために使用されます。
        apoNotificationDescriptors[0].type = APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2;
        (void)m_device.query_to(&apoNotificationDescriptors[0].audioEndpointVolume.device);

        // この APO は、デバイスの向きが変化したときにも通知を受け取ることを望んでいます。
        apoNotificationDescriptors[1].type = APO_NOTIFICATION_TYPE_DEVICE_ORIENTATION;

        // この APO は、オーディオ エンドポイントのマイク ブーストが変化したときにも通知を受け取ることを望んでいます。
        apoNotificationDescriptors[2].type = APO_NOTIFICATION_TYPE_MICROPHONE_BOOST;
        (void)m_device.query_to(&apoNotificationDescriptors[2].audioMicrophoneBoost.device);

        // OS は上記の通知の種類に対して直ちに通知を発行するため、OS に現在の値を問い合わせる必要はありません。

        *apoNotificationDescriptorsReturned = apoNotificationDescriptors.release();
        *count = numDescriptors;

    }
    else
    {
        // ここに到達した場合、APO は APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2、APO_NOTIFICATION_TYPE_DEVICE_ORIENTATION、
        // APO_NOTIFICATION_TYPE_MICROPHONE_BOOST の各通知をサポートしていない古いバージョンの Windows 上で実行されています。
        // この時点で APO が何を行うかは実装に依存します。たとえば、APO は
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2 の代わりに APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME 通知を
        // サブスクライブすることを選択できます。
    }

    return S_OK;

}

22621 より前のバージョンの Windows では、Windows は IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo のみを呼び出し、IAudioProcessingObjectNotifications2 のメソッドは呼び出しません。22621 より前のバージョンの Windows でサポートされる最も高い通知の種類は APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE であったため、バージョン 22621 以前で実行する必要がある APO は、IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo に対して次の実装を使用することでコードを簡略化できます。

STDMETHODIMP SampleApo::GetApoNotificationRegistrationInfo(
    APO_NOTIFICATION_DESCRIPTOR** apoNotificationDescriptorsReturned,
    DWORD* count)
{
    // OS が GetApoNotificationRegistrationInfo を呼び出す場合、サポートされる最大の通知値が
    // APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE であることを意味します。
    GetApoNotificationRegistrationInfo2(APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, apoNotificationDescriptorsReturned, count);

    return S_OK;
}

オーディオ ドライバーに同梱できるオーディオ処理オブジェクト (APO) 向けの Windows 11 API の詳細については、Windows 11 APIs for Audio Processing Objects を参照してください。