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

Llamado por el sistema para permitir que los clientes se registren para recibir devoluciones de llamada de notificación para las notificaciones del punto de conexión de APO y las notificaciones de efectos del sistema. Este método se comporta igual que IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo con la adición de un parámetro que se puede usar para determinar los tipos de notificaciones admitidos en la versión de Windows que se ejecuta en el dispositivo actual.

Sintaxis

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

Parámetros

maxApoNotificationTypeSupported

Valor de la enumeración APO_NOTIFICATION_TYPE que indica el valor de enumeración más alto admitido en la versión de Windows que se ejecuta en el dispositivo actual. Los clientes pueden usar un operador de comparación para determinar si se admite un tipo de notificación determinado.

[out] apoNotifications

Parámetro de salida que devuelve un puntero a una matriz de APO_NOTIFICATION_DESCRIPTOR especificando el conjunto de cambios de APO para los que se solicitan las notificaciones.

[out] count

Parámetro de salida que especifica el número de elementos devueltos en apoNotifications.

Valor devuelto

An HRESULT.

Comentarios

En el ejemplo siguiente se muestra una implementación típica de GetAppNotificationRegistrationInfo2. En el ejemplo se comprueba el valor del parámetro maxApoNotificationTypeSupported para determinar si las notificaciones en las que está interesado se admiten en la versión de Windows que se ejecuta en el dispositivo actual. y, si es así, se registra para estas notificaciones.

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;

}

En las versiones de Windows anteriores a 22621, Windows solo llamará a IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo y no al método en IAudioProcessingObjectNotifications2. Dado que se APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE el tipo de notificación más alto admitido en las versiones de Windows anteriores a 22621, un APO que necesita ejecutarse en las versiones 22621 y anteriores, puede optar por simplificar su código mediante la siguiente implementación para 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;
}

Para obtener más información sobre las API de Windows 11 para los objetos de procesamiento de audio (API) que se pueden enviar con controladores de audio, consulte Windows 11 API para objetos de procesamiento de audio.

Requisitos

Requisito	Value
Cliente mínimo compatible	Compilación 22621 de Windows
Encabezado	audioengineextensionapo.h