IAudioProcessingObjectNotifications2::GetApoNotificationRegistrationInfo2 메서드(audioengineextensionapo.h)

클라이언트가 APO 엔드포인트 및 시스템 효과 알림에 대한 알림 콜백을 수신하도록 등록할 수 있도록 시스템에서 호출됩니다. 이 메서드는 현재 디바이스에서 실행되는 Windows 버전에서 지원되는 알림 유형을 확인하는 데 사용할 수 있는 매개 변수를 추가하여 IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo 와 동일하게 동작합니다.

구문

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

매개 변수

maxApoNotificationTypeSupported

현재 디바이스에서 실행되는 Windows 버전에서 지원되는 가장 높은 열거형 값을 나타내는 APO_NOTIFICATION_TYPE 열거형의 값입니다. 클라이언트는 비교 연산자를 사용하여 특정 알림 유형이 지원되는지 확인할 수 있습니다.

[out] apoNotifications

알림이 요청되는 APO 변경 내용 집합을 지정하는 APO_NOTIFICATION_DESCRIPTOR 배열에 대한 포인터를 반환하는 출력 매개 변수입니다.

[out] count

apoNotifications에 반환된 항목 수를 지정하는 출력 매개 변수입니다.

반환 값

Hresult.

설명

다음 예제에서는 GetAppNotificationRegistrationInfo2의 일반적인 구현을 보여 줍니다. 이 예제에서는 maxApoNotificationTypeSupported 매개 변수의 값을 확인하여 관심 있는 알림이 현재 디바이스에서 실행되는 Windows 버전에서 지원되는지 확인합니다. 이 경우 이러한 알림을 등록합니다.

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;

}

22621 이전의 Windows 버전에서 Windows는 IAudioProcessingObjectNotifications::GetApoNotificationRegistrationInfo만 호출하고 IAudioProcessingObjectNotifications2의 메서드는 호출하지 않습니다. 22621 이전의 Windows 버전에서 지원되는 가장 높은 알림 유형이 APO_NOTIFICATION_TYPE_SYSTEM_EFFECTS_PROPERTY_CHANGE 버전 22621 이상에서 실행해야 하는 APO는 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;
}

오디오 드라이버와 함께 제공할 수 있는 API(오디오 처리 개체)에 대한 Windows 11 API에 대한 자세한 내용은 오디오 처리 개체에 대한 Windows 11 API를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 빌드 22621
머리글	audioengineextensionapo.h