Class IMEngine

单例对象

初始化 SDK

获取 SDK 版本号

上报 APP 版本信息，服务端支持按上报的 App 版本处理自定义消息的推送内容

上设置断线重连时是否踢出重连设备。 用户没有开通多设备登录功能的前提下，同一个账号在一台新设备上登录的时候，会把这个账号在之前登录的设备上踢出。 由于 SDK 有断线重连功能，存在下面情况： 用户在 A 设备登录，A 设备网络不稳定，没有连接成功，SDK 启动重连机制。 用户此时又在 B 设备登录，B 设备连接成功。 A 设备网络稳定之后，用户在 A 设备连接成功，B 设备被踢出。 这个接口就是为这种情况加的。

设置鸿蒙推送 token

1. SDK 初始化之前设置：SDK 会将推送 token 缓存，连接成功后上报
2. SDK 初始化之后连接之前设置：连接成功后 SDK 自动上报
3. SDK 连接成功后设置：SDK 立即上报
Copy

设置数据库状态监听

数据库打开的时机：
1. IMToken 首次连接：SDK 不知道对应的用户 Id，所以必须等到连接成功才能打开数据
2. 使用相同 IMToken 再次连接：相同的 IMToken 一定代表相同的用户 Id，所以 SDK 先打开数据库后连接。凭借该特性可以在无网时立即打开数据库
3. 更换新的 IMToken 再次连接：逻辑同 IMToken 首次连接，SDK 不知道对应的用户 Id，所以必须等到连接成功才能打开数据
Copy

设置控制台日志级别

连接 IM

调用该接口，SDK 会在 timeLimit 秒内尝试重连，直到出现下面三种情况之一

第一、连接成功，回调 IConnectResult.code === EngineError.Success
第二、超时，回调 IConnectResult.code === EngineError.ConnectionTimeout，需要手动调用该接口继续连接
第三、出现 SDK 无法处理的错误，回调 IConnectResult.code 为具体的错误码

常见的错误如下：
ClientNotInit ：SDK 没有初始化，请先调用 init 接口

NaviRespTokenIncorrect ：检查一下 APP 使用的 appKey 和 APP Server 使用的 appKey 是否相同
ConnectTokenIncorrect ：检查一下 APP 使用的 appKey 和 APP Server 使用的 appKey 是否相同

ConnectOneTimePasswordUsed ：重新请求 Token
ConnectPlatformError ：重新请求 Token
ConnectTokenExpired ：重新请求 Token

ConnectAppBlockOrDelete ： 给用户提示 AppKey 已经封禁或删除

ConnectUserBlocked ：给用户提示被封禁
DisconnectUserKicked ：给用户提示被提掉线
DisconnectUserBlocked ：给用户提示被封禁
ConnectUserDeleteAccount ：给用户提示已销号
Copy

设置连接状态监听。每个连接状态都有详细的描述和处理意见

常见的错误如下：
DisconnectTokenIncorrect ： 检查一下 APP 使用的 appKey 和 APP Server 使用的 appKey 是否相同
DisconnectAppBlockOrDelete : 给用户提示该 AppKey 已经封禁或删除
DisconnectUserBlocked ：给用户提示已经被封禁
DisconnectUserKicked ： 给用户提示被提掉线
DisconnectTokenExpired ： 重新请求 Token
DisconnectOneTimePasswordUsed ： 重新请求 Token
DisconnectUserDeleteAccount ： 给用户提示已销户
DisconnectConnectionTimeout ： 连接超时，需要主动调用连接接口
DisconnectDatabaseOpenFailed ：由用户决定如何处理，用户可以将数据库备份之后再重连
Copy

获取当前连接状态

获取当前用户 ID

断开连接

设置消息接收监听

设置消息撤回监听，撤回了之后，原始消息会变成 RecallNotificationMessage 消息

设置消息敏感词拦截监听

发送消息

如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

发送媒体消息

如果遇到 DatabaseNotOpened = 34301 ，原因是在 IM 连接成功前发送了消息
IM 连接成功后 SDK 才会打开对应用户的消息数据库
Copy

下载媒体消息

撤回消息

注册自定义消息，连接之前调用

// 自定义消息示例代码
import { JsonConverter, MessageContent, MessageFlag, MessageTag } from '@rongcloud/imlib';
import List from '@ohos.util.List';

const CustomOrderMessageObjectName = "App:OrderMsg";
const CustomOrderMessageFlag = MessageFlag.Count;


// 1. 继承 MessageContent 并实现 MessageTag 注解
@MessageTag(CustomOrderMessageObjectName,CustomOrderMessageFlag)
class CustomOrderMessage extends MessageContent {
  // 2. 按需增加属性
  id: string = ""; // 订单 ID
  name: string = ""; // 订单名称
  price: number = 0; // 订单价格

  // 3. 必须声明无参的构造方法，因为注册自定义消息时候，只能用无参构造方法
  constructor() {
    super();
  }

