Native (C ABI) IMLib 快速开始

本页用 5 个步骤完成 Native (C ABI) 端 IMLib 接入：控制台取 AppKey / Token、导入 SDK、初始化、建立连接、收发消息与会话。示例方法名与参数来自冻结的 sdk-bindings.json。

  1. 控制台获取 AppKey 与 Token

    在控制台创建应用并获取 AppKey；用户 Token 由业务服务先注册用户（user.register）、再调用 user.token.issue 签发后下发到客户端（两步都需要服务端签名）。

    客户端只持有 Token，不得内置 AppSecret；Token 泄露时可调用服务端接口吊销。

  2. 导入 SDK

    按「导入 SDK」安装依赖；正式 ABI 为 im_client_*；头文件同时保留 deprecated 的 imsdk_* 旧 MVP ABI，新代码不应使用。C ABI 未暴露全部 62 个语义 op，见「功能列表」中的「C ABI 未暴露」标记。

  3. 初始化客户端

    使用 AppKey（与服务端地址）初始化；初始化幂等：同 appkey 重复调用返回同一实例，不建立连接。

  4. 建立连接并订阅事件

    使用 Token 调用 connect，成功后触发 CONNECTED；离线消息在 hello 后自动补发。

  5. 收发消息与会话

    注册对端用户后发送第一条文本消息、监听 MESSAGES 事件并拉取会话列表。

1. 控制台获取 AppKey 与 Token​

凭据获取方式使用位置
AppKey控制台 → 应用 → 基本信息初始化客户端（options.appkey）
用户 Token业务服务注册用户（user.register）后调用 user.token.issue 签发（需签名）connect(token)
AppSecret控制台 → 应用 → 密钥（仅服务端保存）服务端签发 Token / 调用 Open API
禁止硬编码

AppSecret 只能保存在业务服务端；客户端产物中不得出现 AppSecret。示例中的 TOKEN 表示服务端签发的用户 Token。

本地服务端地址

本页及后续示例统一使用 https://im.example.com（服务端缺省端口）。

示例使用占位地址 https://im.example.com；本地联调请替换为你实际启动的服务端地址与端口（客户端与服务端必须指向同一地址）。

2. 导入 SDK​

C / Rust
// 1) 链接预编译库（include/im_sdk.h + libim_sdk）
cc app.c -Iinclude -Llib -lim_sdk -o app

// 2) 或在 Rust 工程中直接依赖 crate
cargo add im-sdk im-kit

3. 初始化​

C（C ABI）
im_client_t* client = im_client_new("YOUR_APP_KEY", "https://im.example.com");
if (client == NULL) {
    fprintf(stderr, "im_client_new failed\n");
}

4. 建立连接​

C（C ABI）
char user_id[64];
int rc = im_client_connect(client, TOKEN, user_id, sizeof(user_id));
if (rc != 0) { fprintf(stderr, "connect failed: %d\n", rc); }

5. 收发消息与会话​

收发验证需要两个已注册用户：先注册对端（例如 user2）并签发它的 Token，再用对端账号建连接收。示例中的 user2 是“已存在的另一个用户”，不是任意字符串。

C（C ABI）
char message_id[128];
int rc = im_client_send_text(client, 1, "user2", "你好，NI PaaS", NULL, message_id, sizeof(message_id));
if (rc != 0) { fprintf(stderr, "send failed: %d\n", rc); }

char* conversations_json = NULL;
rc = im_client_conversation_list(client, &conversations_json);
if (rc == 0) { /* 解析 conversations_json */ }
im_string_free(conversations_json);
发送给未注册用户会断开连接

单聊发送给不存在的用户时，服务端返回 1004（用户不存在），当前连接可能因此被断开，随后发送调用返回 3001（连接已中断）。

这不是网络故障：注册对端用户（user.register）并重连后即可正常发送。排查时先确认两个 userId 都已注册且属于同一个 appkey。

响应不是 JSON / 404？

如果脚本报 Unexpected token '<' 或看到 HTML，通常是服务端地址或端口不对（示例使用占位地址；本地联调要替换为实际端口）。

先用浏览器或 curl 访问服务端根路径确认可达，再检查 serverUrl 是否与启动参数一致。

双端验证：两个进程 / 两个浏览器 profile

同一进程内对同一个 appkey 初始化只会得到一个客户端实例（初始化幂等）：把两个账号塞进同一个实例会互相覆盖登录态，典型报错是 “cannot send to self”。

实测：同一进程内建两个客户端实例（不同 appkey 或先 destroy 再 create）可以互发；同 origin 的两个浏览器标签共享 deviceId，第二个客户端可能收不到投递。

因此本机验证“收发”请开两个进程，或开两个浏览器 profile（各自独立 localStorage/deviceId），每个进程/Profile 只登录一个用户。

下一步​