Metodo IAudioProcessingObjectNotifications2::GetApoNotificationRegistrationInfo2 (audioengineextensionapo.h)

Articolo
03/22/2023

Chiamato dal sistema per consentire ai client di registrare per ricevere callback di notifica per gli endpoint APO e le notifiche degli effetti di sistema. Questo metodo si comporta come IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo con l'aggiunta di un parametro che può essere usato per determinare i tipi di notifiche supportati nella versione di Windows in esecuzione nel dispositivo corrente.

Sintassi

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

Parametri

maxApoNotificationTypeSupported

Valore dell'enumerazione APO_NOTIFICATION_TYPE che indica il valore di enumerazione più alto supportato nella versione di Windows in esecuzione nel dispositivo corrente. I client possono usare un operatore di confronto per determinare se è supportato un particolare tipo di notifica.

[out] apoNotifications

Parametro di output che restituisce un puntatore a una matrice di APO_NOTIFICATION_DESCRIPTOR specificando il set di modifiche APO per cui vengono richieste notifiche.

[out] count

Parametro di output che specifica il numero di elementi restituiti in apoNotifications.

Valore restituito

An HRESULT.

Commenti

Nell'esempio seguente viene illustrata un'implementazione tipica di GetAppNotificationRegistrationInfo2. Nell'esempio viene controllato il valore del parametro maxApoNotificationTypeSupported per determinare se le notifiche interessate sono supportate nella versione di Windows in esecuzione nel dispositivo corrente. e, in tal caso, registra per queste notifiche.

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;

}

Nelle versioni di Windows precedenti alla versione 22621, Windows chiamerà solo IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo e non il metodo in IAudioProcessingObjectNotifications2. Poiché il tipo di notifica più alto supportato nelle versioni di Windows precedenti a 22621 è stato APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE, un'APO che deve essere eseguita nelle versioni 22621 e versioni precedenti, può scegliere di semplificare il codice usando l'implementazione seguente per 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;
}

Per altre informazioni sulle API Windows 11 per gli oggetti di elaborazione audio (API) che possono essere forniti con driver audio, vedere api Windows 11 per oggetti di elaborazione audio.

Requisiti

Requisito	Valore
Client minimo supportato	Build di Windows 22621
Intestazione	audioengineextensionapo.h

Condividi tramite