Class IMEngine

单例对象

Version

1.0.0

初始化 SDK

Version

1.0.0

获取 SDK 版本号

Version

1.0.0

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

Note

当 SDK 初始化时就会用该字段，所以必须在 init 之前调用

Version

1.0.0

设置鸿蒙推送 token

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

Version

1.0.0

设置数据库状态监听

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

Discussion

init 之后 connect 之前调用。connect 成功之后调用不会有任何效果

Version

1.1.0

设置控制台日志级别

Discussion

例如：填入 LogLevel.None ，SDK 将不再控制台输出日志

Discussion

例如：填入 LogLevel.Warn ，SDK 将会在控制台输出 Warn 和 Error 的日志

Version

1.0.0

连接 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

Note

连接成功后，SDK 将接管所有的重连处理。当因为网络原因断线的情况下，SDK 会不停重连直到连接成功为止，不需要您做额外的连接操作。

See

IConnectResult

Version

1.0.0

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

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

See

ConnectionStatus

Version

1.0.0

获取当前连接状态

See

ConnectionStatus

Version

1.0.0

获取当前用户 ID

Version

1.0.0

断开连接

Note

SDK 在前后台切换或者网络出现异常都会自动重连，会保证连接的可靠性，除非您的 App 逻辑需要登出，否则一般不需要调用此方法进行手动断开

Version

1.0.0

设置消息接收监听

Note

刷新逻辑参考 ReceivedInfo

Version

1.0.0

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

Version

1.0.0

设置消息敏感词拦截监听

Discussion

当发送消息触发敏感词拦截的时候，会触发该回调

See

MessageBlockInfo

Version

1.0.0

发送消息

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

Discussion

只有入库成功才会走 savedCallback，其他的情况：非法参数、入库失败、发送不入库的消息等都不会走 savedCallback 直接走 resultCallback

Note

SDK 内置消息都有推送，自定义消息必须设置 Message.pushConfig

Version

1.0.0

发送媒体消息

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

Discussion

只有入库成功才会走 savedCallback，其他的情况：非法参数、入库失败、发送不入库的消息等都不会走 savedCallback 直接走 resultCallback

Version

1.0.0

下载媒体消息

Note

调用该接口下载成功后，消息的本地路径会保存数据库中；相同的消息重复下载，会直接返回本地路径

Version

1.0.0

撤回消息

Discussion

pushContent 用 Message.pushConfig

Version

1.0.0

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

// 自定义消息示例代码
import { JsonUtil, 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
    map.set("id", this.id as Object);
    map.set("name", this.name as Object);
    map.set("price", this.price as Object);

    // 4.3 将 map 转为 字符串
    return JsonUtil.stringifyFromMap(map);
  }

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

    // 5.3 将本类的独有属性解析
    // 说明：需要将 Object 转为对应的数据类型
    this.id = map.get("id") as string;
    this.name = map.get("name") as string;
    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

Note

自定义消息需要继承 MessageContent 并且实现无参构造方法才能注册给 SDK

Version

1.0.0

消息批量入库

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

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

Version

1.0.0

通过 messageId 获取单条消息

Version

1.0.0

通过 messageUid 获取单条消息

Version

1.0.0

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

See

• ConversationIdentifier
• IGetLocalMsgByIdOption

Version

1.0.0

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

See

• ConversationIdentifier
• IGetLocalMsgByTimeOption

Version

1.0.0

获取批量远端消息

Note

此方法从服务器端获取之前的历史消息，但是必须先开通历史消息云存储功能

See

• ConversationIdentifier
• IGetLocalMsgByTimeOption

Version

1.0.0

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

See

• ConversationIdentifier
• ICountOption

Version

1.0.0

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

See

ConversationIdentifier

Version

1.0.0

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

Version

1.0.0

清空本地会话的消息

See

ConversationIdentifier

Version

1.0.0

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

See

ConversationIdentifier

Version

1.0.0

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

See

ConversationIdentifier

Version

1.0.0

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

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

Version

1.1.0

设置输入状态的监听

Version

1.1.0

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

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

Version

1.1.0

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

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

Version

1.1.0

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

Version

1.0.0

获取单个会话

See

ConversationIdentifier

Version

1.0.0

分页获取本地会话列表

See

IGetConversationOption

Version

1.0.0

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

See

IGetConversationOption

Version

1.0.0

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

See

IGetConversationOption

Version

1.0.0

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

Version

1.1.0

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

Version

1.0.0

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

Version

1.0.0

批量 设置/取消 会话置顶

See

ISetConversationTopOption

Version

1.0.0

获取会话置顶状态

Version

1.0.0

批量设置会话免打扰

Version

1.0.0

获取单个会话免打扰状态

Version

1.0.0

保存/清空 会话草稿

Discussion

保存成功的草稿可以通过 Conversation.draft 获取

Version

1.0.0

获取会话草稿

Version

1.0.0

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

Discussion

此方法设置的屏蔽时间会在每天该时间段时生效。

Version

1.0.0

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

Version

1.0.0

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

Version

1.0.0

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

Version

1.0.0

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

Version

1.0.0

获取单个会话的未读数

Version

1.0.0

清空单个会话未读数

Version

1.0.0

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

Version

1.0.0

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

Discussion

正常单聊会话 A 的未读数为1，免打扰单聊会话 B 的未读数为 2。true 代表获取两个单聊会话的未读数之和，其结果为 3。false 代表获取正常会话 A 的未读数，结果为 1

Version

1.0.0

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

Version

1.1.0

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

Version

1.1.0

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

Version

1.1.0

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

Version

1.1.0

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

Version

1.1.0

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

Version

1.1.0

设置聊天室状态监听

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

See

ChatroomStatusListener

Version

1.0.0

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

Version

1.0.2

加入已经存在的聊天室

Discussion

如果加入不存在的聊天室会报错 ChatroomNotExist

Note

聊天室的创建需要通过 AppServer 调用 IM 服务的 ServerAPI 创建

Version

1.0.0

退出聊天室

Version

1.0.0

获取聊天室信息

See

ICountOption

Version

1.0.0

设置聊天室自定义属性

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

Discussion

每个聊天室支持设置最大 KV 数为 100，如果聊天室已经有 100 个 KV，则无法再增加新的 KV

Version

1.1.0

删除聊天室自定义属性

Version

1.1.0

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

Discussion

见 ChatroomKVStatusListener.onChatroomKVSync

Version

1.1.0

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

Discussion

见 ChatroomKVStatusListener.onChatroomKVSync

Version

1.1.0

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

Version

1.1.0

设置聊天室成员变化监听

Version

1.1.0

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

Version

1.1.0