/**
 * @file aiagent_engine.h
 * @brief AI Agent SDK 公开引擎接口
 */

#ifndef AIAGENT_ENGINE_H
#define AIAGENT_ENGINE_H

#include "aiagent_types.h"
#include "aiagent_config.h"

#ifdef __cplusplus
extern "C" {
#endif

/* 引擎不透明句柄 */
typedef void *aiagent_engine_t;

/* ========== 生命周期 ========== */

/**
 * @brief 创建引擎实例
 * @param callbacks 事件回调
 * @return 引擎句柄，失败返回 NULL
 */
aiagent_engine_t aiagent_engine_create(const aiagent_callbacks_t *callbacks);

/**
 * @brief 初始化引擎配置
 * @param engine 引擎句柄
 * @param config 引擎配置
 * @return AIAGENT_OK 成功
 */
int aiagent_engine_init(aiagent_engine_t engine, const aiagent_config_t *config);

/**
 * @brief 启动引擎（建立连接并开始交互）
 */
int aiagent_engine_start(aiagent_engine_t engine);

/**
 * @brief 停止引擎（断开连接、释放音频资源）
 */
void aiagent_engine_stop(aiagent_engine_t engine);

/**
 * @brief 销毁引擎并释放所有资源
 */
void aiagent_engine_destroy(aiagent_engine_t engine);

/* ========== 运行时控制 ========== */

/**
 * @brief 开始录音（按键模式按下时调用）
 */
int aiagent_engine_start_record(aiagent_engine_t engine);

/**
 * @brief 停止录音（按键模式松开时调用）
 */
int aiagent_engine_stop_record(aiagent_engine_t engine);

/**
 * @brief 打断 AI（停止 TTS 并发送 break）
 */
int aiagent_engine_interrupt(aiagent_engine_t engine);

/**
 * @brief 带延时的打断（之后忽略 N 毫秒输入音频）
 * @param delay_ms 延时毫秒数
 */
int aiagent_engine_interrupt_delay(aiagent_engine_t engine, unsigned int delay_ms);

/**
 * @brief 直接发送文本输入（绕过 ASR）
 * @param text UTF-8 文本
 */
int aiagent_engine_send_text(aiagent_engine_t engine, const char *text);

/**
 * @brief 直接发送 TTS 文本（绕过 LLM，仅合成播放）
 */
int aiagent_engine_send_tts_direct(aiagent_engine_t engine, const char *text);

/**
 * @brief 发送原始 PCM 音频（外部采集模式）
 * @param data PCM 音频缓冲区
 * @param len 字节数
 */
int aiagent_engine_send_audio(aiagent_engine_t engine, const uint8_t *data, size_t len);

/**
 * @brief 设置播放音量
 * @param volume 0-100
 */
int aiagent_engine_set_volume(aiagent_engine_t engine, int volume);

/**
 * @brief 运行时切换交互模式
 */
int aiagent_engine_switch_mode(aiagent_engine_t engine, aiagent_interact_mode_t mode);

/**
 * @brief 切换 TTS 音色
 * @param voice_id vcn 标识
 */
int aiagent_engine_switch_voice(aiagent_engine_t engine, const char *voice_id);

/**
 * @brief 切换场景角色
 * @param json 含 tts/scene_role 字段的 JSON
 */
int aiagent_engine_switch_scene_role(aiagent_engine_t engine, const char *json);

/**
 * @brief 上报 function call 执行结果
 * @param session_id FC 会话 ID
 * @param result "ok" 或 "error"
 * @param message 结果描述
 */
int aiagent_engine_send_fc_result(aiagent_engine_t engine,
                                   const char *session_id,
                                   const char *result,
                                   const char *message);

/**
 * @brief 动态更新 system prompt
 * @param json_payload 含 model_type 和 prompt 的 JSON
 */
int aiagent_engine_update_system_prompt(aiagent_engine_t engine, const char *json_payload);

/**
 * @brief 设置增强查询上下文
 * @param json_payload 含 enhance_type、pre_query、post_query 的 JSON
 */
int aiagent_engine_set_enhance_query(aiagent_engine_t engine, const char *json_payload);

/**
 * @brief 开关语音自动打断
 */
int aiagent_engine_set_auto_interrupt(aiagent_engine_t engine, bool enable);

/**
 * @brief 发送原始事件/命令字符串
 *
 * 用于无专用 API 的自定义 SET 命令，例如：
 *   "[SET]:[MEDIA_GENERATE_MODE]:[TRUE]"
 *   "[SET]:[UPDATE_VISION_MODE]:{...}"
 */
int aiagent_engine_send_event(aiagent_engine_t engine, const char *event_str);

/**
 * @brief 更新视觉模式
 * @param vision_mode 0=单帧，1=连续视频流
 * @param expire_sec 过期秒数，0 表示不过期
 */
int aiagent_engine_update_visual_mode(aiagent_engine_t engine, int vision_mode, int expire_sec);

/**
 * @brief 发送 JPEG 图像数据（视觉理解）
 */
int aiagent_engine_send_video(aiagent_engine_t engine, const uint8_t *data, size_t len);

/**
 * @brief 云端音乐：停止
 */
int aiagent_engine_remote_player_stop(aiagent_engine_t engine);

/**
 * @brief 云端音乐：暂停
 */
int aiagent_engine_remote_player_pause(aiagent_engine_t engine);

/**
 * @brief 云端音乐：恢复
 */
int aiagent_engine_remote_player_resume(aiagent_engine_t engine);

/**
 * @brief 通知按键按下事件
 */
int aiagent_engine_notify_key_press(aiagent_engine_t engine);

/**
 * @brief 通知按键松开事件
 */
int aiagent_engine_notify_key_release(aiagent_engine_t engine);

/**
 * @brief 通知按键长按事件
 */
int aiagent_engine_notify_key_long_press(aiagent_engine_t engine);

/**
 * @brief 通知唤醒词检测事件（仅唤醒词模式生效）
 */
int aiagent_engine_notify_wakeword(aiagent_engine_t engine);

/* ========== 状态查询 ========== */

/**
 * @brief 获取当前引擎状态
 */
aiagent_state_t aiagent_engine_get_state(aiagent_engine_t engine);

/**
 * @brief 引擎是否处于活动状态（非 IDLE/EXITING）
 */
bool aiagent_engine_is_busy(aiagent_engine_t engine);

#ifdef __cplusplus
}
#endif

#endif /* AIAGENT_ENGINE_H */
