插入消息
IMLib SDK 支持在本地数据库中插入消息。本地插入的消息不会实际发送给融云服务器和对方。
提示
- 请确保所有插入的消息均为支持客户端本地存储的消息，否则会报错。详见了解消息存储策略。
- 插入消息的接口仅将消息插入本地数据库，所以当 App 卸载重装或者换端登录时插入的消息不会从远端同步到本地数据库。
插入发送消息
您可以通过 insertOutgoingMessage: 接口在本地数据库插入一条 对外发送的消息。以下示例使用 RCChannelClient 下的 insertOutgoingMessage 方法。
提示
- 如果 sentTime 有问题会影响消息排序，请谨慎使用！
- 此接口不支持聊天室会话类型。
接口原型
Objective C
- (void)insertOutgoingMessage:(RCConversationType)conversationType
targetId:(NSString *)targetId
sentStatus:(RCSentStatus)sentStatus
content:(RCMessageContent *)content
sentTime:(long long)sentTime
completion:(nullable void(^)(RCMessage *_Nullable message))completion;
插入本地数据库的消息如需支持消息扩展功能，必须使用 RCChannelClient 下的插入方法，否则无法打开消息的可扩展属性（canIncludeExpansion）。本地插入消息时不支持设置消息扩展信息数据。您可以在消息插入后，选择合适的时机为消息设置扩展数据。详见消息扩展。
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | RCConversationType | 会话类型。 |
targetId | NSString | 会话 targetId |
channelId | NSString | 超级群会话的频道 Id，非超级群会话传 nil。 |
canIncludeExpansion | BOOL | 是否支持消息扩展。YES表示可扩展；NO 表示不可扩展。 |
sentStatus | RCSentStatus | 发送状态。 |
content | RCMessageContent | 消息的内容。 |
sentTime | long long | 消息发送的 Unix 时间戳，单位为毫秒（传 0 会按照本地时间插入）。 |
completion | Block | 异步回调，返回已插入的消息实体 RCMessage。 |
示例代码
Objective C
RCTextMessage *content = [RCTextMessage messageWithContent:@"测试文本消息"];
[[RCChannelClient sharedChannelManager]
insertOutgoingMessage:ConversationType_PRIVATE
targetId:@"targetId"
channelId:@"channelId"
canIncludeExpansion:YES
sentStatus:SentStatus_SENT
content:content
sentTime:sentTime
completion::^(RCMessage * _Nullable message) {
}];
插入接收消息
您可以通过 insertIncomingMessage: 接口在本地数据库被插入一条接收的消息。
提示
- 如果消息的 sentTime 有问题会影响消息排序，慎用！
- 5.6.8 版本后使用 RCReceivedStatusInfo 对象构造接收消息状态，5.6.8 版本前使用 RCReceivedStatus 对象构造消息接收状态。
接口原型
objectivec-
targetId:(NSString *)targetId
senderUserId:(NSString *)senderUserId
receivedStatusInfo:(RCReceivedStatusInfo *)receivedStatusInfo
content:(RCMessageContent *)content
sentTime:(long long)sentTime
completion:(nullable void(^)(RCMessage *_Nullable message))completion;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
conversationType | RCConversationType | 会话类型，单聊传入 ConversationType_PRIVATE |
targetId | NSString | targetId 用于标识会话，称为目标 ID 或会话 ID。注意，因为单聊业务中始终使用对端用户 ID 作为标识本端会话 的 Target ID，因此在单聊会话中插入本端接收的消息时，Target ID 始终是单聊对端用户 ID。群聊、超级群的会话 ID 分别为群组 ID、超级群 ID。详见消息介绍中关于 Target ID 的说明。 |
senderUserId | NSString | 发送者ID |
RCReceivedStatusInfo | RCReceivedStatusInfo | 消息接收状态 |
content | RCMessageContent | 消息的内容 |
sentTime | long long | 消息发送的Unix时间戳，单位为毫秒（传 0 会按照本地时间插入） |
completion | Block | 异步回调，返回已插入的消息实体 RCMessage |
示例代码
Objective C
RCTextMessage *content = [RCTextMessage messageWithContent:@"测试文本消息"];
RCReceivedStatusInfo * info = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:0];
[[RCCoreClient sharedCoreClient] insertIncomingMessage:ConversationType_PRIVATE
targetId:@"targetId"
senderUserId:@"senderUserId"
receivedStatusInfo:info
content:content
sentTime:0
completion:^(RCMessage * _Nullable message) {
}];
插入消息体
您可通过下面接口在本地数据库插入一条构造好的消息体。
提示
- 如果消息的 sentTime 有问题会影响消息排序，慎用！
- IMLib SDK 5.12.2 版本之后，
RCMessaage新增disableUpdateLastMessage属性，可以控制这条消息是否更新到会话最新一条消息。disableUpdateLastMessage属性的默认值为 NO，代表更新。您可以设置为 YES，不更新到会话最新一条消息。
- 以下是插入一条发送的消息体
Objective C
RCTextMessage *txtMessage = [RCTextMessage messageWithContent:@"测试文本消息"];
RCMessage *outgoing = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
targetId:@"targetID"
channelId:@"channelID"
direction:MessageDirection_SEND
content:txtMessage];
outgoing.senderUserId = @"own user id";
outgoing.sentStatus = SentStatus_SENT;
outgoing.canIncludeExpansion = YES;// 如需后续支持扩展能力，插入前需要设置
outgoing.disableUpdateLastMessage = YES;// 不更新会话最新一条消息
[[RCCoreClient sharedCoreClient] insertMessage:outgoing successBlock:successBlock errorBlock:errorBlock];
- 以下是插入一条接收的消息体
Objective C
RCTextMessage *txtMessage = [RCTextMessage messageWithContent:@"测试文本消息"];
RCMessage *incoming = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
targetId:@"targetID"
direction:MessageDirection_RECEIVE
content:txtMessage];
incoming.senderUserId = @"senderUserId";
RCReceivedStatusInfo *statusInfo = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:0];
[statusInfo markAsRead];
incoming.receivedStatusInfo = statusInfo;
incoming.disableUpdateLastMessage = YES;// 不更新会话最新一条消息
[[RCCoreClient sharedCoreClient] insertMessage:incoming successBlock:successBlock errorBlock:errorBlock];
批量插入消息
提示
- 从 5.1.1 版本 IMLib SDK 开始支持批量插入消息功能。
- 从 5.3.0 版本开始，建议使用
RCCoreClient的异步方法batchInsertMessage:返回对应的插入结果，原同步接口同时废弃。 - 由于批量插入本地数据库失败时会使数据整体插入失败，建议分批插入。单次操作最多插入 500 条消息，建议单次插入 10 条。
- 该功能不支持聊天室会话类型，不支持超级群会话类型。
RCMessage 的下列属性会被入库，其余属性会被抛弃：
conversationType：会话类型。messageUId：消息全局唯一 ID，消息成功收发后会带有由服务端生成的全局唯一 ID。SDK 从 5.3.5 开始支持入库该属性，该字段一般用于迁移数据。targetId：会话 ID。messageDirection：消息方向。senderUserId：发送者 ID。receivedStatus：接收状态；如果消息方向为接收方，并且receivedStatus为ReceivedStatus_UNREAD时，该条消息未读。未读消息数会累加到会话的未读消息数上。sentStatus：发送状态。content：消息的内容。sentTime：消息发送的 Unix 时间戳，单位为毫秒，会影响消息排序。extra：消息附加信息
接口原型
Objective C
/*!
异步批量插入接收的消息（该消息只插入本地数据库，实际不会发送给服务器和对方）
@discussion 此方法不支持聊天室的会话类型。不支持超级群会话类型。每批最多处理 500 条消息，超过 500 条返回 NO
@discussion 消息的未读会累加到会话的未读数上
@remarks 消息操作
*/
- (void)batchInsertMessage:(NSArray<RCMessage *> *)msgs completion:(nullable void(^)(BOOL))completion;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
msgs | NSArray | 消息实体 RCMessage 对象列表。单次操作最多插入 500 条消息，建议单次插入 10 条。注意，message 中必须包含正确有效的 sentTime（消息发送的 Unix 时间戳，单位为毫秒），否则无法通过获取历史消息接口从数据库中获取该消息。 |
completion | Block | 异步回调，返回是否插入成功 |
批量插入消息提供以下方法，设置 checkDuplicate 为 YES 后，IMLib SDK 会在插入时检查当前消息的 messageUId 是否与数据库中消息的 messageUId 重复，并移除重复项。注意，App 应自行保证插入的消息数组内部的消息无重复的 messageUId。
Objective C
- (void)batchInsertMessage:(NSArray<RCMessage *> *)msgs checkDuplicate:(BOOL)checkDuplicate completion:(nullable void(^)(BOOL ret))completion;
批量插入带原始 JSON 数据的消息
提示
- 从
5.40.0版本开始，IMLib SDK 支持通过RCCoreClient高性能批量插入原始消息。 - 该接口适用于批量迁移或导入需要保留原始 JSON 数据的消息。与
batchInsertMessage:不同，SDK 会直接使用RCMessage.content.rawJSONData入库，不会将消息内容编码为各消息类型对应的 payload。 - 该接口不支持聊天室和超级群会话类型。
该接口主要面向历史消息迁移、跨端数据导入、备份恢复等需要批量写入本地消息数据库的场景。例如，业务侧已经持有服务端消息的原始 JSON 数据，并希望尽量保留原始消息结构、减少批量插入时的消息内容编解码开销，可以使用该接口。该接口只写入本地数据库，不会把消息发送给融云服务端或会话成员。
该接口不会检查待插入消息是否已存在，也不会移除重复消息。App 需要在调用前自行完成排重，并保证传入的消息列表内部以及待插入消息与本地数据库中已有消息之间没有重复数据。
如果只是插入少量应用内生成的本地消息，或不需要保留原始 JSON 数据，建议继续使用普通 batchInsertMessage: 接口。
RCMessage 的下列属性会被入库，其余属性会被抛弃：
conversationType：会话类型。targetId：会话 ID。messageUId：消息 全局唯一 ID，通常用于迁移已有消息数据。objectName：消息类型标识。messageDirection：消息方向。senderUserId：发送者 ID。receivedStatusInfo：消息接收状态。当消息方向为接收，且receivedStatusInfo.receivedStatus为未读时，消息未读数会累加到对应会话中。sentStatus：消息发送状态。content.rawJSONData：消息内容的原始 JSON 数据。sentTime：消息发送的 Unix 时间戳，单位为毫秒，会影响消息排序。extra：消息附加信息。
接口原型
Objective C
- (void)batchInsertOriginalMessage:(NSArray<RCMessage *> *)messages
success:(nullable void (^)(void))successBlock
error:(nullable void (^)(RCErrorCode status))errorBlock;
参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
messages | NSArray<RCMessage *> | 待插入的消息列表，数组元素为 RCMessage。单次必须传入 1 到 500 条消息。 |
successBlock | Block | 插入成功回调。 |
errorBlock | Block | 插入失败回调，返回错误码。 |
如果您使用 RCMessageContent 基类承载原始 JSON，建议显式设置 message.objectName，用于保留消息类型标识。请确保 message 中包含正确有效的 sentTime，否则可能无法通过历史消息接口按时间查询该消息。
示例代码
Objective C
RCMessageContent *content = [[RCMessageContent alloc] init];
content.rawJSONData = [@"{\"content\":\"测试文本消息\"}" dataUsingEncoding:NSUTF8StringEncoding];
RCMessage *message = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
targetId:@"targetId"
direction:MessageDirection_RECEIVE
content:content];
message.senderUserId = @"senderUserId";
message.messageUId = @"original_uid_1";
message.objectName = @"RC:TxtMsg";
message.sentTime = 1748400000000;
message.receivedStatusInfo = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:ReceivedStatus_UNREAD];
[[RCCoreClient sharedCoreClient] batchInsertOriginalMessage:@[ message ]
success:^{
}
error:^(RCErrorCode status) {
}];