  // 4. 将消息对象转为 JSON 字符串
  encode(): string {
    // 4.1 将基类的数据保存到 map 中
    let map = super.encodeBaseData();

    // 4.2 将本类的独有属性放到 map 中
    // 说明：ts 的 map 必须指定 kv 的类型，所以存多种类型数据，需要转为 Object
    if (this.id) {
      map.set("id", this.id as Object);
    }
    if (this.name) {
      map.set("name", this.name as Object);
    }
    map.set("price", this.price as Object);

    // 4.3 将 map 转为 字符串
    return JsonConverter.stringifyFromHashMap(map);
  }

  // 5. 将字符串转为消息对象
  decode(contentJson: string): void {
    // 5.1 将字符串转为 map
    let map = JsonConverter.parseToHashMap(contentJson);
    // 5.2 将基类的数据解析出来
    super.decodeBaseData(map);

    // 5.3 将本类的独有属性解析
    // 说明：需要将 Object 转为对应的数据类型
    if (map.get("id")) {
      this.id = map.get("id") as string;
    }
    if (map.get("name")) {
      this.name = map.get("name") as string;
    }
    if (map.get("price")) {
      this.price = map.get("price") as number;
    }
  }

  // 6. 将当前类名返回：该方法的作用是防止代码混淆或者压缩后无法获取正常的类名
  // 直接写字符串可能会出现拼写错误的情况，所以此处建议直接使用 类名.name
  getClassName(): string {
    return CustomOrderMessage.name;
  }


  // 7. 返回搜索字段
  // 1) 不实现该方法，该类消息无法被搜索
  // 2) 实现该方法，返回 null 或者 List 长度为 0，无法被搜索
  // 3) 实现该方法， List 里面的 空字符串 和 null 会被忽略
  // 4) List 中必须包含有效的字符串才能被搜索到
  getSearchableWord(): List | null {
   if (!this.name) {
     return null;
   }
   let list = new List();
   list.add(this.name);
   return list;
  }
}

export { CustomOrderMessage, CustomOrderMessageObjectName }
Copy

// 注册自定义消息示例代码
let clazzList: List<MessageContentConstructor> = new List();
clazzList.add(CustomOrderMessage);
IMEngine.getInstance().registerMessageType(clazzList);
Copy

获取 SDK 中所有的消息 objectName 和存储标识的映射关系

注意事项：
1. 映射关系集合包含 内置消息 和 自定义消息
2. 必须在所有自定义消息注册完成之后再调用该方法，否则会导致无法正确获取自定义消息的映射关系
3. 不要频繁调用该方法：建议 app 调用该方法之后， app 自行保存整个集合
Copy

其他平台说明：
iOS 通过 RCMessagePersistentCompatible.persistentFlag 获取消息存储标识
Android 通过 getClass().getAnnotation(MessageTag.class) 获取消息存储标识
鸿蒙需要通过本方法获取
Copy

如何获取 objectName？
1. 发送消息时需要手动构造指定的消息体，可以直接获取到 objectName：例如创建文本消息时一定知道是文本消息的 objectName
2. 接收消息时通过 Message 对象获取：Message.objectName
3. 读取会话时通过 Conversation 对象获取：Conversation.objectName
Copy

消息批量入库（多用于数据迁移）

Message 下列属性会被入库，其他属性会被抛弃：

conversationType   会话类型
targetId           会话 ID
channelId          所属会话的业务标识，长度限制 20 字符
direction          消息方向
senderId           发送者 ID
receivedStatus     接收状态
sentStatus         发送状态
sentTime           发送时间
content            消息内容
objectName         消息类型，设置 content 的时候 SDK 会自动赋值对应的 objectName
messageUid         服务端生产的消息唯一 ID，如要携带该字段需要保证入库后是唯一的
extra              扩展信息
Copy

单条消息入库

Message 下列属性会被入库，其他属性会被抛弃：

conversationType   会话类型
targetId           会话 ID
direction          消息方向，默认为发送
senderId           发送者 ID
receivedStatus     接收状态，默认为未读
sentStatus         发送状态，默认为发送失败
sentTime           发送时间
content            消息内容
objectName         消息类型，设置 content 的时候 SDK 会自动赋值对应的 objectName
messageUid         服务端生产的消息唯一 ID，如要携带该字段需要保证入库后是唯一的
extra              扩展信息
Copy

通过 messageId 获取单条消息

通过 messageUid 获取单条消息

获取批量本地消息，基于 messageId 获取

获取批量本地消息，基于 time 获取

获取批量远端消息

获取本地会话中 @ 自己的未读消息列表

获取会话里第一条未读消息

删除本地会话的指定一批消息

清空本地会话的消息

删除本地会话特定时间前的所有消息

删除远端会话特定时间前的消息

批量删除远端消息，发送成功或者接收到的消息才可以从远端删除

msgList 里面 Message 下列属性是必须的
uid:               服务端生产的消息唯一 id
direction:         消息方向
sentTime:          发送时间，不能小于等于 0
Copy

