本地最近会话
功能概述
最近会话列表，即最近联系人列表。当收到新联系人的消息时，SDK会自动生成这个消息对应的本地最近会话。它记录了包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。
原型是RecentContact，接口说明如下：
| 返回值 | RecentContact 接口 | 说明 |
|---|---|---|
| MsgAttachment | getAttachment() | 获取最近一条消息的附件内容 |
| String | getContactId() | 获取最近联系人的 ID（好友帐号，群 ID 等） |
| String | getContent() | 获取最近一条消息的缩略内容 |
| Map | getExtension() | 获取最近会话对象的扩展字段 |
| String | getFromAccount() | 获取最近一条消息的发送方的帐号 |
| String | getFromNick() | 获取与该联系人的最近一条消息的发送方的昵称 |
| MsgStatusEnum | getMsgStatus() | 获取最近一条消息状态 |
| MsgTypeEnum | getMsgType() | 获取最近一条消息的消息类型 |
| String | getRecentMessageId() | 获取最近一条消息的客户端ID， 即 IMMessage#getUuid() |
| SessionTypeEnum | getSessionType() | 获取会话类型，是单聊还是群聊等 |
| long | getTag() | 获取标签属性 |
| long | getTime() | 获取最近一条消息的时间，单位为 ms |
| int | getUnreadCount() | 获取未读消息条数 |
| void | setExtension(Map extension) | 设置最近会话对象的扩展字段 |
| void | setMsgStatus(MsgStatusEnum msgStatus) | 设置最近一条消息的状态 |
| void | setTag(long tag) | 设置一个标签，用于做联系人置顶、最近会话列表排序等扩展用途。 |
获取最近会话
获取最近会话列表，一般用于首页显示会话列表
获取最近会话列表
- 异步接口：
/**
* 查询最近联系人列表数据
*
* @return InvocationFuture
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts();- 同步接口：
/**
* 查询最近联系人列表数据(同步接口)
*
* @return InvocationFuture
*/
public List<RecentContact> queryRecentContactsBlock();- 示例
NIMClient.getService(MsgService.class).queryRecentContacts()
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
// recents参数即为最近联系人列表（最近会话列表）
}
});获取最近会话列表(自定义)
过滤指定消息类型
当希望返回的会话的最近一条消息不是某一类消息时，可以使用以下过滤接口。
如希望最近一条消息为非文本消息时，使用该接口的返回的会话，将取最近的一条非文本的消息作为最近一条消息。
- 异步接口：
/**
* 查询最近联系人列表数据
*
* @return InvocationFuture
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts(MsgTypeEnum filterMsgType);- 同步接口：
/**
* 查询最近联系人列表数据, 过滤指定消息类型(同步接口)
*
* @return InvocationFuture
*/
public List<RecentContact> queryRecentContactsBlock(MsgTypeEnum filterMsgType);- 示例
NIMClient.getService(MsgService.class).queryRecentContacts(MsgTypeEnum.text)
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
// recents参数即为最近联系人列表（最近会话列表）
}
});获取少量会话
可以获取指定数量的最近会话：
- 异步接口
/**
* 查询最近联系人会话列表数据, 可以设置limit， 防止本地会话过多时，导致第一次加载慢
*
* @param limit 获取本地会话的数量，最大100，超过100修正到100
* @return InvocationFuture
*/
InvocationFuture<List<RecentContact>> queryRecentContacts(int limit);- 同步接口
/**
* 查询最近联系人会话列表数据(同步接口)，可以设置limit， 防止本地会话过多时，导致第一次加载慢
*
* @param limit 获取本地会话的数量，最大100，超过100修正到100
*/
List<RecentContact> queryRecentContactsBlock(int limit);- 示例
NIMClient.getService(MsgService.class).queryRecentContacts(10);获取指定的最近会话
v5.9.0版本开始，支持通过会话id获取对应的会话。
/**
* 查询最近联系人会话列表数据(同步接口)，可以设置limit， 防止本地会话过多时，导致第一次加载慢
* @param contactId - 会话id ，对方帐号或群组id。
* @param sessionType - 会话类型。
*/
RecentContact queryRecentContact(java.lang.String contactId, SessionTypeEnum sessionType);创建最近会话
创建一个空的最近会话:
/**
* @param contactId - 会话id ，对方帐号或群组id。
* @param sessionType - 会话类型。
* @param tag - 会话tag ， eg:置顶标签（UIKit中的实现： RECENT_TAG_STICKY） ，用户参照自己的tag 实现即可， 如不需要，传 0 即可。
* @param time - 会话时间 ，单位为ms。
* @param saveToDB - 是否需要将会话保存在DB中，注意以下两点：
1，如果已经存在相同的会话（contactId 、sessionType 一样），则不会保存在db中；
2，如果之前不存在相同的会话，且needSaveToDB为true 会触发MsgServiceObserve.observeRecentContact(Observer, boolean)通知；
*/
RecentContact createEmptyRecentContact(java.lang.String contactId,
SessionTypeEnum sessionType,
long tag,
long time,
boolean saveToDB);此外，当某条消息无对应的本地最近会话时，可以使用以下接口根据消息创建本地最近会话。
/**
* @param message - 消息。
* @param needNotify - 是否需要触发MsgServiceObserve.observeRecentContact(Observer, boolean)的通知
*/
void updateRecentByMessage(IMMessage message, boolean needNotify);更新最近会话
更新最近会话
/**
* 更新一条最近联系人会话的属性。目前可设置的属性有：tag, extension。
* @param recent - 待更新的最近联系人会话数据
*/
void updateRecent(RecentContact recent);如果想收到 MsgServiceObserve.observeRecentContact(Observer, boolean) 的通知， 可使用以下接口进行更新：
/**
* 更新一条最近联系人会话的属性。目前可设置的属性有：tag, extension。
* @param recent - 待更新的最近联系人会话数据
*/
void updateRecentAndNotify(RecentContact recent);监听最近会话变更
当最近会话对象以及其属性发生变更时，SDK 会更新对应聊天对象的最近联系人资料，并发出最近联系人更新通知。
- API 原型
/**
* 注册/注销最近联系人列表变化观察者
* @param observer 观察者，参数为变化的最近联系人列表
* @param register true为注册，false为注销
*/
public void observeRecentContact(Observer<List<RecentContact>> observer, boolean register);- 示例
// 创建观察者对象
Observer<List<RecentContact>> messageObserver = new Observer<List<RecentContact>>() {
@Override
public void onEvent(List<RecentContact> messages) {
}
}
// 注册/注销观察者
NIMClient.getService(MsgServiceObserve.class).observeRecentContact(messageObserver, register);未读数
获取未读数
获取总未读数
/**
* 获取未读数总数
*/
public int getTotalUnreadCount();示例
int unreadNum = NIMClient.getService(MsgService.class).getTotalUnreadCount();获取单个会话未读数
通过 RecentContact - getUnreadCount() 方法获取。
重置未读数
调用以下接口重置当前会话，SDK会自动管理消息的未读数。该接口会自动调用clearUnreadCount(String, SessionTypeEnum)将正在聊天对象的未读数清零。如果有新消息到达，且消息来源是正在聊天的对象，其未读数也不会递增。
/**
* 设置当前会话
* @param account, - 聊天对象帐号，或者以下两个值：MSG_CHATTING_ACCOUNT_ALL与MSG_CHATTING_ACCOUNT_NONE。
* @param sessionType 会话类型。如果account不是具体的对象，该参数将被忽略
*/
void setChattingAccount(java.lang.String account, SessionTypeEnum sessionType);一般在退出聊天界面时，需要恢复更新未读数：
// 恢复更新未读数
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);如果需要不进入聊天窗口就将未读数清零，可以调用如下方法来实现：
// 清理指定会话的未读数
NIMClient.getService(MsgService.class).clearUnreadCount(account,sessionType);
// 将所有联系人的未读数清零
NIMClient.getService(MsgService.class).clearAllUnreadCount();未读数多端同步
开启会话的未读数多端同步后，在其中一个客户端读过的会话在其它端也会被标记为已读。
开启方法：设置 SDKOptions - sessionReadAck 属性为 true 。
删除最近会话
删除最近会话
SDK 支持删除指定的本地最近会话。但会保留会话内的消息。调用时，总未读消息数会减去当前会话的未读数。
- API 介绍
MsgService 提供了两种方法： deleteRecentContact 和 deleteRecentContact2，区别在于后者会触发 MsgServiceObserve#observeRecentContactDeleted 通知。
- API 原型
不触发观察者通知版本:
/**
* 从最近联系人列表中删除一项。
* 调用这个接口删除数据后，不会引发观察者通知。
*
* @param recent 待删除的最近联系人项
*/
public void deleteRecentContact(RecentContact recent);触发观察者通知版本:
/**
* 删除最近联系人记录。
* 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContactDeleted(Observer, boolean)}通知
*
* @param account
* @param sessionType
*/
public void deleteRecentContact2(String account, SessionTypeEnum sessionType);- 示例
// 不触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact(recent);
//触发观察者通知版本
NIMClient.getService(MsgService.class).deleteRecentContact2(account, SessionTypeEnum.P2P);删除漫游消息
SDK 支持删除指定联系人的漫游消息，可以通过以下方法实现：
- API 原型
/**
* 删除指定最近联系人的漫游消息。
* 不删除本地消息，但如果在其他端登录，当前时间点该会话已经产生的消息不漫游。
*
* @return InvocationFuture 可设置回调函数，监听删除结果。
*/
public InvocationFuture<Void> deleteRoamingRecentContact(String contactId, SessionTypeEnum sessionTypeEnum);- 参数说明
| 参数 | 说明 |
|---|---|
| contactId | 最近联系人的 ID（好友帐号，群 ID 等） |
| sessionTypeEnum | 会话类型 |
- 示例
NIMClient.getService(MsgService.class)
.deleteRoamingRecentContact(contactId, sessionTypeEnum)
.setCallback(new RequestCallback<Void>() { ... });