本地最近会话

功能概述

最近会话列表,即最近联系人列表。当收到新联系人的消息时,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 会更新对应聊天对象的最近联系人资料,并发出最近联系人更新通知。

/**
 * 注册/注销最近联系人列表变化观察者
 * @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 支持删除指定的本地最近会话。但会保留会话内的消息。调用时,总未读消息数会减去当前会话的未读数。

MsgService 提供了两种方法: deleteRecentContact 和 deleteRecentContact2,区别在于后者会触发 MsgServiceObserve#observeRecentContactDeleted 通知。

不触发观察者通知版本:

/**
 * 从最近联系人列表中删除一项。
 * 调用这个接口删除数据后,不会引发观察者通知。
 *
 * @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 支持删除指定联系人的漫游消息,可以通过以下方法实现:

/**
 * 删除指定最近联系人的漫游消息。
 * 不删除本地消息,但如果在其他端登录,当前时间点该会话已经产生的消息不漫游。
 *
 * @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>() { ... });