IAudioEffectsManager：：SetAudioEffectState 方法 (audioclient.h)

設定指定音訊效果的狀態。

語法

HRESULT SetAudioEffectState(
  GUID               effectId,
  AUDIO_EFFECT_STATE state
);

參數

effectId

正在變更狀態之效果的 GUID 識別碼。 音訊效果 GUID 定義於 ksmedia.h 中。

state

AUDIO_EFFECT_STATE列舉 的值 ，指定要設定的狀態。

傳回值

傳回 HRESULT，包括但不限於下列專案。

值	描述
S_OK	Success
AUDCLNT_E_EFFECT_NOT_AVAILABLE	指定的效果無法使用
AUDCLNT_E_EFFECT_STATE_READ_ONLY	指定的效果具有只讀狀態
AUDCLNT_E_DEVICE_INVALIDATED	相關聯的音訊數據流已終結。

備註

藉由呼叫 GetAudioEffects，取得相關聯音訊數據流的音訊效果目前清單。

範例

下列範例示範如何使用 IAudioEffectsManager.SetAudioEffectState 來停用 AUDIO_EFFECT_TYPE_DEEP_NOISE_SUPPRESSION 效果。

HRESULT TryDisablePlatformDeepNoiseSuppression(_In_ IAudioClient *client)
{
    wil::com_ptr_nothrow<IAudioEffectsManager> audioEffectsManager;
    RETURN_IF_FAILED(client->GetService(IID_PPV_ARGS(&audioEffectsManager)));
    wil::unique_cotaskmem_array_ptr<AudioEffect> effects;
    UINT32 numEffects;
    RETURN_IF_FAILED(audioEffectsManager->GetAudioEffects(&effects, &numEffects));

    for (UINT32 i = 0; i < numEffects; i++)
    {
        if (effects[i].id == AUDIO_EFFECT_TYPE_DEEP_NOISE_SUPPRESSION)
        {
            // Check if deep noise suppression can be set and if it is currently on
            if (effects[i].canSetState && effects[i].state == AUDIO_EFFECT_STATE_ON)
            {
                HRESULT hr = audioEffectsManager->SetAudioEffectState(effects[i].id, AUDIO_EFFECT_STATE_OFF);

                // If canSetState changed to false, or the effect was removed, SetAudioEffectState
                // can fail with one of the following error codes.
                if (hr != AUDCLNT_E_EFFECT_NOT_AVAILABLE && hr != AUDCLNT_E_EFFECT_STATE_READ_ONLY)
                {
                    return hr;
                }
            }

            return S_OK;
        }
    }

    return S_OK;
}

下列範例示範如何使用 IAudioEffectsManager.SetAudioEffectState 來啟用 AUDIO_EFFECT_TYPE_DEEP_NOISE_SUPPRESSION 效果。

HRESULT TryEnablePlatformDeepNoiseSuppression(_In_ IAudioClient *client)
{
    wil::com_ptr_nothrow<IAudioEffectsManager> audioEffectsManager;
    RETURN_IF_FAILED(client->GetService(IID_PPV_ARGS(&audioEffectsManager)));
    wil::unique_cotaskmem_array_ptr<AUDIO_EFFECT> effects;
    UINT32 numEffects;
    RETURN_IF_FAILED(audioEffectsManager->GetAudioEffects(&effects, &numEffects));

    for (UINT32 i = 0; i < numEffects; i++)
    {
        if (effects[i].id == AUDIO_EFFECT_TYPE_DEEP_NOISE_SUPPRESSION)
        {
            // Check if deep noise suppression can be set and if it is currently off
            if (effects[i].canSetState && effects[i].state == AUDIO_EFFECT_STATE_OFF)
            {
                HRESULT hr = audioEffectsManager->SetAudioEffectState(effects[i].id, AUDIO_EFFECT_STATE_ON);

                // If canSetState changed to false, or the effect was removed, SetAudioEffectState
                // can fail with one of the following error codes.
                if (hr != AUDCLNT_E_EFFECT_NOT_AVAILABLE && hr != AUDCLNT_E_EFFECT_STATE_READ_ONLY)
                {
                    return hr;
                }
            }

            return S_OK;
        }
        }

        return S_OK;
}

規格需求

需求	值
最低支援的用戶端	Windows 組建 22000
標頭	audioclient.h