/**
 * Copyright (c) 2025 Tencent. All rights reserved.
 * Module：   TMGAudioCtrl@GMESDK
 * Function： 腾讯云 GME 音频控制相关功能接口。
 */
import 'dart:ffi';
import 'tmg_type.dart';

abstract class ITMGAudioCtrl {
    /////////////////////////////////////////////////////////////////////////////////
    //
    //                              音频控制
    //
    /////////////////////////////////////////////////////////////////////////////////

    /**
     * 开启或关闭麦克风。
     *
     * 此接口用来开启/关闭麦克风，并推送音频流到房间，需要在**接收到进房成功事件后**调用，加入房间默认不会打开麦克风。
     * {@link EnableMic}(boolean) = {@link EnableAudioCaptureDevice}(boolean) + {@link EnableAudioSend}(boolean)。
     * @param enable true：开启  false：关闭。
     */
    int EnableMic(bool enable);

    /**
     * 麦克风状态获取。
     *
     * 此接口用于获取麦克风状态，返回值 0 为关闭麦克风状态，返回值 1 为打开麦克风状态。
     */
    int GetMicState();

    /**
     * 开启或关闭扬声器。
     *
     * 此接口用于开启/关闭扬声器，并接收远端的音频流，需要在**接收到进房成功事件后**调用，加入房间默认不会打开扬声器。
     * {@link EnableSpeaker}(boolean) = {@link EnableAudioPlayDevice}(boolean) + {@link EnableAudioRecv}(boolean)。
     * @param enable true：开启  false：关闭。
     */
    int EnableSpeaker(bool enable);

    /**
     * 扬声器状态获取。
     *
     * 此接口用于扬声器状态获取。返回值 0 为关闭扬声器状态，返回值 1 为打开扬声器状态。
     */
    int GetSpeakerState();

    /**
     * 开启音频采集设备。
     *
     * 此接口用来开启/关闭采集设备，需要在**接收到进房成功事件后**调用，加入房间默认不打开采集设备。
     * @param enable true：开启  false：关闭。
     */
    int EnableAudioCaptureDevice(bool enable);

    /**
     * 获取采集设备状态。
     *
     * 此接口用于采集设备状态获取。
     */
    bool IsAudioCaptureDeviceEnabled();

    /**
     * 开启或关闭播放设备。
     *
     * 此接口用于开启关闭播放设备，需要在**接收到进房成功事件后**调用，加入房间默认不打开播放设备。
     * @param enable true：开启  false：关闭。
     */
    int EnableAudioPlayDevice(bool enable);

    /**
     * 获取播放设备状态。
     *
     * 此接口用于获取播放设备状态。
     */
    bool IsAudioPlayDeviceEnabled();

    /**
     * 打开关闭音频上行。
     *
     * 此接口用于打开/关闭音频上行，需要在**接收到进房成功事件后**调用，用来控制否是将采集到的音频数据发送给远端用户。如果采集设备已经打开，那么会发送采集到的音频数据。如果采集设备没有打开，那么仍旧无声。采集设备的打开关闭请参见接口  {@link
     * EnableAudioCaptureDevice}。
     * @param enable true：打开  false：关闭。
     */
    int EnableAudioSend(bool enable);

    /**
     * 获取音频上行状态。
     *
     * 此接口用于音频上行状态获取。
     */
    bool IsAudioSendEnabled();

    /**
     * 打开或关闭音频下行。
     *
     * 此接口用于打开/关闭音频下行，需要在**接收到进房成功事件后**调用，用于控制是否接收远端用户的音频数据。如果播放设备已经打开，那么会播放房间里其他人的音频数据。如果播放设备没有打开，那么仍旧无声。播放设备的打开关闭参见接口请参见接口 {@link
     * EnableAudioPlayDevice}。
     * @param enable true：打开  false：关闭。
     */
    int EnableAudioRecv(bool enable);

