IAudioProcessingObjectNotifications2：：GetApoNotificationRegistrationInfo2 方法 (audioengineextensionapo.h)

由系統呼叫，以允許客戶端註冊以接收 APO 端點和系統效果通知的通知回呼。 這個方法的行為與 IAudioProcessingObjectNotifications：：GetApoNotificationRegistrationInfo 相同，並新增參數，可用來判斷目前裝置上執行的 Windows 版本所支援的通知類型。

語法

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

參數

maxApoNotificationTypeSupported

來自 APO_NOTIFICATION_TYPE 列舉的值，指出目前裝置上執行的 Windows 版本所支援的最高列舉值。 用戶端可以使用比較運算符來判斷是否支援特定的通知類型。

[out] apoNotifications

輸出參數，這個參數會傳回 APO_NOTIFICATION_DESCRIPTOR 陣列的指標，指定要求通知的 APO 變更集。

[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;
}

如需音訊處理物件的 Windows 11 API (API) 可隨附音訊驅動程式的詳細資訊，請參閱音訊處理物件的 Windows 11 API。

規格需求