/**
 * @file protocol_commands.h
 * @brief 上行协议命令发送
 */

#ifndef CORE_PROTOCOL_COMMANDS_H
#define CORE_PROTOCOL_COMMANDS_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct engine_internal_ctx engine_internal_ctx_t;

/* ---- 打断 ---- */

/** @brief 发送打断（立即停止 TTS）*/
int protocol_send_break(engine_internal_ctx_t *ctx);

/** @brief 发送带延时的打断开始（忽略 N ms 音频）*/
int protocol_send_break_begin(engine_internal_ctx_t *ctx, unsigned int delay_ms);

/** @brief 发送打断结束（提前恢复）*/
int protocol_send_break_end(engine_internal_ctx_t *ctx);

/* ---- 文本输入 ---- */

/** @brief 发送文本输入（绕过 ASR）*/
int protocol_send_text(engine_internal_ctx_t *ctx, const char *text);

/** @brief 发送 TTS 直接播报（不经 LLM）*/
int protocol_send_tts_direct(engine_internal_ctx_t *ctx, const char *text);

/* ---- 对话模式控制 ---- */

/** @brief 启用实时 ASR（唤醒词/语音打断模式）*/
int protocol_send_asr_enable_realtime(engine_internal_ctx_t *ctx);

/** @brief 禁用实时 ASR（切到按键模式）*/
int protocol_send_asr_disable_realtime(engine_internal_ctx_t *ctx);

/** @brief 按键开始录音 */
int protocol_send_asr_start_longtext(engine_internal_ctx_t *ctx);

/** @brief 按键松开停止录音 */
int protocol_send_asr_stop_longtext(engine_internal_ctx_t *ctx);

/* ---- 自动打断控制 ---- */

/** @brief 启用语音自动打断 */
int protocol_send_auto_int_enable(engine_internal_ctx_t *ctx);

/** @brief 禁用语音自动打断 */
int protocol_send_auto_int_disable(engine_internal_ctx_t *ctx);

/* ---- 设备信息 ---- */

/**
 * @brief 发送设备信息（鉴权通过后调用）
 * @param device_id 设备 ID（必填，否则云端 FC 失效）
 * @param user_id   用户 ID
 * @param asr_text_ext 是否启用 ASR 扩展（情绪/声纹）
 */
int protocol_send_device_info(engine_internal_ctx_t *ctx, const char *model,
                              const char *device_id, const char *user_id,
                              bool asr_text_ext);

/** @brief 动态更新 system prompt */
int protocol_send_update_system_prompt(engine_internal_ctx_t *ctx, const char *json_payload);

/** @brief 设置增强查询上下文 */
int protocol_send_enhance_query(engine_internal_ctx_t *ctx, const char *json_payload);

/* ---- 音色/角色切换 ---- */

/** @brief 切换 TTS 音色（VCN）*/
int protocol_send_switch_voice(engine_internal_ctx_t *ctx, const char *vcn_id);

/** @brief 切换场景角色 */
int protocol_send_switch_scene_role(engine_internal_ctx_t *ctx, const char *json_payload);

/* ---- FC 结果 ---- */

/**
 * @brief 发送 FC 执行结果
 * @param session_id FC 请求的 session_id
 * @param result     "ok" 或 "error"
 * @param message    结果描述
 */
int protocol_send_fc_result(engine_internal_ctx_t *ctx, const char *session_id,
                            const char *result, const char *message);

/* ---- 云端音乐控制 ---- */

/** @brief 停止远程播放 */
int protocol_send_remote_player_stop(engine_internal_ctx_t *ctx);

/** @brief 暂停远程播放 */
int protocol_send_remote_player_pause(engine_internal_ctx_t *ctx);

/** @brief 恢复远程播放 */
int protocol_send_remote_player_resume(engine_internal_ctx_t *ctx);

/* ---- MCP ---- */

/** @brief 通知服务端 MCP tools 已变更 */
int protocol_send_mcp_tools_changed(engine_internal_ctx_t *ctx);

#ifdef __cplusplus
}
#endif

#endif /* CORE_PROTOCOL_COMMANDS_H */
