Compartilhar via

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

  • Artigo

Chamado pelo sistema para permitir que os clientes se registrem para receber retornos de chamada de notificação para notificações de efeito de sistema e ponto de extremidade do APO. Esse método se comporta da mesma forma que IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo com a adição de um parâmetro que pode ser usado para determinar os tipos de notificações com suporte na versão do Windows em execução no dispositivo atual.

Sintaxe

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

Parâmetros

maxApoNotificationTypeSupported

Um valor da enumeração APO_NOTIFICATION_TYPE indicando o valor de enumeração mais alto com suporte na versão do Windows em execução no dispositivo atual. Os clientes podem usar um operador de comparação para determinar se há suporte para um tipo de notificação específico.

[out] apoNotifications

Parâmetro de saída que retorna um ponteiro para uma matriz de APO_NOTIFICATION_DESCRIPTOR especificando o conjunto de alterações de APO para as quais as notificações são solicitadas.

[out] count

Parâmetro de saída que especifica o número de itens retornados em apoNotifications.

Retornar valor

Um HRESULT.

Comentários

O exemplo a seguir ilustra uma implementação típica de GetAppNotificationRegistrationInfo2. O exemplo verifica o valor do parâmetro maxApoNotificationTypeSupported para determinar se as notificações nas quais ele está interessado têm suporte na versão do Windows em execução no dispositivo atual. e, nesse caso, registra-se para essas notificações.

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;

}

Nas versões do Windows anteriores à 22621, o Windows chamará apenas IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo, e não o método em IAudioProcessingObjectNotifications2. Como o tipo de notificação com suporte mais alto em versões do Windows anteriores à 22621 era APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, um APO que precisa ser executado nas versões 22621 e mais antigas, pode optar por simplificar seu código usando a implementação a seguir 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 obter mais informações sobre as APIs de Windows 11 para APOs (Objetos de Processamento de Áudio) que podem ser enviadas com drivers de áudio, consulte APIs Windows 11 para objetos de processamento de áudio.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows build 22621
Cabeçalho audioengineextensionapo.h