StealthIM C SDK (stim)

StealthIM 的 C 语言 SDK,对标官方 Python SDK。用 C11 编写,构建在异步网络库 asyncweb(及其底层协程库 libcoro)之上。

每个端点都有两种风格:

• 同步(stim_sync_* / 句柄的非 _async 方法):阻塞,内部自驱事件循环, 直接把结果填进你给的 out 结构。
• 异步(stim_async_* / 句柄的 _async 方法):返回 task_t*,在协程里 gen_yield_from_task 它,完成后从 future 取结果。

特性

• 用户:注册 / 登录 / 查自己或他人信息 / 改密码·邮箱·昵称·手机号 / 注销
• 群组:列群 / 群信息 / 建群 / 加群 / 邀请 / 设角色 / 踢人 / 改名·改密
• 消息:发消息 / 撤回 / SSE 流式收消息
• 文件:查文件信息(上传 / 下载留二期)
• 三层句柄对象模型:Server → User → Group,对标 Python 的 Server/User/Group
• 同步 + 异步双 API,共享同一套 JSON 编解码与请求构造

依赖

• CMake ≥ 3.16、C11 编译器
• asyncweb:优先 find_package(系统已装),否则自动 FetchContent 源码。 asyncweb 又会透传拉入 libcoro 与 OpenSSL。
• JSON 用 vendored 的 cJSON(已内置于 third_party/,无需外部安装)。

构建

# 作为库嵌入你的项目 (find_package 或 add_subdirectory 均可):
cmake -B build -DCMAKE_PREFIX_PATH=/prefix/with/asyncweb
cmake --build build -j

变量	取值	说明
STIM_STANDALONE	ON / OFF	是否构建测试(默认 OFF)
ENABLE_ASAN	ON / OFF	测试开 AddressSanitizer(默认 OFF)

日志级别在编译期通过 STIM_LOG_LEVEL 控制(见 include/stim/config.h: STIM_LOG_DEBUG/INFO/WARN/ERROR/OFF)。

句柄 API 示例(同步)

#include <stim/stim.h>

stim_server_t *srv = stim_server_create("http://127.0.0.1:8080");

stim_result_t login_res;
stim_user_t *user = stim_server_login(srv, "alice", "pw", &login_res);
stim_result_free(&login_res);
if (!user) { /* 登录失败 */ }

stim_user_info_t info;
if (stim_user_get_self_info(user, &info) == STIM_OK &&
    info.result.code == STIM_CODE_OK) {
    printf("nickname = %s\n", info.nickname);
}
stim_user_info_free(&info);

stim_group_t *g = stim_group_create(user, /*group_id=*/42);
stim_result_t sr;
stim_group_send_text(g, "hello", &sr);
stim_result_free(&sr);

stim_group_destroy(g);
stim_user_destroy(user);
stim_server_destroy(srv);

异步 API 示例

异步端点返回 task_t*;在协程里 await,完成后 future_result 是一个 堆分配的结果结构(用完 stim_xxx_free + free):

task_t *t = stim_async_login(url, "alice", "pw");
gen_yield_from_task(t);
stim_login_result_t *lr = future_result(t->future);
if (lr && lr->result.code == STIM_CODE_OK) {
    printf("session = %s\n", lr->session);
}
if (lr) { stim_login_result_free(lr); free(lr); }

完整可运行示例见 examples/(sync_login.c / async_login.c)。

SSE 收消息

收消息是流式的,用回调消费(异步生成器无法同步迭代):

void on_msg(const stim_message_t *m, void *ud) {
    printf("[%d] %s: %s\n", m->groupid, m->username, m->msg);
}

// 在协程里 (或独立 task_run):
task_t *t = stim_group_receive_text(g, /*from_id=*/0, /*sync=*/1,
                                    /*limit=*/128, on_msg, NULL);
task_run(t);   // 不要 gen_yield_from —— 底层 gen_emit 只在顶层驱动有效
// 用 future_add_done_callback(t->future, ...) 等流结束

内存所有权

C 无 GC,凡返回含堆字段(char* / 数组)的结构,用完须调配套的 stim_xxx_free()(只释放堆字段,不释放结构本身)。异步路径额外:结果结构本身 也是 malloc 的,stim_xxx_free 之后还要 free 指针。

状态码约定

• stim_status_t:STIM_OK = 1 / STIM_ERR = 0(与 C 惯例相反,对齐 asyncweb 的 ANET_OK,避免封装层双重翻转语义)。表示"调用本身是否成功完成"。
• 业务码是独立的 int result.code:STIM_CODE_OK = 800 为成功;900-999 为服务器错误,传输层内部自动重试 3 次。

许可

MIT,见 LICENSE。