im_client_t 句柄（Native (C ABI) IMLib）
类继承图
Object→im_client_t
继承关系：Object → im_client_t。初始化方法为 SDK 唯一入口；实例由初始化接口返回，不直接 new。
类说明
im_client_t 是 Native (C ABI) IMLib 的入口句柄：持有连接与事件总线，串联连接、消息、会话、用户、好友、群组、聊天室与文件上传共 62 个语义操作。方法名与 IDL 语义 op 同名，仅调用风格与常量名随平台变化。
| 项 | 值 |
|---|---|
| 程序包 | libim_sdk |
| 完整声明 | im-sdk (crate) + libim_sdk |
| 语言 / 运行时 | Rust core + C ABI |
| 初始化入口 | im_client_new(const char* appkey, const char* server_url) -> im_client_t* |
| 异步模型 | opaque handle + 返回 int 错误码 + out 参数 |
| 事件 API | im_client_set_event_callback(im_client_t*, im_event_cb cb, void* user_data) |
| 命名约定 | im_<domain>_<action> |
| 方法总数 | 103 个语义操作，本平台导出 17 个 |
| 平台状态 | 已交付 |
概要
方法按能力域分组。点击方法名跳转到详细说明；"签名"列逐字来自平台绑定的 methodMap。
连接与监听（7）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
init | im_client_new(const char* appkey, const char* server_url) -> im_client_t* | 初始化 SDK（构造客户端实例） |
connect | im_client_connect(im_client_t*, const char* token, char* out_user_id, size_t out_len) | 使用用户 token 建立长连接：握手→hello→离线补发→sync_done |
disconnect | im_client_disconnect(im_client_t*) | 主动断开 |
getConnectionStatus | im_client_connection_status(im_client_t*) -> int | 返回 ConnectionStatus 枚举值 |
getCurrentUserId | im_client_current_user_id(im_client_t*, char* out, size_t out_len) | 当前登录 userId |
addEventListener | im_client_set_event_callback(im_client_t*, im_event_cb cb, void* user_data) | 注册事件监听 |
removeEventListener | 未导出 C ABI | 移除事件监听 |
消息（26）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
sendMessage | im_client_send_content(im_client_t*, int conversation_type, const char* target_id, const char* content_json, c… | 发送任意类型消息 |
sendTextMessage | im_client_send_text(im_client_t*, int conversation_type, const char* target_id, const char* text, const char* … | 发送文本消息 |
sendImageMessage | 未导出 C ABI | 发送图片消息 |
sendFileMessage | 未导出 C ABI | 发送文件消息 |
sendVoiceMessage | 未导出 C ABI | 发送语音消息 |
sendLocationMessage | 未导出 C ABI | 发送位置消息 |
sendTypingStatus | 未导出 C ABI | 发送正在输入状态 |
recallMessage | im_client_recall(im_client_t*, const char* message_id) | 撤回消息（仅发送者、撤回时限内） |
sendReadReceipt | im_client_send_read_receipt(im_client_t*, int conversation_type, const char* target_id, const char* const* mes… | 上报已读回执 |
getMessageReadCount | 未导出 C ABI | 查询消息已读人数 |
getMessageReadUsers | 未导出 C ABI | 查询已读用户明细（分页） |
getMessageReadDetail | 未导出 C ABI | 查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页） |
searchMessages | 未导出 C ABI | 在当前用户全部会话中搜索文本消息（倒序） |
updateMessageExpansion | 未导出 C ABI | 更新已发送消息的扩展 KV（合并语义） |
removeMessageExpansion | 未导出 C ABI | 删除消息扩展 KV（按 key） |
addMessageReaction | 未导出 C ABI | 为指定消息添加回应（reactionId 由业务定义，1-16 字符） |
removeMessageReaction | 未导出 C ABI | 移除自己对指定消息的回应 |
batchGetMessageReactionSummaries | 未导出 C ABI | 批量查询消息回应摘要（1-100 个 messageId） |
getMessageReactions | 未导出 C ABI | 分页查询指定消息的回应列表（count 1-50，默认 20） |
getMessageReactionUsers | 未导出 C ABI | 分页查询某个回应的参与用户（count 1-50，默认 20） |
startStreamMessage | 未导出 C ABI | 开始一条流式消息（IDL rev17） |
appendStreamMessage | 未导出 C ABI | 追加一个流式增量（IDL rev17） |
completeStreamMessage | 未导出 C ABI | 结束流式消息（IDL rev17） |
getStreamMessage | 未导出 C ABI | 查询流式消息快照（IDL rev17） |
getMessageExpansion | 未导出 C ABI | 读取已发送消息的扩展 KV（IDL rev19） |
combineMessages | 未导出 C ABI | 本地构造合并转发内容（IDL rev19，transport=local，不做网络 IO）：把 Message[] 转换为 `{type:'co… |
功能指南：发送消息、接收消息、消息管理、已读回执、输入状态、消息进阶
会话（22）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
getConversationList | im_client_conversation_list(im_client_t*, char** out_json) + im_string_free | 会话列表：置顶优先、按 updatedAt 倒序 |
getConversation | 未导出 C ABI | 单会话详情 |
getHistoryMessages | im_client_history(im_client_t*, int conversation_type, const char* target_id, int limit, unsigned long long be… | 历史消息分页（beforeSeq 向前翻页） |
clearUnreadCount | 未导出 C ABI | 清空会话未读（等价 read 帧 + 本地清零） |
setConversationToTop | 未导出 C ABI | 会话置顶/取消 |
saveTextMessageDraft | 未导出 C ABI | 保存草稿（空串=清除） |
getTextMessageDraft | 未导出 C ABI | 读取草稿 |
clearTextMessageDraft | 未导出 C ABI | 清除草稿 |
setConversationNotificationLevel | 未导出 C ABI | 会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰 |
createConversationTag | 未导出 C ABI | 创建会话标签（tagName ≤16） |
updateConversationTag | 未导出 C ABI | 重命名会话标签 |
deleteConversationTag | 未导出 C ABI | 删除会话标签（同时清除标签内会话引用） |
getConversationTags | 未导出 C ABI | 获取全部会话标签（含会话数量） |
addConversationsToTag | 未导出 C ABI | 把会话加入标签（≤100/次，幂等） |
removeConversationsFromTag | 未导出 C ABI | 把会话移出标签（≤100/次，幂等） |
getConversationsFromTagByPage | 未导出 C ABI | 分页获取标签内会话（含置顶/未读数/最后消息时间） |
getTagsFromConversation | 未导出 C ABI | 查询某个会话所属的标签列表 |
getUnreadCountByTag | 未导出 C ABI | 标签内未读汇总（消息总数 + 有未读的会话数） |
setConversationToTopInTag | 未导出 C ABI | 标签内置顶/取消置顶会话（同步会话会话级置顶状态） |
deleteConversation | 未导出 C ABI | 删除会话记录（列表项/未读/草稿/置顶），历史消息保留 |
getConversationTypeNotification | 未导出 C ABI | 查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰） |
setConversationTypeNotification | 未导出 C ABI | 设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰） |
功能指南：历史消息、会话列表、未读数、草稿、置顶与免打扰、会话标签与分组、会话删除与类型免打扰
用户（10）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
getUserProfile | 未导出 C ABI | 查询用户资料 |
updateMyUserProfile | 未导出 C ABI | 修改本人资料（name/avatarUrl） |
getOnlineStatus | 未导出 C ABI | 查询单个用户在线状态 |
getOnlineStatusBatch | 未导出 C ABI | 批量在线状态（<=100） |
subscribePresence | 未导出 C ABI | 订阅用户在线状态（IDL rev20） |
unsubscribePresence | 未导出 C ABI | 取消订阅用户在线状态（IDL rev20） |
getPresenceSubscriptions | 未导出 C ABI | 查询当前用户的在线状态订阅列表（IDL rev20） |
registerPushToken | 未导出 C ABI | 注册设备推送 token（IDL rev21 C23 收口） |
unregisterPushToken | 未导出 C ABI | 注销本人设备推送 token（IDL rev21 C23） |
getPushTokens | 未导出 C ABI | 查询本人设备推送 token（IDL rev21 C23） |
功能指南：用户资料、在线状态、在线状态订阅与推送令牌
好友与黑名单（11）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
searchUsers | 未导出 C ABI | 搜索用户（userId/name，大小写不敏感，排除自己） |
sendFriendRequest | 未导出 C ABI | 发起好友申请 |
getFriendRequests | 未导出 C ABI | 好友申请列表（incoming/outgoing，pending/all） |
acceptFriendRequest | 未导出 C ABI | 同意申请，双向建立好友关系 |
rejectFriendRequest | 未导出 C ABI | 拒绝申请 |
getFriends | 未导出 C ABI | 好友列表（含备注/在线/拉黑标记） |
deleteFriend | 未导出 C ABI | 双向删除好友 |
setFriendRemark | 未导出 C ABI | 设置好友备注（<=64 字，空串清除） |
getBlacklist | 未导出 C ABI | 黑名单列表 |
addToBlacklist | 未导出 C ABI | 加入黑名单（幂等） |
removeFromBlacklist | 未导出 C ABI | 移出黑名单 |
群组（20）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
createGroup | 未导出 C ABI | 创建群（groupType 缺省 normal） |
getGroupsInfo | 未导出 C ABI | 批量查询群信息（<=20） |
getGroupMembers | im_client_group_members(im_client_t*, const char* group_id, char** out_json) | 群成员列表（含角色/禁言） |
addGroupMembers | 未导出 C ABI | 拉人入群（群主/管理员） |
removeGroupMembers | 未导出 C ABI | 移除成员（群主/管理员） |
quitGroup | 未导出 C ABI | 退出群 |
updateGroupName | 未导出 C ABI | 修改群名（群主/管理员） |
updateGroupNotice | 未导出 C ABI | 设置群公告（群主/管理员，<=500 字，空串清除） |
transferGroupOwner | 未导出 C ABI | 转让群主（新群主须为成员） |
addGroupAdmin | 未导出 C ABI | 设置管理员（群主，幂等） |
removeGroupAdmin | 未导出 C ABI | 取消管理员（群主） |
muteGroupMember | 未导出 C ABI | 禁言/解禁（群主/管理员） |
createSupergroupChannel | 未导出 C ABI | 创建超级群频道（IDL rev21 C17） |
listSupergroupChannels | 未导出 C ABI | 超级群频道列表（IDL rev21 C17） |
joinSupergroupChannel | 未导出 C ABI | 加入超级群频道（IDL rev21 C17） |
leaveSupergroupChannel | 未导出 C ABI | 离开超级群频道（IDL rev21 C17） |
bindUserGroupToChannel | 未导出 C ABI | 把用户组绑定到频道（IDL rev21 C17） |
createUserGroup | 未导出 C ABI | 创建超级群用户组（IDL rev21 C17） |
listUserGroups | 未导出 C ABI | 超级群用户组列表（IDL rev21 C17） |
getUserGroupsByUser | 未导出 C ABI | 查询某用户所在的所有用户组（IDL rev21 C17） |
聊天室（5）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
createChatroom | 未导出 C ABI | 创建聊天室（客户端能力） |
joinChatroom | im_client_chatroom_join(im_client_t*, const char* chatroom_id) | 加入聊天室：发送 chatroom_join，收到 chatroom_joined |
leaveChatroom | im_client_chatroom_leave(im_client_t*, const char* chatroom_id) | 离开聊天室 |
getChatroomInfo | im_client_chatroom_info(im_client_t*, const char* chatroom_id, char** out_json) | 聊天室信息（含在线数） |
getChatroomMembers | 未导出 C ABI | 聊天室在线成员列表 |
系统通知（1）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
getSystemMessages | 未导出 C ABI | 系统通知历史（会话 conversationType=SYSTEM，targetId='system'） |
功能指南：系统通知
文件上传（1）
| 方法 | 签名（本平台绑定） | 说明 |
|---|---|---|
uploadFile | im_client_upload_file(im_client_t*, const void* data, size_t len, const char* name, const char* mime, char** o… | 上传文件（<=20MB），返回可用于图片/文件/语音消息的 url |
功能指南：文件上传
未导出的语义操作
C ABI 当前只导出与连接、消息、会话、聊天室、文件上传相关的 17 个函数；其余 86 个语义操作由 Rust core 提供，尚未暴露为 C 函数，详见 未导出的语义操作。
详细成员说明
连接与监听（6）
im_client_new(const char* appkey, const char* server_url) -> im_client_t*初始化 SDK（构造客户端实例）。幂等：同 appkey 重复初始化返回同一实例。 可能错误码：1001 参数错误。 该操作幂等：重复调用不会产生额外副作用。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
options | {appkey:string, serverUrl?:string, timeoutMs?:uint32, transport?:any} | 可选参数对象 |
返回
IMClient 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
im_client_t* client = im_client_new(NULL, NULL);
if (client == NULL) {
fprintf(stderr, "init failed\n");
return -1;
}im_client_connect(im_client_t*, const char* token, char* out_user_id, size_t out_len)使用用户 token 建立长连接：握手→hello→离线补发→sync_done；成功后触发 CONNECTED。失败按协议重连策略重试。 可能错误码：1002 Token 无效或已过期、1016 账号已被封禁、1017 应用已停用、2001 服务端内部错误、2002 依赖服务不可用、3002 请求超时、3003 网络错误。 可能触发事件：CONNECTING、CONNECTED。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
token | string | 见类型定义 |
返回
{userId:string, sessionId?:string} 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_connect(client, NULL, NULL, 0);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_disconnect(im_client_t*)主动断开；停止重连、清理心跳与待决请求。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。
返回
void / null 成功时返回 0；失败时返回非 0 错误码。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_disconnect(client);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_connection_status(im_client_t*) -> int返回 ConnectionStatus 枚举值。 可能错误码：无特定错误码（通用错误见 ErrorCode）。
返回
ConnectionStatus 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_connection_status(client);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_current_user_id(im_client_t*, char* out, size_t out_len)当前登录 userId；未登录返回空串。 可能错误码：无特定错误码（通用错误见 ErrorCode）。
返回
string 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_current_user_id(client, NULL, 0);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_set_event_callback(im_client_t*, im_event_cb cb, void* user_data)注册事件监听；同一 handler 重复注册只生效一次。 可能错误码：无特定错误码（通用错误见 ErrorCode）。 该操作幂等：重复调用不会产生额外副作用。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
event | string | 事件名，取值见 EventType |
handler | function | 事件处理函数（注册与移除需传同一引用） |
返回
void / null 成功时返回 0；失败时返回非 0 错误码。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
/* on_event 需按 include/im_sdk.h 的 im_event_cb 原型实现 */
int rc = im_client_set_event_callback(client, on_event, NULL);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}消息（4）
im_client_send_content(im_client_t*, int conversation_type, const char* target_id, const char* content_json, const char* client_msg_id, char* out_json, size_t out_len)发送任意类型消息。优先走长连接；连接不可用（SUSPEND/DISCONNECTED）时按 SDK_NO_CONNECTION 失败并保留本地待发队列（可选实现）。rev23：options.channelId 用于超级群频道消息（conversationType=10），仅频道成员接收；消息模型带 channelId。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1005 群组不存在、1006 未加入群组、1007 消息体过大（上限 5KB）、1008 发送过于频繁、1009 你已被禁言、1010 内容包含敏感词、1011 已被对方拉黑或你已拉黑对方 等 17 个。 可能触发事件：MESSAGES、CONVERSATION。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | ConversationType | 会话类型，取值见 ConversationType |
targetId | string | 目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId |
content | Content | 消息内容体，字段见 MessageContent |
options | {clientMsgId?:string, channelId?:string} | 可选参数对象（可选） |
返回
Message 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_send_content(client, 1 /* ConversationType.PRIVATE */, NULL, NULL, NULL, NULL, 0);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_send_text(im_client_t*, int conversation_type, const char* target_id, const char* text, const char* client_msg_id, char* out_message_id, size_t out_len)发送文本消息；内部等价 sendMessage(content={type:'text',text,mentionedInfo?,quote?})。 可能错误码：1001 参数错误、1007 消息体过大（上限 5KB）、1009 你已被禁言、1010 内容包含敏感词、1011 已被对方拉黑或你已拉黑对方、3001 长连接未就绪、3002 请求超时。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | ConversationType | 会话类型，取值见 ConversationType |
targetId | string | 目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId |
text | string | 文本消息内容（非空，序列化后 ≤ 5KB） |
options | {clientMsgId?:string, mentionedInfo?:MentionedInfo, quote?:Quote, channelId?:string} | 可选参数对象（可选） |
返回
Message 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_send_text(client, 1 /* ConversationType.PRIVATE */, NULL, NULL, NULL, NULL, 0);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_recall(im_client_t*, const char* message_id)撤回消息（仅发送者、撤回时限内）。成功后本地与对端收到 MESSAGE_RECALLED。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、1022 超过撤回时限、1023 消息已撤回、3001 长连接未就绪。 可能触发事件：MESSAGE_RECALLED、CONVERSATION。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
messageId | string | 消息 ID（服务端生成的 messageId） |
返回
Message 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_recall(client, NULL);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_send_read_receipt(im_client_t*, int conversation_type, const char* target_id, const char* const* message_ids, size_t count)上报已读回执；服务端记录唯一读者并推送给消息发送者。 可能错误码：1001 参数错误、1003 无权限、1004 用户不存在、3001 长连接未就绪。 可能触发事件：READ_RECEIPT。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | ConversationType | 会话类型，取值见 ConversationType |
targetId | string | 目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId |
messageIds | string[] | 消息 ID 列表 |
返回
{messageIds:string[], readCounts?:map<string,uint32>, totalMembers?:uint32} 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_send_read_receipt(client, 1 /* ConversationType.PRIVATE */, NULL, NULL, 1);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}会话（2）
im_client_conversation_list(im_client_t*, char** out_json) + im_string_free会话列表：置顶优先、按 updatedAt 倒序；含未读/提及/草稿/免打扰。 可能错误码：无特定错误码（通用错误见 ErrorCode）。
返回
Conversation[] 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
char* out_json = NULL;
int rc = im_client_conversation_list(client, &out_json);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}
im_string_free(out_json);im_client_history(im_client_t*, int conversation_type, const char* target_id, int limit, unsigned long long before_seq, char** out_json)历史消息分页（beforeSeq 向前翻页）；limit 默认 20 上限 100。rev23：channelId 过滤超级群频道消息（仅返回该频道消息）。 可能错误码：1001 参数错误、1003 无权限。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | ConversationType | 会话类型，取值见 ConversationType |
targetId | string | 目标 ID：单聊为对方 userId，群组为 groupId，聊天室为 chatroomId |
options | {limit?:uint32, beforeSeq?:uint64, channelId?:string} | 可选参数对象（可选） |
返回
{messages:Message[], hasMore:bool} 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
char* out_json = NULL;
int rc = im_client_history(client, 1 /* ConversationType.PRIVATE */, NULL, 20, 0, &out_json);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}
im_string_free(out_json);群组（1）
im_client_group_members(im_client_t*, const char* group_id, char** out_json)群成员列表（含角色/禁言）。 可能错误码：1001 参数错误、1003 无权限、1005 群组不存在、1006 未加入群组。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
groupId | string | 群组 ID |
返回
GroupMember[] 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
char* out_json = NULL;
int rc = im_client_group_members(client, NULL, &out_json);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}
im_string_free(out_json);聊天室（3）
im_client_chatroom_join(im_client_t*, const char* chatroom_id)加入聊天室：发送 chatroom_join，收到 chatroom_joined；房内广播 member_changed。 可能错误码：1001 参数错误、1012 聊天室不存在、1013 聊天室已销毁、3001 长连接未就绪。 可能触发事件：CHATROOM_EVENT。 该操作幂等：重复调用不会产生额外副作用。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
chatroomId | string | 聊天室 ID |
返回
Chatroom 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_chatroom_join(client, NULL);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_chatroom_leave(im_client_t*, const char* chatroom_id)离开聊天室。 可能错误码：1001 参数错误、1012 聊天室不存在、3001 长连接未就绪。 可能触发事件：CHATROOM_EVENT。 该操作幂等：重复调用不会产生额外副作用。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
chatroomId | string | 聊天室 ID |
返回
void / null 成功时返回 0；失败时返回非 0 错误码。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
int rc = im_client_chatroom_leave(client, NULL);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}im_client_chatroom_info(im_client_t*, const char* chatroom_id, char** out_json)聊天室信息（含在线数）。 可能错误码：1001 参数错误、1012 聊天室不存在。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
chatroomId | string | 聊天室 ID |
返回
Chatroom 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
char* out_json = NULL;
int rc = im_client_chatroom_info(client, NULL, &out_json);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}
im_string_free(out_json);文件上传（1）
im_client_upload_file(im_client_t*, const void* data, size_t len, const char* name, const char* mime, char** out_json)上传文件（<=20MB），返回可用于图片/文件/语音消息的 url。 可能错误码：1001 参数错误、1003 无权限、1007 消息体过大（上限 5KB）。
参数
| 参数 | 类型 | 说明 |
|---|---|---|
data | bytes|blob | 文件二进制内容 |
name | string | 名称（群名称 / 文件名等） |
mime | string | 文件 MIME 类型（可选） |
返回
{url:string,name:string,size:uint64,mime:string,fullUrl?:string} 成功时返回 0，并通过 out 参数回填数据（JSON 由调用方释放）。
示例
C
// client 由 im_client_new() 创建（见 init 示例）
char* out_json = NULL;
int rc = im_client_upload_file(client, NULL, sizeof(data) - 1, NULL, NULL, &out_json);
if (rc != 0) {
fprintf(stderr, "im_sdk error: %d\n", rc);
}
im_string_free(out_json);未导出的语义操作
下列 86 个语义操作尚未导出为 C ABI 函数。可以改用 Rust core（im-sdk crate）直接调用，或通过服务端 Open API 完成同等管理动作；导出后签名将保持与 IDL 语义 op 同名。
| 语义操作 | 能力域 | 传输 | 返回类型 | 说明 |
|---|---|---|---|---|
removeEventListener | 连接与监听 | 本地（无 IO） | null | 移除事件监听 |
sendImageMessage | 消息 | 长连接（WebSocket） | Message | 发送图片消息 |
sendFileMessage | 消息 | 长连接（WebSocket） | Message | 发送文件消息 |
sendVoiceMessage | 消息 | 长连接（WebSocket） | Message | 发送语音消息 |
sendLocationMessage | 消息 | 长连接（WebSocket） | Message | 发送位置消息 |
sendTypingStatus | 消息 | 长连接（WebSocket） | null | 发送正在输入状态 |
getMessageReadCount | 消息 | REST（HTTP） | {messageId:string, readCount:uint32, totalMembers:uint32} | 查询消息已读人数 |
getMessageReadUsers | 消息 | REST（HTTP） | {messageId:string, readCount:uint32, totalMembers:uint32, readers:UserProfile[]} | 查询已读用户明细（分页） |
getMessageReadDetail | 消息 | REST（HTTP） | {messageId:string, readCount:uint32, unreadCount:uint32, totalMembers:uint32, filter:string, offset:uint32, limit:uint32, total:uint32, hasMore:boolean, items:MessageReadDetailItem[]} | 查询单条消息的已读详情：已读/未读名单 + 具体读取时间（分页） |
searchMessages | 消息 | REST（HTTP） | {messages:Message[], total:uint32} | 在当前用户全部会话中搜索文本消息（倒序） |
getConversation | 会话 | REST（HTTP） | Conversation | 单会话详情 |
clearUnreadCount | 会话 | 长连接（WebSocket） | null | 清空会话未读（等价 read 帧 + 本地清零） |
setConversationToTop | 会话 | REST（HTTP） | null | 会话置顶/取消 |
saveTextMessageDraft | 会话 | REST（HTTP） | null | 保存草稿（空串=清除） |
getTextMessageDraft | 会话 | REST（HTTP） | string | 读取草稿 |
clearTextMessageDraft | 会话 | REST（HTTP） | null | 清除草稿 |
setConversationNotificationLevel | 会话 | REST（HTTP） | null | 会话提醒级别：0 全部 / 1 仅提及 / 2 免打扰 |
getUserProfile | 用户 | REST（HTTP） | UserProfile | 查询用户资料 |
updateMyUserProfile | 用户 | REST（HTTP） | UserProfile | 修改本人资料（name/avatarUrl） |
getOnlineStatus | 用户 | REST（HTTP） | {userId:string, online:bool, sessionCount:uint32} | 查询单个用户在线状态 |
getOnlineStatusBatch | 用户 | REST（HTTP） | {items:[{userId:string,online:bool,sessionCount:uint32}]} | 批量在线状态（<=100） |
searchUsers | 好友与黑名单 | REST（HTTP） | {users:[{userId:string,name:string,isFriend:bool,blacklisted:bool}], total:uint32} | 搜索用户（userId/name，大小写不敏感，排除自己） |
sendFriendRequest | 好友与黑名单 | REST（HTTP） | FriendRequest | 发起好友申请 |
getFriendRequests | 好友与黑名单 | REST（HTTP） | FriendRequest[] | 好友申请列表（incoming/outgoing，pending/all） |
acceptFriendRequest | 好友与黑名单 | REST（HTTP） | FriendRequest | 同意申请，双向建立好友关系 |
rejectFriendRequest | 好友与黑名单 | REST（HTTP） | FriendRequest | 拒绝申请 |
getFriends | 好友与黑名单 | REST（HTTP） | [{userId:string,name?:string,avatarUrl?:string,remark?:string,online?:bool,blacklisted?:bool}] | 好友列表（含备注/在线/拉黑标记） |
deleteFriend | 好友与黑名单 | REST（HTTP） | null | 双向删除好友 |
setFriendRemark | 好友与黑名单 | REST（HTTP） | null | 设置好友备注（<=64 字，空串清除） |
getBlacklist | 好友与黑名单 | REST（HTTP） | [{userId:string,name?:string}] | 黑名单列表 |
addToBlacklist | 好友与黑名单 | REST（HTTP） | null | 加入黑名单（幂等） |
removeFromBlacklist | 好友与黑名单 | REST（HTTP） | null | 移出黑名单 |
createGroup | 群组 | REST（HTTP） | Group | 创建群（groupType 缺省 normal） |
getGroupsInfo | 群组 | REST（HTTP） | Group[] | 批量查询群信息（<=20） |
addGroupMembers | 群组 | REST（HTTP） | {added:string[], group:Group} | 拉人入群（群主/管理员） |
removeGroupMembers | 群组 | REST（HTTP） | {removed:string[]} | 移除成员（群主/管理员） |
quitGroup | 群组 | REST（HTTP） | null | 退出群 |
updateGroupName | 群组 | REST（HTTP） | Group | 修改群名（群主/管理员） |
updateGroupNotice | 群组 | REST（HTTP） | Group | 设置群公告（群主/管理员，<=500 字，空串清除） |
transferGroupOwner | 群组 | REST（HTTP） | Group | 转让群主（新群主须为成员） |
addGroupAdmin | 群组 | REST（HTTP） | Group | 设置管理员（群主，幂等） |
removeGroupAdmin | 群组 | REST（HTTP） | Group | 取消管理员（群主） |
muteGroupMember | 群组 | REST（HTTP） | {groupId:string,userId:string,mutedUntil:uint64,group:Group} | 禁言/解禁（群主/管理员） |
createChatroom | 聊天室 | REST（HTTP） | Chatroom | 创建聊天室（客户端能力） |
getChatroomMembers | 聊天室 | REST（HTTP） | {members:ChatroomMember[], total:uint32} | 聊天室在线成员列表 |
getSystemMessages | 系统通知 | REST（HTTP） | {messages:Message[], hasMore:bool} | 系统通知历史（会话 conversationType=SYSTEM，targetId='system'） |
updateMessageExpansion | 消息 | REST（HTTP） | {messageId:string, expansion:Record<string,string>} | 更新已发送消息的扩展 KV（合并语义） |
removeMessageExpansion | 消息 | REST（HTTP） | {messageId:string, removed:string[], expansion:Record<string,string>} | 删除消息扩展 KV（按 key） |
addMessageReaction | 消息 | REST（HTTP） | {messageId:string, reactionId:string, userId:string, reactionTime:uint64} | 为指定消息添加回应（reactionId 由业务定义，1-16 字符） |
removeMessageReaction | 消息 | REST（HTTP） | {messageId:string, reactionId:string, removed:boolean} | 移除自己对指定消息的回应 |
batchGetMessageReactionSummaries | 消息 | REST（HTTP） | Record<string, ReactionSummary[]>（ReactionSummary={reactionId:string,totalCount:uint32,hasCurrentUserReacted:boolean,reactionTime:uint64,users:{userId:string,reactionTime:uint64}[]}） | 批量查询消息回应摘要（1-100 个 messageId） |
getMessageReactions | 消息 | REST（HTTP） | {reactions:ReactionSummary[], pageToken?:string, totalCount:uint32} | 分页查询指定消息的回应列表（count 1-50，默认 20） |
getMessageReactionUsers | 消息 | REST（HTTP） | {users:{userId:string,reactionTime:uint64}[], pageToken?:string, totalCount:uint32} | 分页查询某个回应的参与用户（count 1-50，默认 20） |
createConversationTag | 会话 | REST（HTTP） | ConversationTag | 创建会话标签（tagName ≤16） |
updateConversationTag | 会话 | REST（HTTP） | ConversationTag | 重命名会话标签 |
deleteConversationTag | 会话 | REST（HTTP） | void | 删除会话标签（同时清除标签内会话引用） |
getConversationTags | 会话 | REST（HTTP） | ConversationTag[] | 获取全部会话标签（含会话数量） |
addConversationsToTag | 会话 | REST（HTTP） | {added:int, existing:int, conversationCount:int} | 把会话加入标签（≤100/次，幂等） |
removeConversationsFromTag | 会话 | REST（HTTP） | {removed:int, conversationCount:int} | 把会话移出标签（≤100/次，幂等） |
getConversationsFromTagByPage | 会话 | REST（HTTP） | {total:int, items:ConversationTagConversation[]} | 分页获取标签内会话（含置顶/未读数/最后消息时间） |
getTagsFromConversation | 会话 | REST（HTTP） | ConversationTag[] | 查询某个会话所属的标签列表 |
getUnreadCountByTag | 会话 | REST（HTTP） | {unreadCount:int, unreadConversations:int, conversationCount:int} | 标签内未读汇总（消息总数 + 有未读的会话数） |
setConversationToTopInTag | 会话 | REST（HTTP） | void | 标签内置顶/取消置顶会话（同步会话会话级置顶状态） |
deleteConversation | 会话 | REST（HTTP） | {removed:bool} | 删除会话记录（列表项/未读/草稿/置顶），历史消息保留 |
getConversationTypeNotification | 会话 | REST（HTTP） | {conversationType:int, level:int} | 查询按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰） |
setConversationTypeNotification | 会话 | REST（HTTP） | {conversationType:int, level:int} | 设置按会话类型默认免打扰级别（0 全部 / 1 仅 @ / 2 免打扰） |
startStreamMessage | 消息 | REST（HTTP） | StreamMessage | 开始一条流式消息（IDL rev17） |
appendStreamMessage | 消息 | REST（HTTP） | StreamMessage | 追加一个流式增量（IDL rev17） |
completeStreamMessage | 消息 | REST（HTTP） | {streamId:string, messageId:string, text:string, status:streaming|ended, complete:bool, message?:Message} | 结束流式消息（IDL rev17） |
getStreamMessage | 消息 | REST（HTTP） | StreamMessage | 查询流式消息快照（IDL rev17） |
getMessageExpansion | 消息 | REST（HTTP） | {messageId:string, expansion:Record<string,string>} | 读取已发送消息的扩展 KV（IDL rev19） |
combineMessages | 消息 | 本地（无 IO） | CombineContent | 本地构造合并转发内容（IDL rev19，transport=local，不做网络 IO）：把 Message[] 转换为 `{type:'co… |
subscribePresence | 用户 | REST（HTTP） | {subscribed:string[]} | 订阅用户在线状态（IDL rev20） |
unsubscribePresence | 用户 | REST（HTTP） | {subscribed:string[]} | 取消订阅用户在线状态（IDL rev20） |
getPresenceSubscriptions | 用户 | REST（HTTP） | {userId:string, subscribed:string[]} | 查询当前用户的在线状态订阅列表（IDL rev20） |
registerPushToken | 用户 | REST（HTTP） | PushToken | 注册设备推送 token（IDL rev21 C23 收口） |
unregisterPushToken | 用户 | REST（HTTP） | {tokenId:string, userId:string, platform:string, deleted:bool, active:bool, alreadyInactive:bool} | 注销本人设备推送 token（IDL rev21 C23） |
getPushTokens | 用户 | REST（HTTP） | {userId:string, tokens:PushToken[], total:uint32, activeTotal:uint32, platforms:string[]} | 查询本人设备推送 token（IDL rev21 C23） |
createSupergroupChannel | 群组 | REST（HTTP） | SupergroupChannel | 创建超级群频道（IDL rev21 C17） |
listSupergroupChannels | 群组 | REST（HTTP） | {groupId:string, channels:SupergroupChannel[], total:uint32} | 超级群频道列表（IDL rev21 C17） |
joinSupergroupChannel | 群组 | REST（HTTP） | {groupId:string, channelId:string, userId:string, joined:bool, alreadyJoined:bool} | 加入超级群频道（IDL rev21 C17） |
leaveSupergroupChannel | 群组 | REST（HTTP） | {groupId:string, channelId:string, userId:string, left:bool, wasMember:bool} | 离开超级群频道（IDL rev21 C17） |
bindUserGroupToChannel | 群组 | REST（HTTP） | {groupId:string, channelId:string, userGroupId:string, bound:bool, reverseIndexed:bool} | 把用户组绑定到频道（IDL rev21 C17） |
createUserGroup | 群组 | REST（HTTP） | UserGroup | 创建超级群用户组（IDL rev21 C17） |
listUserGroups | 群组 | REST（HTTP） | {groupId:string, userGroups:UserGroup[], total:uint32} | 超级群用户组列表（IDL rev21 C17） |
getUserGroupsByUser | 群组 | REST（HTTP） | {userId:string, userGroups:UserGroup[], total:uint32} | 查询某用户所在的所有用户组（IDL rev21 C17） |
相关链接
- 本包：libim_sdk；类列表：类
- 数据结构：Chatroom（数据结构）、ChatroomMember（数据结构）、Conversation（数据结构）、Friend（数据结构）、FriendRequest（数据结构）、Group（数据结构）、GroupMember（数据结构）、im_event_cb（监听器）、全部
- 枚举：ChatroomEventKind（聊天室事件类型）、ConnectionStatus（连接状态）、ContentType（消息内容类型）、ConversationType（会话类型）、Direction（消息方向）、ErrorCode（错误码）、EventType（事件类型）、FriendEventKind（好友事件类型）、全部
- 错误码：ErrorCode；事件：im_event_cb
- 已过时 API：已过时 API；索引：索引