IAudioProcessingObjectNotifications2::GetApoNotificationRegistrationInfo2 メソッド (audioengineextensionapo.h)

APO エンドポイントとシステム効果通知の通知コールバックをクライアントが受信できるように、システムによって呼び出されます。 このメソッドは 、IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo と同じように動作し、現在のデバイスで実行されている Windows のバージョンでサポートされている通知の種類を決定するために使用できるパラメーターを追加します。

構文

HRESULT GetApoNotificationRegistrationInfo2(
        APO_NOTIFICATION_TYPE       maxApoNotificationTypeSupported,
  [out] APO_NOTIFICATION_DESCRIPTOR **apoNotifications,
  [out] DWORD                       *count
);

パラメーター

maxApoNotificationTypeSupported

現在のデバイスで実行されている Windows のバージョンでサポートされている列挙値の最大値を示す、 APO_NOTIFICATION_TYPE 列挙からの値。 クライアントは、比較演算子を使用して、特定の通知の種類がサポートされているかどうかを判断できます。

[out] apoNotifications

通知が要求される APO 変更のセットを指定 APO_NOTIFICATION_DESCRIPTOR の配列へのポインターを返す出力パラメーター。

[out] count

apoNotifications で返される項目の数を指定する出力パラメーター。

戻り値

HRESULT。

注釈

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

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

    *apoNotificationDescriptorsReturned = nullptr;
    
    *count = 0;
    
    // Before this function can be called, our m_device member variable should already have been initialized.
    // This would typically be done in our implementation of IAudioProcessingObject::Initialize, by using
    // APOInitSystemEffects3::pDeviceCollection to obtain the last IMMDevice in the collection.
    
    RETURN_HR_IF_NULL(E_FAIL, m_device);
    
    if(maxApoNotificationTypeSupported >= APO_NOTIFICATION_TYPE_MICROPHONE_BOOST)
    {
    
        // Let the OS know what notifications we are interested in by returning an array of
        // APO_NOTIFICATION_DESCRIPTORs.
        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);
        
        // Our APO wants to get notified when the volume level changes on the audio endpoint.
        // The APO_NOTIFICATION_DESCRIPTOR::audioEndpointVolume element is used to specify the audio
        // endpoint for both the APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME and the
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2 notifications.
        apoNotificationDescriptors[0].type = APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2;
        (void)m_device.query_to(&apoNotificationDescriptors[0].audioEndpointVolume.device);
        
        // Our APO also wants to get notified when the orientation of the device changes.
        apoNotificationDescriptors[1].type = APO_NOTIFICATION_TYPE_DEVICE_ORIENTATION;
        
        // Our APO also wants to get notified when the microphone boost changes on the audio endpoint.
        apoNotificationDescriptors[2].type = APO_NOTIFICATION_TYPE_MICROPHONE_BOOST;
        (void)m_device.query_to(&apoNotificationDescriptors[2].audioMicrophoneBoost.device);
        
        // The OS will immediately fire a notification for the above notification types, so we do not
        // need to query the OS for the current values.
        
        *apoNotificationDescriptorsReturned = apoNotificationDescriptors.release();
        *count = numDescriptors;
    
    }
    else
    {
        // If we get here, the APO is running on an older version of Windows that does not support the
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2, APO_NOTIFICATION_TYPE_DEVICE_ORIENTATION, and
        // APO_NOTIFICATION_TYPE_MICROPHONE_BOOST notifications. What the APO does at this point is
        // implementation-specific. For example, the APO may choose to subscribe to the
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME notification instead of
        // APO_NOTIFICATION_TYPE_ENDPOINT_VOLUME2.
    }
    
    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)
{
    // When the OS invokes GetApoNotificationRegistrationInfo, it implies that the maximum notification value
    // that is supported is APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE.
    GetApoNotificationRegistrationInfo2(APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, apoNotificationDescriptorsReturned, count);
    
    return S_OK;
}

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

要件

要件	値
サポートされている最小のクライアント	Windows ビルド 22621
Header	audioengineextensionapo.h