stc32g128k/App/app_manager.h

#ifndef __APP_MANAGER_H__
#define __APP_MANAGER_H__

#include "config.h"

// 动态挂载的 WristbandApp 控制块定义
typedef struct WristbandApp {
    u8 app_id;                     // 应用唯一识别 ID
    char *app_name;                // 应用名称
    void (*OnStart)(void);         // 启动生命周期，进入前台时调用
    void (*onRun)(void);           // 轮询生命周期，主循环每次被调度
    void (*onClose)(void);         // 关闭生命周期，退出前台/后台时清理资源
    EventResult (*onEvent)(SystemEvent *evt); // 事件处理生命周期，接收按键事件
} WristbandApp;

/**
 * @brief 初始化应用管理器
 * @details 将前台活跃槽位与后台的三个槽位全部清空为 NULL。
 */
void AppManager_Init(void);

/**
 * @brief 动态将一个应用切换至前台活跃运行
 * @param app 目标应用的结构体指针
 * @return bit 1-切换成功，0-失败
 * @details 流程：
 *          1. 若前台已有应用运行，且该应用未挂载在后台，则对其执行 onClose() 关闭生命周期。
 *          2. 将 fg_app 指针指向新的 app。
 *          3. 若该 app 目前并未在后台槽位中运行，则执行其 OnStart() 启动生命周期。
 */
bit AppManager_SwitchToForeground(WristbandApp *app);

/**
 * @brief 动态将一个应用挂载到后台槽位
 * @param app 目标应用的结构体指针
 * @return bit 1-挂载成功，0-槽位已满挂载失败
 * @details 后台总共支持 3 个槽位。若挂载成功，其 onRun 将会持续在主循环中被轮询。
 */
bit AppManager_AttachToBackground(WristbandApp *app);

/**
 * @brief 动态将一个应用从后台卸载
 * @param app 目标应用的结构体指针
 * @details 从后台槽位数组中移除该指针。若该应用当前也不在前台运行，将对其执行 onClose() 清理外设。
 */
void AppManager_DetachFromBackground(WristbandApp *app);

/**
 * @brief 将捕获的事件派发给前台活跃应用
 * @param evt 系统派发来的事件
 */
void AppManager_DispatchEvent(SystemEvent evt);

/**
 * @brief 在系统主循环中持续轮询轮转前后台所有活跃的应用
 * @details 负责轮询前台 fg_app 对应的 onRun()，并遍历轮询后台 bg_apps 数组中所有有效应用的 onRun()。
 */
void AppManager_RunActiveApp(void);

/**
 * @brief 获取当前前台活跃应用的 ID
 * @return u8 当前活跃前台应用的 ID 编号。若无则返回 255 (0xFF)
 */
u8 AppManager_GetActiveAppID(void);

// 兼容性接口声明
void AppManager_StartApp(u8 app_id);

// ====== 系统中各独立 App 实例的外包声明 (各 App 内部进行实体定义) ======
extern WristbandApp clock_app;
extern WristbandApp menu_app;
extern WristbandApp pair_app;
extern WristbandApp alarm_app;
extern WristbandApp sos_app;
extern WristbandApp rf_monitor_app; // 后台射频监控应用

#endif // __APP_MANAGER_H__