历史消息

云信支持在客户端本地与云端存储历史消息,供后续查询。

本地历史消息

本地历史消息查询

原型

@protocol NIMConversationManager <NSObject>
/**
 *  从本地db读取一个会话里某条消息之前的若干条的消息
 *
 *  @param session 消息所属的会话
 *  @param message 当前最早的消息,没有则传入nil
 *  @param limit   个数限制
 *
 *  @return 消息列表,按时间从小到大排列
 */
- (nullable NSArray<NIMMessage *> *)messagesInSession:(NIMSession *)session
                                              message:(nullable NIMMessage *)message
                                                limit:(NSInteger)limit;
@end

属性列表

参数 类型 说明
session NIMSession 消息所属的会话
message NIMMessage 锚点消息
limit NSInteger 读取条数限制

传入一个已知的消息(锚点消息),返回比这个消息更早的消息集合。如果没有已知的消息,则传入 nil,返回最新的消息集合。查询结果按照旧消息到新消息的顺序排列。

示例

// NIMSessionMsgDatasource.m

- (void)resetMessages:(void(^)(NSError *error)) handler
{    
    ...
    //获取到本地会话最后 limit 个消息并接到数据末尾
    NSArray<NIMMessage *> *messages = [[[NIMSDK sharedSDK] conversationManager] messagesInSession:_currentSession
                                                                                message:nil
                                                                                    limit:_messageLimit];
    [self appendMessageModels:[self modelsWithMessages:messages]];
    ...
}

按消息id查询

@protocol NIMConversationManager <NSObject>
/**
 *  根据消息Id获取消息
 *
 *  @param session    消息所属会话结合
 *  @param messageIds 消息Id集合
 *  @return 消息列表,按时间从小到大排列
 */
- (nullable NSArray<NIMMessage *> *)messagesInSession:(NIMSession *)session
                                           messageIds:(NSArray<NSString *> *)messageIds;
@end

属性列表

参数 类型 说明
session NIMSession 消息所属的会话
messageIds NSArray 消息Id集合

删除本地消息

删除单条消息


@protocol NIMConversationManager <NSObject>

/**
 *  删除某条消息
 *
 *  @param message 待删除的聊天消息
 *  @param option  删除选项。
 */
- (void)deleteMessage:(NIMMessage *)message 
               option:(nullable NIMDeleteMessageOption *)option;

@end

调用此方法时,如果删除的是最后一条消息,消息所属的最近会话的 lastMessage 属性会自动变成上一条消息(没有则为空消息),同时触发最近消息修改的回调。

NIMDeleteMessageOption 中可配置 removeFromDB。默认为 NO。若设置为YES,则为标记删除,即SDK将记录此条消息的删除记录,即使从云端再次同步到该消息,也无法再从数据库里查询出来。

删除指定会话内消息

@protocol NIMConversationManager <NSObject>
/**
 *  删除某个会话的所有消息
 *
 *  @param session 待删除会话
 *  @param option 删除消息选项
 */
- (void)deleteAllmessagesInSession:(NIMSession *)session
                            option:(nullable NIMDeleteMessagesOption *)option;
@end

NIMDeleteMessagesOption 参数列表

参数 类型 说明
removeSession BOOL 是否移除对应最近会话,批量删除消息时是否移除最近会话,默认为 NO,设置为 YES 时将同时删除最近会话信息
removeTable BOOL 是否删除消息表,默认情况下云信采用标记的方式进行消息删除,如果设置为 YES,将一并移除对应的消息表,进而减少消息表数量,加快 I/O。默认为NO,为标记删除。当删除后又从云端将该消息拉取下来并设置同步到数据库后,此时,该条消息依旧无法查询到。

若想指定删除某一时间段内的消息,请使用以下接口:

@protocol NIMConversationManager <NSObject>
/**
 *  删除指定范围内的消息,如指定时间范围
 *
 *  @param session 目标会话
 *  @param option 删除消息选项
 */
- (void)deleteMessagesInSession:(NIMSession *)session 
                         option:(nullable NIMBatchDeleteMessagesOption *)option 
                     completion:(nullable NIMBatchDeleteMessagesBlock)block;
@end

NIMBatchDeleteMessagesOption 参数列表

参数 类型 说明
start NSTimeInterval 起始时间,默认 0,单位s。小于等于0表示之前全部消息。
end NSTimeInterval 截止时间, 默认 0, 单位s。小于等于0表示当前时间

删除所有消息

@protocol NIMConversationManager <NSObject>
/**
 *  删除所有会话消息
 *
 *  @param option 删除消息选项
 *  @discussion 调用这个接口只会触发allMessagesDeleted这个回调,其他针对单个recentSession的回调都不会被调用
 */
