/*
 * meow_ui_notify.h — SDK 应用通知（§9.1，meow_notify_*，M2.53 最小可用版）。
 *
 * 原 meow_ui.h 拆分的一部分（notify 模块）。app 只需声明类型 + meow_notify_send() 即可发通知，
 * SDK 管配额/活动表/降级。本阶段 SDK 内部维护活动通知表 + 用 meow_log() 打日志作为落点；
 * 真实投递到通知中心 UI / D-Bus 是后续任务（本结构已对齐 freedesktop 字段为此预留）。
 */
#ifndef MEOW_UI_NOTIFY_H
#define MEOW_UI_NOTIFY_H

#include "meow_ui_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ============================================================ */
/* §9.1 应用通知（meow_notify_*，M2.53 最小可用版） */
/* ============================================================ */
/* app 只需声明类型 + meow_notify_send() 即可发通知，SDK 管配额/活动表/降级：
 *   - 类型注册：app 声明支持的类型（最多 MEOW_NOTIFY_MAX_TYPES 4 种）；
 *     meow_notify_send 也会自动注册未声明类型（受同样 4 种上限约束）；
 *   - 配额（NOTIFICATION_SYSTEM.md §7，2026-08-29 用户拍板）：每 App 最多 4 种类型；
 *     每类型活动（未过期）通知上限 4，满则丢最旧（替换）；媒体类型单例（每 app 仅
 *     保留最近 1 条，重发替换——可多媒体 App）；
 *   - 超时语义 [实现定案，沿用 NOTIFICATION_SYSTEM.md §2]：timeout_ms>0 = 过期毫秒数；
 *     0 = 不自动过期（直到 meow_notify_cancel）；-1 = 常驻（ONGOING），同样不自动过期；
 *   - 落点：本阶段 SDK 内部维护活动通知表 + 用 meow_log() 打日志作为落点；真实投递到
 *     通知中心 UI / D-Bus（org.freedesktop.Notifications）是后续任务——本结构已对齐
 *     freedesktop 字段（summary/body/…）为此预留，但不写死后端；
 *   - 线程安全；不依赖 /dev/fb0、不依赖板子，可宿主编译。 */
#define MEOW_NOTIFY_MAX_TYPES      4   /* 每 App 最多 4 种通知类型 */
#define MEOW_NOTIFY_MAX_PER_TYPE   4   /* 每类型活动（未过期）通知上限 */
#define MEOW_NOTIFY_MAX_MEDIA      1   /* 媒体通知每 App 仅 1 条（单例） */
#define MEOW_NOTIFY_TIMEOUT_ONGOING (-1)  /* 常驻（ONGOING），不自动过期 */
#define MEOW_NOTIFY_TIMEOUT_NEVER    0    /* 不自动过期，直到取消 */

/* 通知分类（freedesktop.org Desktop Notifications 的 category 最小子集 [实现定案]） */
typedef enum {
    MEOW_NOTIFY_CAT_GENERAL  = 0,   /* 通用（默认） */
    MEOW_NOTIFY_CAT_MESSAGE  = 1,   /* 即时消息/聊天 */
    MEOW_NOTIFY_CAT_EMAIL    = 2,   /* 邮件 */
    MEOW_NOTIFY_CAT_EVENT    = 3,   /* 事件/日历提醒 */
    MEOW_NOTIFY_CAT_PROGRESS = 4,   /* 进度/下载 */
    MEOW_NOTIFY_CAT_MEDIA    = 5,   /* 媒体播放（MPRIS；每 app 单例） */
    MEOW_NOTIFY_CAT_COUNT    = 6,   /* 边界哨兵（非合法类型） */
} meow_notify_category;

/* 紧急度（UI 视觉分级 + 提示音/震动强弱） */
typedef enum {
    MEOW_NOTIFY_URG_LOW      = 0,   /* 低：仅进通知中心，不打扰 */
    MEOW_NOTIFY_URG_NORMAL   = 1,   /* 普通 */
    MEOW_NOTIFY_URG_HIGH     = 2,   /* 高：顶部横幅 + 提示音 */
    MEOW_NOTIFY_URG_CRITICAL = 3,   /* 紧急：需立刻注意 */
    MEOW_NOTIFY_URG_COUNT    = 4,   /* 边界哨兵（非合法值） */
} meow_notify_urgency;

/* 发送负载（对齐 freedesktop Notify() 字段；SDK 内部复制副本，不持 app 外部指针，
 * app 只需保证 icon/title/body/target_activity 指针在调用返回前有效）。 */
typedef struct meow_notify {
    meow_notify_category cat;           /* 类型（未声明则按 4 种上限自动注册） */
    meow_notify_urgency  urgency;       /* 紧急度（缺省 MEOW_NOTIFY_URG_NORMAL；越界钳位） */
    const char *title;                  /* summary：标题，单行（必填，NULL 则发送失败） */
    const char *body;                   /* body：正文，可多行（可 NULL） */
    const char *icon;                   /* app_icon：图标 icon name 或 path；NULL/空 = 用该 app 默认图标（launcher 按 app_id 回退） */
    int         timeout_ms;             /* 见上超时语义；推荐 MEOW_NOTIFY_TIMEOUT_* */
    const char *target_activity;        /* 通知中心点击跳转的 Activity 名（可 NULL；M3 导航预留） */
    int         progress;               /* 进度 0-100；-1=不显示进度条（缺省 -1） */
} meow_notify;

/* 类型注册：app 声明支持的类型。0=成功；-1=已声明/已达 4 种上限/非法。 */
int  meow_notify_register_type(meow_notify_category cat);

/* 发送一条通知。返回通知 id（用于 meow_notify_cancel）；失败返回 0。
 * 同类型满 4 条时丢弃最旧（替换）；媒体类型单例（重发替换同 app 上一条媒体通知）。 */
uint32_t meow_notify_send(const meow_notify *n);

/* 取消一条通知。1=成功；0=未找到（id 无效/已过期/已取消）。 */
int  meow_notify_cancel(uint32_t id);

/* 实时更新一条活动通知的进度（0-100，-1=清除进度条）。local_id=meow_notify_send 的返回值。
 * 语义（用户定案）：仅改 SDK 内部活动槽 + 经 IPC 通知 launcher 改**内存活跃槽**；不落盘——
 * TF 快照只在「创建时 / 结束(100% 或 dismiss)」触发。返回 1=找到并更新；0=未找到/非法。 */
int  meow_notify_update_progress(uint32_t local_id, int progress);

/* 查询当前活动（未过期、未取消）通知数/是否还有。 */
int  meow_notify_active_count(void);
int  meow_notify_count_in_type(meow_notify_category cat);
int  meow_notify_has_active(void);             /* 1=尚有活动通知，0=无 */

/* 紧急度/分类 → 字符串（"low"/"normal"/"high"/"critical"、"general"/"message"/…）。 */
const char *meow_notify_urgency_str(meow_notify_urgency u);
const char *meow_notify_category_str(meow_notify_category cat);

#ifdef __cplusplus
}
#endif
#endif /* MEOW_UI_NOTIFY_H */