IAudioProcessingObjectNotifications2::GetApoNotificationRegistrationInfo2-Methode (audioengineextensionapo.h)

Artikel
02/28/2024

Wird vom System aufgerufen, um Clients die Registrierung zu ermöglichen, um Benachrichtigungsrückrufe für APO-Endpunkt- und Systemeffektbenachrichtigungen zu empfangen. Diese Methode verhält sich genauso wie IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo mit einem Parameter, der verwendet werden kann, um die Benachrichtigungstypen zu bestimmen, die in der Auf dem aktuellen Gerät ausgeführten Windows-Version unterstützt werden.

Syntax

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

Parameter

maxApoNotificationTypeSupported

Ein Wert aus der APO_NOTIFICATION_TYPE-Enumeration , der den höchsten Enumerationswert angibt, der in der Auf dem aktuellen Gerät ausgeführten Windows-Version unterstützt wird. Clients können einen Vergleichsoperator verwenden, um zu bestimmen, ob ein bestimmter Benachrichtigungstyp unterstützt wird.

[out] apoNotifications

Ausgabeparameter, der einen Zeiger auf ein Array von APO_NOTIFICATION_DESCRIPTOR den Satz von APO-Änderungen angibt, für die Benachrichtigungen angefordert werden.

[out] count

Ausgabeparameter, der die Anzahl der in apoNotifications zurückgegebenen Elemente angibt.

Rückgabewert

Ein HRESULT.

Hinweise

Das folgende Beispiel veranschaulicht eine typische Implementierung von GetAppNotificationRegistrationInfo2. Im Beispiel wird der Wert des maxApoNotificationTypeSupported-Parameters überprüft, um festzustellen, ob die Benachrichtigungen, an denen es interessiert ist, in der Windows-Version unterstützt werden, die auf dem aktuellen Gerät ausgeführt wird. und registriert sich, falls ja, für diese Benachrichtigungen.

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;

}

In Windows-Versionen vor 22621 ruft Windows nur IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo und nicht die -Methode auf IAudioProcessingObjectNotifications2 auf. Da der höchste unterstützte Benachrichtigungstyp unter Windows-Versionen vor 22621 APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE war, kann ein APO, der unter Versionen 22621 und älter ausgeführt werden muss, den Code mithilfe der folgenden Implementierung für IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo vereinfachen.

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;
}

Weitere Informationen zu den Windows 11-APIs für die Audioverarbeitungsobjekte (Audio Processing Objects, APOs), die mit Audiotreibern ausgeliefert werden können, finden Sie unter Windows 11 APIs für Audioverarbeitungsobjekte.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Build 22621
Kopfzeile	audioengineextensionapo.h

Share via