/**
 * @file aiagent_scene.h
 * @brief 场景应用注册接口
 *
 * 场景是可插拔的应用配置（如 AI 玩具、AI 学习机），
 * 每个场景提供独立配置并处理业务事件。
 */

#ifndef AIAGENT_SCENE_H
#define AIAGENT_SCENE_H

#include "aiagent_engine.h"

#ifdef __cplusplus
extern "C" {
#endif

#define AIAGENT_SCENE_NAME_MAX  32

/**
 * @brief 场景操作回调集合（所有回调可选，NULL 表示不处理）
 */
typedef struct {
    const char *name;                       /* 场景标识 */

    /* 配置提供者 */
    const aiagent_config_t* (*get_config)(void);

    /* 生命周期钩子 */
    int  (*on_init)(aiagent_engine_t engine);
    void (*on_start)(aiagent_engine_t engine);
    void (*on_stop)(aiagent_engine_t engine);
    void (*on_destroy)(void);

    /* 事件钩子 */
    void (*on_state_change)(aiagent_state_t old_state, aiagent_state_t new_state);

    /* ASR 文本回调（含情绪/声纹扩展，ext 为 NULL 表示无扩展） */
    void (*on_asr_result)(const char *text, bool is_final, const aiagent_asr_ext_t *ext);

    /* Function Call 处理：返回 1=已处理，0=fallback 到内置 FC */
    int  (*on_function_call)(const char *session_id, const char *name, const char *params);

    void (*on_event)(aiagent_event_type_t event, const char *data, size_t data_len);
    void (*on_key_event)(int action, int key_value);
    void (*on_network_event)(int event);
} aiagent_scene_ops_t;

/**
 * @brief 注册场景（启动前调用）
 * @param scene 场景操作集合（须为静态生命周期）
 * @return AIAGENT_OK 成功
 */
int aiagent_scene_register(const aiagent_scene_ops_t *scene);

/**
 * @brief 按名称启动已注册的场景
 */
int aiagent_scene_start(const char *scene_name);

/**
 * @brief 停止当前运行的场景
 */
void aiagent_scene_stop(void);

/**
 * @brief 获取当前激活的场景名（无激活返回 NULL）
 */
const char *aiagent_scene_get_active(void);

/**
 * @brief 获取当前激活场景的引擎句柄（无激活场景返回 NULL）
 */
aiagent_engine_t aiagent_scene_get_engine(void);

/**
 * @brief 通知场景网络事件（在网络连接/断开时调用）
 */
void aiagent_scene_notify_network(int event);

/**
 * @brief 通知场景按键事件
 */
void aiagent_scene_notify_key(int action, int key_value);

#ifdef __cplusplus
}
#endif

#endif /* AIAGENT_SCENE_H */
