Метод 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;

}

В версиях Windows до 22621 Windows будет вызывать только метод IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo, а не метод iAudioProcessingObjectNotifications2. Так как самый высокий поддерживаемый тип уведомлений в версиях Windows до 22621 был APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, APO, который должен работать в версиях 22621 и более ранних, может упростить свой код, используя следующую реализацию для 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 для объектов обработки звука (APOs), которые могут поставляться с аудиодрайверами, см. в статье Windows 11 API для объектов обработки звука.

Требования

Требование	Значение
Минимальная версия клиента	Сборка Windows 22621
Верхняя часть	audioengineextensionapo.h