晞晗IM（XHIM）SDK API Reference

适用版本：0.1 Commercial Beta 面向对象：iOS、macOS、Android、Windows、HarmonyOS 客户端开发者和二次开发团队

这里是客户端 SDK 的完整公开能力目录。第一次接入仍然从各平台 QuickStart 开始；当你需要查方法、参数、返回模型、事件、错误或扩展点时，再进入本目录。

1. 文档导航

你要找什么	文档
创建、连接、登录、续凭、退出、关闭	生命周期与连接
消息、会话、已读、草稿、搜索	消息与会话 API
用户、好友、黑名单、群组、Push	用户、关系链与群组 API
图片、视频、音频、文件、缓存、离线读取	媒体与离线 API
所有事件、回调线程和刷新规则	事件与回调
iOS 的 onSuccess / onFailure 写法	iOS 回调式 API
macOS 的 onSuccess / onFailure 写法	macOS 回调式 API
全部 100 个公开 API 的 Swift Concurrency 写法	100 个 API 并发示例
每个回调的载荷、触发条件、线程与重查动作	回调详细说明
公开模型、枚举和稳定错误字段	模型、枚举与错误
自定义消息、Renderer、UI Kit 二次开发	扩展点
同一能力在各原生端叫什么	原生平台 API 名称映射
C/C++ 或自研语言 Bridge	xhim_v1 C ABI

平台安装与第一条消息：

2. 统一调用模型

各原生端语义一致，只有语言习惯不同：

平台	异步调用	事件	普通请求取消
iOS	首选 `onSuccess/onFailure`；支持 `async throws`	`addEventListener`；支持 `AsyncStream`	`XHIMRequest.cancel()` 或取消 Swift `Task`
macOS	首选 `onSuccess/onFailure`；支持 `async throws`	`addEventListener`；支持 `AsyncStream`	`XHIMRequest.cancel()` 或取消 Swift `Task`
Android	Kotlin `suspend`	`SharedFlow<XHIMEvent>`	取消调用它的 Coroutine
Windows	C# `Task<T>`	`IAsyncEnumerable<XHIMEvent>`	传入并取消 `CancellationToken`
HarmonyOS	ArkTS `Promise<T>`	`onEvent` 返回退订函数	用 `onRequest` 取得 `requestId` 后调用 `cancelRequest`

除非方法特别注明：

可读写 API 需要 Client 已进入 ready；
字符串 ID 均不能为空，游标是 SDK 返回的不透明字节，不得自行拼装；
mutationID 和 clientMessageID 是调用方生成的幂等键，重试时必须复用；
时间统一为 Unix Epoch 毫秒；
页面层不持有 Token，不直接打开 SDK 数据库；
Completion 表示这次 API 调用已完成；界面长期状态仍以本地投影查询和事件重查为准。

iOS 与 macOS 新项目可分别使用各自文档中的回调式 Facade。它会把成功、失败和事件按顺序投递到 MainActor，代码可以直接写在 ViewModel；已经采用 Swift Concurrency 的项目继续使用同名 async throws 重载。两种写法共享同一个 Client 和本地状态。

3. 推荐的页面数据流

text

先订阅事件
  → 首次查询 conversations/messages/social page
  → 收到 projection event
  → 按事件 scope 重新查询 SDK 本地投影
  → 用查询结果替换页面状态

事件是轻量失效通知，不是另一份业务数据库，也不应把事件 payload 当成完整消息。如果发现未知事件版本、事件丢失或投影 revision 跳号，直接重新查询相关列表。

4. 方法状态与兼容承诺

本目录只记录当前二进制 Facade 确实存在的公开符号。每个方法都有稳定 api-id，例如 message.send_text。语言命名可以随平台习惯不同，统一语义、模型字段和错误判断键保持一致。

docs/sdk-api/public-api-surface.tsv 是文档覆盖门禁的机器清单：

清单中的每个原生平台符号必须存在于对应 Facade 源码；
每个 api-id 必须在 Reference 中出现；
每个 api-id 必须有 example:<api-id> 示例覆盖标记；
C ABI 导出基线中的每个符号必须进入 C ABI 文档。

新接口只有在 Core、C ABI、各原生 OS Facade、Reference 和兼容性测试一起完成后，才能被声明为跨平台公开能力。

5. 不属于客户端 API 的内容

数据库、对象存储、审核、管理后台、管理员密钥、服务端部署命令和 Endpoint 签名私钥都属于服务端。客户端开发者只配置公开 Server URL、App ID、当前 User ID，并使用业务账号层提供的凭证回调。

服务端接口与运维说明见 XHIM Server，不要把其中的管理员 API 或密钥复制进 App。

晞晗IM（XHIM）SDK API Reference ​

1. 文档导航 ​

2. 统一调用模型 ​

3. 推荐的页面数据流 ​