- (void)deleteAllMessages:(NIMDeleteMessagesOption *)option
@end

云端历史消息

云端历史消息查询

@protocol NIMConversationManager <NSObject>
/**
 *  从服务器上获取一个会话里某条消息之前的若干条的消息
 *
 *  @param session 消息所属的会话
 *  @param option  搜索选项
 *  @param result  读取的消息列表结果
 *  @discussion    此接口不支持查询聊天室消息,聊天室请参考 NIMChatroomManagerProtocol 中的查询消息接口。
 *
 */
- (void)fetchMessageHistory:(NIMSession *)session
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(nullable NIMFetchMessageHistoryBlock)result;
@end

其中 option 为搜索选项,具体选项如下:

参数 类型 说明
startTime NSTimeInterval 需要检索的起始时间,没有则传入0。
endTime NSTimeInterval 结束时间(默认为0,表示当前时间) 。结束时间需要大于起始时间。此参数对聊天室会话无效。
limit NSUInteger 检索条数,上限为 100 条
order NIMMessageSearchOrder 查询方向,NIMMessageSearchOrderDesc表示从新消息往旧消息查(并且查询结果按照新消息到旧消息的顺序排列),设置为NIMMessageSearchOrderAsc表示从旧消息往新消息查(并且查询结果按照旧消息到新消息的顺序排列)。此参数对聊天室会话无效
currentMessage NIMMessage 作为查询起点的消息(查询结果不会包含该消息)。如果order为NIMMessageSearchOrderDesc,那么设置currentMessage的同时必须设置endTime为该消息对应的timestamp属性。如果order为NIMMessageSearchOrderAsc,那么设置currentMessage的同时必须设置startTime为该消息对应的timestamp属性。 此参数对聊天室会话无效。
sync BOOL 是否在远程获取消息成功之后同步到本地数据库,同步只会保证消息数据写入本地但不触发回调。默认不同步,此参数对聊天室会话无效。
messageTypes NSArray \* 消息类型组合,默认为 nil ,搜索全类型。一旦设置了这个字段,则 sync 字段失效,查询结果不会写入 db。

删除云端历史消息

删除单会话云端历史消息

@protocol NIMConversationManager <NSObject>

/**
 *  清空点对点会话的服务端的消息。不会删除本地的消息记录。
 *
 *  @param session 目标会话
 *  @param option 清空消息选项
 *  @param completion 完成回调
 *  @discussion 只支持点对点,清空本用户服务端消息,不影响对方;如果不设置清空选项,服务端默认会同时清空漫游消息;
 */
- (void)deleteSelfRemoteSession:(NIMSession *)session
                         option:(nullable NIMClearMessagesOption *)option
                     completion:(nullable NIMRemoveRemoteSessionBlock)completion;              
@end

属性列表

参数 类型 说明
sessions NIMSession 会话
option NIMClearMessagesOption 可选择是否同时清空服务端漫游消息,nil时默认删除
completion NIMRemoveRemoteSessionBlock 远端会话删除错误回调

删除单条云端历史消息

@protocol NIMConversationManager <NSObject>

/**
 *  删除本地某条消息,并同时删除服务端历史、漫游
 *
 *  @param message 待删除的聊天消息
 *  @param ext 扩展字段
 *  @param completion 完成回调
 */
- (void)deleteMessageFromServer:(NIMMessage *)message 
                            ext:(nullable NSString *)ext 
                     completion:(nullable NIMRemoveRemoteMessageBlock)block         
@end

消息检索

SDK当前支持消息检索。

本地消息检索

根据会话检索

@protocol NIMConversationManager <NSObject>
/**
 *  搜索本地会话内消息
 *
 *  @param session 消息所属的会话
 *  @param option  搜索选项
 *  @param result  读取的消息列表结果
 *
 */
- (void)searchMessages:(NIMSession *)session
                option:(NIMMessageSearchOption *)option
                result:(nullable NIMSearchMessageBlock)result;
@end

其中 option 为搜索选项,具体选项如下:

参数 类型 说明
startTime NSTimeInterval 起始时间,默认为0
endTime NSTimeInterval 结束时间。默认为0,表示最大时间戳。若自行设置,要保证endTime晚于startTime。
limit NSUInteger 检索条数,默认100条,设置为0表示无条数限制
order NIMMessageSearchOrder 查询方向,默认为NIMMessageSearchOrderDesc表示从新消息往旧消息查,设置为NIMMessageSearchOrderAsc表示从旧消息往新消息查。无论查询方向如何,查询结果都按照旧消息到新消息的顺序排列。
messageTypes NSArray 消息类型组合,默认只搜索文本类型, 只有在 allMessageTypes 为 NO 时有效
messageSubTypes NSArray<NSNumber> 查询的消息子类型组合
allMessageTypes BOOL 搜索全部消息类型。默认为 NO,当设置为 YES 时,忽略 messageType 和 searchContent,同时返回所有的消息类型消息。
searchContent NSString 检索文本,如果需要搜索的消息类型为文本,会进行内容的匹配
fromIds NSArray 消息发起者列表
enableContentTransfer BOOL 将搜索文本中的正则特殊字符转义,默认 YES

