Méthode IAudioProcessingObjectNotifications2 ::GetApoNotificationRegistrationInfo2 (audioengineextensionapo.h)

Appelé par le système pour permettre aux clients de s’inscrire pour recevoir des rappels de notification pour les notifications de point de terminaison APO et d’effet système. Cette méthode se comporte comme IAudioProcessingObjectNotifications ::GetApoNotificationRegistrationInfo avec l’ajout d’un paramètre qui peut être utilisé pour déterminer les types de notifications pris en charge sur la version de Windows exécutée sur l’appareil actuel.

Syntaxe

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

Paramètres

maxApoNotificationTypeSupported

Valeur de l’énumération APO_NOTIFICATION_TYPE indiquant la valeur d’énumération la plus élevée prise en charge sur la version de Windows exécutée sur l’appareil actuel. Les clients peuvent utiliser un opérateur de comparaison pour déterminer si un type de notification particulier est pris en charge.

[out] apoNotifications

Paramètre de sortie qui retourne un pointeur vers un tableau de APO_NOTIFICATION_DESCRIPTOR spécifiant l’ensemble des modifications APO pour lesquelles des notifications sont demandées.

[out] count

Paramètre de sortie spécifiant le nombre d’éléments retournés dans apoNotifications.

Valeur retournée

An HRESULT.

Remarques

L’exemple suivant illustre une implémentation classique de GetAppNotificationRegistrationInfo2. L’exemple vérifie la valeur du paramètre maxApoNotificationTypeSupported pour déterminer si les notifications qui l’intéressent sont prises en charge sur la version de Windows exécutée sur l’appareil actuel. et, si c’est le cas, s’inscrit pour ces notifications.

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;

}

Sur les versions de Windows antérieures à 22621, Windows appelle uniquement IAudioProcessingObjectNotifications ::GetApoNotificationRegistrationInfo, et non la méthode sur IAudioProcessingObjectNotifications2. Étant donné que le type de notification le plus élevé pris en charge sur les versions de Windows antérieures à 22621 était APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, une apo qui doit s’exécuter sur les versions 22621 et antérieures, peut choisir de simplifier son code à l’aide de l’implémentation suivante pour 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;
}

Pour plus d’informations sur les API Windows 11 pour les objets de traitement audio (API) qui peuvent être fournis avec des pilotes audio, consultez Windows 11 API pour les objets de traitement audio.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows build 22621
En-tête	audioengineextensionapo.h