主题
离线读取与取消请求
本页只说明应用开发时怎么用。离线读取适合通知扩展、桌面搜索和只读小组件； 取消请求适合页面退出、用户停止操作或请求超时。
什么时候使用离线读取
以下场景可以使用 OfflineReader：
- App 没有连接 IM，但需要读取已经同步到本机的会话或消息；
- 系统通知扩展需要根据本地消息补充通知内容；
- 桌面搜索需要查询本地历史记录；
- 只读小组件需要展示最近会话。
离线读取不会登录账号、不会连接服务器，也不会修改数据。它只能读取当前 SDK 已经正常创建并升级过的账号数据库。
接入步骤
- 从 Keychain、Keystore、DPAPI 或 HUKS 取得与在线 SDK 相同的数据库密钥；
- 在后台线程创建
OfflineReader，传入数据库路径、账号 ID 和密钥； - 调用会话、消息或联系人查询；
- 把结果转换成页面需要的模型；
- 页面或扩展结束时关闭 Reader。
不要把数据库密钥写进源码、配置文件、日志或普通业务数据库。不要在 UI 主线程 执行离线查询，也不要让两个线程同时使用同一个 Reader。
可以查询什么
- 最近会话和本地消息；
- 按会话、发送者或消息类型搜索消息；
- 好友申请、好友和黑名单；
- 群组、群成员和入群申请。
分页返回的 cursor 是 SDK 生成的游标。应用只需保存并原样传给下一页，不要解析、 拼接，也不要把一种查询的游标用于另一种查询。
常见处理方式
| 情况 | 应用怎么处理 |
|---|---|
| 数据库尚未创建 | 先让同版本在线 SDK 完成一次正常登录和同步 |
| SDK 版本不匹配 | 使用创建该数据库的 SDK 或先由新版在线 SDK 完成升级 |
| 账号不匹配 | 检查传入的账号 ID 和数据库目录 |
| 密钥错误 | 从平台安全存储重新取得密钥，不要尝试绕过加密 |
| 页面已关闭 | 丢弃查询结果并关闭 Reader |
更具体的方法名、参数和返回值请在 SDK API Reference 选择当前平台查看。
取消一个进行中的请求
平台公开 API 都支持逐请求取消：
- iOS/macOS：保存返回的请求对象或取消句柄，在页面退出时调用
cancel()； - Android：取消返回的
CompletableFuture或请求句柄； - Windows：传入
CancellationToken； - HarmonyOS、Web、Electron：使用返回的取消方法或
AbortSignal； - Flutter：取消请求句柄或页面持有的订阅。
取消表示“应用不再等待这次结果”。如果服务端已经完成写入，取消不会撤销已经成功的 消息、好友或群组操作。带 mutationID / operationID 的写操作重试时，必须继续 使用第一次的 ID，这样 SDK 才能返回同一结果，而不会重复执行。
text
页面发起请求
-> 保存请求句柄
-> 页面正常显示结果
如果页面提前关闭
-> 调用 cancel
-> 忽略取消后的迟到 UI 更新不要这样做
- 不要通过关闭数据库或销毁整个 Client 来取消单个页面请求；
- 不要在取消后立即换一个新的 mutation ID 重试同一写操作；
- 不要把 Reader 当成第二个在线 Client；
- 不要直接读取或修改 SDK 的 SQLite 表。