设置输入状态的监听

发送输入状态，仅支持单聊

常见的使用方式如下：
在聊天页面输入文本时，可以发送 TextMessageObjectName ，对方收到后可以展示"正在输入中"
在录音时，可以发送 HQVoiceMessageObjectName ，对方收到后可以展示"正在说话"
Copy

设置输入状态更新时间间隔

控制输入状态发送频率，在规定时间内多次调用发送输入状态方法，最终只会发送一次输入状态
例如输入状态时间间隔为 6000 毫秒，在这段时间多次调用输入状态方法，只会发出一次输入状态，对方也只会收到一次输入状态
Copy

设置消息扩展监听

更新消息扩展信息

调用更新扩展的一方必须通过成功回调来处理本端的数据刷新。
仅被动接收扩展变更的用户（包含本用户的其他端）通过监听方法 MessageExpansionListener.onMessageExpansionUpdate 获取通知。
消息扩展信息是以字典形式存在。设置的时候从 expansion 中读取 key，如果原有的扩展信息中 key 不存在则添加新的 KV 对，如果 key 存在则替换成新的 value。
扩展信息字典中的 Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 32；Value 最长长度 4096，单次设置扩展数量最大为 20，消息的扩展总数不能超过 300
Copy

删除消息扩展信息中特定的键值对

调用删除扩展的一方必须通过成功回调来处理本端的数据刷新。
仅被动接收扩展变更的用户（包含本用户的其他端）通过监听方法 MessageExpansionListener.onMessageExpansionRemove 获取通知。
Copy

设置会话状态（置顶，消息免打扰）变化监听

获取单个会话

分页获取本地会话列表

分页获取本地置顶会话列表

分页获取本地免打扰会话列表

获取本地未读会话列表，该接口仅支持单聊、群聊、系统三种会话类型，不支持聊天室、超级群。

删除本地会话同时删除会话中的消息

批量删除本地会话，但是不会删除消息

批量 设置/取消 会话置顶

获取会话置顶状态

批量设置会话免打扰

获取单个会话免打扰状态

保存/清空 会话草稿

获取会话草稿

屏蔽某个时间段的消息提醒

查询已设置的时间段消息提醒屏蔽

删除已设置的全局时间段消息提醒屏蔽

获取本地会话的全部未读数

获取本地批量会话的未读数之和

获取单个会话的未读数

清空单个会话未读数

清除单个会话的未读数：按照时间戳清除

会话未读数，是否包含免打扰会话的未读数

同步会话已读状态

用于相同账号的多端已读同步
例如用户 A 同时登录鸿蒙和 Android，两端同时收到消息，同时未读数增加
Android 调用该方法将某个会话同步已读之后， 鸿蒙会触发 setSyncConversationReadStatusListener
Copy

设置会话已读状态监听

根据关键字搜索本地会话。

根据关键字搜索本地会话。

根据关键字搜索指定消息类型的本地消息。

根据关键字和指定时间段搜索指定会话中的消息。

根据用户 id 搜索指定会话中的本地消息。

获取本地订阅的所有公众号（仅支持私有云）

获取本地订阅的指定公众号

设置聊天室状态监听

let listener: ChatroomStatusListener = {
 onChatroomJoining(roomId: string): void {
   hilog.info(0x0000, 'IM-App', 'onChatroomJoining roomId:%{public}s', roomId);
 },

 onChatroomJoined(roomId: string, info: ChatroomJoinedInfo): void {
   hilog.info(0x0000, 'IM-App', 'onChatroomJoined roomId:%{public}s info:%{public}s', roomId, JSON.stringify(info));
 },

 onChatroomJoinFailed(roomId: string, code: EngineError): void {
   hilog.info(0x0000, 'IM-App', 'onChatroomJoined roomId:%{public}s code:%{public}d', roomId, code);
 },

 onChatroomQuited(roomId: string): void {
   hilog.info(0x0000, 'IM-App', 'onChatroomQuited roomId:%{public}s', roomId);
 },

 onChatroomDestroyed(roomId: string, type: ChatroomDestroyType): void {
   hilog.info(0x0000, 'IM-App', 'onChatroomDestroyed roomId:%{public}s type:%{public}d', roomId, type);
 },
}
IMEngine.getInstance().setChatroomStatusListener(listener);
Copy

加入聊天室，如果聊天室不存在则创建聊天室

加入已经存在的聊天室

退出聊天室

获取聊天室信息

设置聊天室自定义属性

entries 最大限制为 10
key ： 聊天室属性名称，长度范围 [1~128]，支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式
value : 聊天室属性对应的值，长度范围 [1~4096]
Copy

删除聊天室自定义属性

获取本地指定一批聊天室自定义属性

获取本地聊天室全部自定义属性

设置聊天室 KV 状态变化的监听

设置聊天室成员变化监听

设置聊天室事件通知监听器