xhim_v1 C ABI Reference

普通 iOS、Android、Windows、HarmonyOS App 不需要使用本页。 本页面向 XHIM 平台 Wrapper 维护者和自研语言 Bridge。

唯一稳定的跨语言二进制边界是 ffi/include/xhim/xhim_v1.h。C++ 类布局、 STL 类型和内部 Engine 接口不属于兼容合同。

1. 版本和能力

• xhim_v1_abi_version
• xhim_v1_version_string
• xhim_v1_source_commit
• xhim_v1_client_get_compatibility
• xhim_v1_client_get_device_session_policy
• xhim_v1_client_get_diagnostics

Wrapper 初始化时必须核对 ABI version。发行包还应核对 wrapper、native library 和 manifest 的版本/commit 一致性。

2. Client 生命周期

• xhim_v1_client_create
• xhim_v1_client_start
• xhim_v1_client_login
• xhim_v1_client_update_credential
• xhim_v1_client_logout
• xhim_v1_client_get_state
• xhim_v1_client_notify_network_available
• xhim_v1_client_shutdown
• xhim_v1_client_destroy

shutdown 是异步收尾，destroy 是最终释放。外部必须把 destroy 与所有 Client API 串行化；destroy 开始后不得再提交请求。

3. 订阅与取消

• xhim_v1_client_subscribe
• xhim_v1_subscription_cancel
• xhim_v1_client_cancel_request

同一 subscription handle 只取消一次。每个被接纳的异步请求返回非零 request ID；普通请求取消使用这个 ID。事件与 completion 在 native 私有串行 callback 线程执行。

4. 消息

• xhim_v1_client_send_text
• xhim_v1_client_send_message
• xhim_v1_client_edit_text_message
• xhim_v1_client_recall_message
• xhim_v1_client_get_message
• xhim_v1_client_retry_message
• xhim_v1_client_cancel_message
• xhim_v1_client_list_messages
• xhim_v1_client_search_messages
• xhim_v1_client_get_message_history
• xhim_v1_client_delete_message_for_self

输入 byte views 在函数返回前由 Core 复制。Completion snapshot 中的 byte views 只在 callback 期间有效，Wrapper 必须先复制再恢复语言层 Future/Promise。

5. 会话与已读

• xhim_v1_client_list_conversations
• xhim_v1_client_get_or_create_direct_conversation
• xhim_v1_direct_conversation_get_participant_user_ids
• xhim_v1_client_clear_conversation
• xhim_v1_client_hide_conversation
• xhim_v1_client_mark_conversation_read
• xhim_v1_client_mark_all_conversations_read
• xhim_v1_client_get_total_unread_count
• xhim_v1_client_list_conversation_peer_reads
• xhim_v1_client_set_conversation_preference
• xhim_v1_client_set_conversation_draft
• xhim_v1_client_get_conversation_draft
• xhim_v1_client_clear_conversation_draft

6. 用户、Push 和设备会话

• xhim_v1_client_get_current_user_profile
• xhim_v1_client_get_user_profiles
• xhim_v1_user_profile_page_get_missing_user_ids
• xhim_v1_client_update_current_user_profile
• xhim_v1_client_register_push_device
• xhim_v1_client_disable_push_device
• xhim_v1_client_list_device_sessions
• xhim_v1_client_revoke_device_session

7. 好友、黑名单和群组

• xhim_v1_client_send_friend_request
• xhim_v1_client_resolve_friend_request
• xhim_v1_client_delete_friendship
• xhim_v1_client_set_friend_remark
• xhim_v1_client_list_friend_requests
• xhim_v1_client_list_friendships
• xhim_v1_social_page_get_friendship_remarks
• xhim_v1_client_set_block
• xhim_v1_client_list_blocks
• xhim_v1_client_create_group
• xhim_v1_client_change_group_members
• xhim_v1_client_leave_group
• xhim_v1_client_dismiss_group
• xhim_v1_client_request_group_join
• xhim_v1_client_resolve_group_join
• xhim_v1_client_change_group_governance
• xhim_v1_client_list_groups
• xhim_v1_social_page_get_group_profiles
• xhim_v1_client_list_group_members
• xhim_v1_client_list_group_join_requests

8. Presence 与 Typing

• xhim_v1_client_publish_presence
• xhim_v1_client_publish_typing

短暂状态通过 XHIM_V1_EVENT_PRESENCE_CHANGED 和 XHIM_V1_EVENT_TYPING_CHANGED 发送，必须读取 sequence、event ID 和过期时间。

9. 媒体任务与缓存

• xhim_v1_client_create_media_upload
• xhim_v1_client_create_media_download
• xhim_v1_client_get_media_task
• xhim_v1_client_cancel_media_task
• xhim_v1_client_open_media_cache_reader
• xhim_v1_media_cache_reader_get_size
• xhim_v1_media_cache_reader_read
• xhim_v1_media_cache_reader_destroy

媒体任务 snapshot 不包含本地路径、credential 或 signed URL。Cache Reader 与 Client 是不同 opaque handle，必须显式 destroy。

10. 离线只读

• xhim_v1_offline_reader_create
• xhim_v1_offline_reader_list_messages
• xhim_v1_offline_reader_search_messages
• xhim_v1_offline_reader_list_conversations
• xhim_v1_offline_reader_list_friend_requests
• xhim_v1_offline_reader_list_friendships
• xhim_v1_offline_reader_list_groups
• xhim_v1_offline_reader_list_group_members
• xhim_v1_offline_reader_list_blocks
• xhim_v1_offline_reader_list_group_join_requests
• xhim_v1_offline_reader_destroy

Offline Reader 不得启动 Transport、Sync 或 Outbox。数据库 Key Provider 的输出 只用于打开加密数据库，不能写入错误、日志或 diagnostics。

11. 状态码

立即返回值表示请求是否被接纳：

• XHIM_V1_STATUS_OK：请求已接纳，最终结果仍等待 completion；
• 参数、状态或已关闭错误：不会再产生 completion；
• 请求接纳后只完成一次，成功或失败二选一。

完整状态码和稳定错误字段见 模型、枚举与错误。Bridge 必须保留 domain + stable_code、retry 信息、user action、operation ID 和 trace ID， 不能只抛一个 message 字符串。

12. struct_size 兼容

所有公开结构：

1. 调用方写入自己的 struct_size 和 XHIM_V1_ABI_VERSION；
2. 读取 native snapshot 尾部前检查 struct_size；
3. 新字段只追加在 v1 兼容尾部；
4. 不读取未知尾部，不要求旧版本认识新枚举值；
5. 未知枚举保留原始数值并映射到平台 unknown。

导出符号基线位于 compatibility/abi-baseline/xhim_v1.exports。 文档门禁会检查基线中的每个导出都在本页出现。