搜索将返回:时间在 (startTime,endTime) 之间,消息类型为指定类型,且匹配搜索内容或消息发起者列表的一定数量的消息。

根据关键词搜索最新 100 条消息的内容示例:

NIMMessageSearchOption *option = [[NIMMessageSearchOption alloc] init];
option.searchContent = @"keyWord";
option.fromIds       = uids;
option.limit         = 100;
option.allMessageTypes = YES;

[[NIMSDK sharedSDK].conversationManager searchMessages:session option:option result:^(NSError * _Nullable error, NSArray<NIMMessage *> * _Nullable messages) {
    // do something with messages
}];

本地全局检索

@protocol NIMConversationManager <NSObject>
/**
 *  全局搜索本地消息
 *
 *  @param option 搜索选项
 *  @param result 读取的消息内容
 */
- (void)searchAllMessages:(NIMMessageSearchOption *)option
                result:(NIMGlobalSearchMessageBlock)result
@end

其中 option 为搜索选项,具体选项如下:

参数 类型 说明
startTime NSTimeInterval 起始时间,默认为0
endTime NSTimeInterval 结束时间。默认为0,表示最大时间戳。若自行设置,要保证endTime晚于startTime。
limit NSUInteger 检索条数,默认100条,设置为0表示无条数限制
order NIMMessageSearchOrder 查询方向,默认为NIMMessageSearchOrderDesc表示从新消息往旧消息查,设置为NIMMessageSearchOrderAsc表示从旧消息往新消息查。无论查询方向如何,查询结果都按照旧消息到新消息的顺序排列。
messageTypes NSArray 消息类型组合,默认只搜索文本类型, 只有在 allMessageTypes 为 NO 时有效
messageSubTypes NSArray<NSNumber> 查询的消息子类型组合
allMessageTypes BOOL 搜索全部消息类型。默认为 NO,当设置为 YES 时,忽略 messageType 和 searchContent,同时返回所有的消息类型消息。
searchContent NSString 检索文本,如果需要搜索的消息类型为文本,会进行内容的匹配
fromIds NSArray 消息发起者列表
enableContentTransfer BOOL 将搜索文本中的正则特殊字符转义,默认 YES

搜索将返回:时间在 (startTime,endTime) 之间,消息类型为指定类型,且匹配搜索内容或消息发起者列表的一定数量的消息。

搜索全局的图片和视频的最新 100 条消息示例:

NIMMessageSearchOption *option = [[NIMMessageSearchOption alloc] init];
option.limit = 100;

[[NIMSDK sharedSDK].conversationManager searchAllMessages:option result:^(NSError * _Nullable error, NSDictionary<NIMSession *,NSArray<NIMMessage *> *> * _Nullable messages) { }];

云端消息关键字检索

根据关键字查询服务端历史消息的文本内容,可另外通过指定设置起、止时间完成分页等功能;支持点对点、群(暂不支持超大群);

/**
 *  会话管理器
 */
@protocol NIMConversationManager <NSObject>
    /**
     *  根据关键字从服务器上检索消息
     *
     *  @param session 消息所属的会话
     *  @param option  检索选项
     *  @param result  读取的消息列表结果
     *  @discussion    检索消息内容,大小写不敏感;此接口不支持查询聊天室消息,聊天室请参考 NIMChatroomManagerProtocol 中的消息接口。
     *
     */
    - (void)retrieveServerMessages:(NIMSession *)session
                            option:(NIMMessageServerRetrieveOption *)option
                            result:(nullable NIMRetrieveServerMessagesBlock)result;
@end

属性列表

参数 类型 说明
session NIMSession 表示的当前会话
option NIMMessageServerRetrieveOption 检索选项
result NIMRetrieveServerMessagesBlock 结果回调

示例

    NSString * keyword = searchBar.text;
    NIMMessageServerRetrieveOption * option = [[NIMMessageServerRetrieveOption alloc] init];
    option.keyword = keyword;
    [[NIMSDK sharedSDK].conversationManager retrieveServerMessages:self.session
                                                            option:option
                                                            result:^(NSError * _Nullable error,
                                                                     NSArray<NIMMessage *> * _Nullable messages)
    {
     ...
    }];