    /**
     * 获取音频下行状态。
     *
     * 此接口用于音频下行状态获取。
     */
    bool IsAudioRecvEnabled();

    /**
     * 设置麦克风音量的增益。
     *
     * 此接口用于设置麦克风音量的增益。
     * @param volume 音量增益大小，取值 [0，200]，其中 100 为默认值，相当于音量大小不增不减。
     */
    int SetMicVolume(int volume);

    /**
     * 获取麦克风音量的增益。
     *
     * 获取使用 {@link SetMicVolume} 设置的麦克风音量增益大小。
     */
    int GetMicVolume();

    /**
     * 设置扬声器音量增益。
     *
     * 此接口用于设置扬声器音量的增益。
     * @param volume 音量增益大小，取值 [0，200]，其中 100 为默认值，相当于音量大小不增不减。
     */
    int SetSpeakerVolume(int volume);

    /**
     * 获取扬声器音量增益。
     *
     * 获取使用 {@link SetSpeakerVolume} 设置的扬声器音量增益大小。
     */
    int GetSpeakerVolume();

    /**
     * 动态设置房间内某成员音量增益。
     *
     * @param userID      用户 ID。
     * @param volume      音量增益大小，取值 [0，200]，其中 100 为默认值，相当于音量大小不增不减。
     */
    int SetSpeakerVolumeByUserID(String userID, int volume);

    /**
     * 获取设置的房间内成员音量增益。
     *
     * 获取通过{@link SetSpeakerVolumeByUserID}接口设置的音量增益。
     * @param userID      用户 ID。
     */
    int GetSpeakerVolumeByUserID(String userID);

    /**
     * 开启/关闭耳返。
     *
     * @param enable      是否开启耳返。
     */
    int EnableLoopBack(bool enable);

    /**
     * 设置耳返音量。
     *
     * 此接口用于设置耳返的音量大小。
     * @param volume      音量大小，取值 [0，200]，其中 100 为默认值，相当于音量大小不增不减。
     */
    int SetLoopBackVolume(int volume);

    /**
     * 禁言房间中某个用户。
     *
     * 将某个用户加入音频数据黑名单，即不接受该用户的语音， 只对本端生效，不会影响其他端。返回值为 0 表示调用成功。
     * @param userID      用户 ID。
     */
    int AddAudioBlackList(String userID);

    /**
     * 解除对房间中某个用户的禁言。
     *
     * 将某个用户移除音频数据黑名单。返回值为0表示调用成功。
     * @param userID      用户 ID。
     */
    int RemoveAudioBlackList(String userID);

    /**
     * 查询某个用户是否被禁言。
     *
     * @param userID      用户 ID。
     */
    bool IsUserIDInAudioBlackList(String userID);

    /**
     * 开启或关闭 3D 音效。
     *
     * 此函数用于开启或关闭 3D 音效。开启之后可以听到 3D 音效。
     * @param enable           是否开启 3D 音效。
     */
    int EnableSpatializer(bool enable);

    /**
     * 获取当前 3D 音效状态。
     *
     * 此函数用于获取当前 3D 音效状态。
     */
    bool IsEnableSpatializer();

    /**
     * 开启音量回调。
     *
     * @param interval 音量回调周期，单位（秒）。
     * @note
     *   通过 ITMG_MAIN_EVENT_TYPE_USER_VOLUMES 事件返回用户音量数据。
     */
    int TrackingVolume(double interval);

    /**
     * 停止音量回调。
     */
    int StopTrackingVolume();

    /**
     * 获取实时麦克风音量。
     */
    int GetMicLevel();

    /**
     * 获取实时扬声器音量。
     */
    int GetSpeakerLevel();

    /**
     * 获取音频上行实时音量。
     */
    int GetSendStreamLevel();

    /**
     * 获取房间内其他成员下行实时音量。
     *
     * @param userID 房间其他成员的 ID。
     */
    int GetRecvStreamLevel(String userID);
}
