最近会话

最近会话列表由 SDK 维护并提供查询、监听变化的接口,只要与某个用户或者群组有产生聊天(自己发送消息或者收到消息), SDK 会自动更新最近会话列表并通知上层,开发者无需手动更新。

最近会话 SessionData ,也可称作会话列表或者最近联系人列表,它记录了与用户最近有过会话的联系人信息,包括联系人帐号、联系人类型、最近一条消息的时间、消息状态、消息内容、未读条数等信息。

SessionData重要参数说明:

参数类型 SessionInfo 字段 说明
String id_ 最近联系人的 ID(好友帐号,群 ID 等)
NIMSessionType type_ 会话的类型(群会话、点对点消息)
int unread_count_ 当前会话的消息未读数
NIMSessionCommand command_ 当前会话的修改操作类型(增加、更新、删除等,详见NIMSessionCommand
string msg_id_ 当前会话的最新一条消息的唯一Id
string msg_sender_accid_ 当前会话最新一条消息发送方的ID
int64_t msg_timetag_ 当前会话最新一条消息时间戳(毫秒)
NIMMessageType msg_type_ 最近一条消息的消息类型 (如文本、图片、视频、语音消息等等 详见NIMMessageType
string msg_content_ 当前会话最近一条消息内容
string msg_attach_ 当前会话最近一条消息的附件内容
NIMMsgLogStatus msg_status_ 当前会话最近一条消息状态(已读、未读等状态,详见消息状态
NIMMsgLogSubStatus msg_sub_status_ 当前会话最近一条消息子状态(已播放、未播放等状态,详见消息子状态
bool last_updated_msg_ 在批量消息通知时,消息变更或增加时是否是最后一条变更的信息
bool placed_on_top_ 是否会话置顶(暂不支持)
bool is_robot_session_ 是否是机器人消息(暂不支持)
string extend_data_ 本地扩展字段, 限4096(暂不支持)

NIMSessionType枚举值说明:

枚举 说明
kNIMSessionTypeP2P 0 个人,即点对点会话
kNIMSessionTypeTeam 1 群组会话

NIMSessionCommand枚举值说明:

枚举 说明
kNIMSessionCommandAdd 0 添加会话项
kNIMSessionCommandRemove 1 删除单个会话项
kNIMSessionCommandRemoveAll 2 删除所有会话项
kNIMSessionCommandRemoveAllP2P 3 删除所有点对点的会话项
kNIMSessionCommandRemoveAllTeam 4 删除所有群的会话项
kNIMSessionCommandMsgDeleted 5 单个会话项的消息已删除
kNIMSessionCommandAllMsgDeleted 6 所有会话项的消息已删除
kNIMSessionCommandAllP2PMsgDeleted 7 所有点对点会话项的消息已删除
kNIMSessionCommandAllTeamMsgDeleted 8 所有群会话项的消息已删除
kNIMSessionCommandUpdate 9 更新会话项

注意:最近会话是本地的,不会漫游。漫游与消息相关,与最近会话无关。多端同时登录时,最新版本调用设置会话清零接口时会同步其他端的同一个会话为0.

获取最近会话列表

获取最近的会话列表数据。

static void QueryAllRecentSessionAsync(const QuerySessionListCallabck& cb, const std::string& json_extension = "");
参数 说明
cb 通知查询结果的异步回调函数
json_extension 预留字段
nim::Session::QueryAllRecentSessionAsync((([&](int total_unread_count, const SessionDataList& sessions)
{
    for (auto session : sessions.sessions_)
    {
        ...
    }
});

监听最近会话变更

在收发消息的同时,SDK 会更新对应聊天对象的最近联系人资料。当有消息收发时,SDK 会发出最近联系人更新通知,通过注册该事件来监听会话项变化。

static void RegChangeCb(const ChangeCallback& cb, const std::string& json_extension = "");

回调ChangeCallback返回参数说明:

类型 参数 说明
NIMResCode code 错误码(详见NIMResCode
SessionData session 会话信息,详见SessionData
int total_unread_counts 所有会话的未读数计数总和

//监听事件通知
nim::Session::RegChangeCb([&](NIMResCode code, const SessionData& session, int total_unread_counts)
{
    ...
});

//如果不再需要,则注销事件监听
nim::Session::RegChangeCb(nullptr);

未读数清零

如果需要将当前会话的未读数清零,则需要调用SetUnreadCountZero接口来设置,在较老的版本中,在调用SetUnreadCountZero接口之后还需要调用 MarkMessagesStatusRead接口来设置消息数据库的已读状态。

static bool SetUnreadCountZeroAsync(nim::NIMSessionType to_type, const std::string& id, const SetUnreadCountZeroCallback& cb, const std::string& json_extension = "");
参数 说明
to_type 会话类型,详见NIMSessionType
id 会话id(对方账号或者群id)
cb 异步通知回调
json_extension 预留扩展字段
//指定需要设置已读的会话类型和会话id;

NIMSessionType sessionType = kNIMSessionTypeP2P;
std:string sessionId = "test1";

//设置会话未读计数清零
nim::Session::SetUnreadCountZeroAsync(sessionType, sessionId, [&](NIMResCode code, const SessionData& session, int total_unread_counts)
{
    ...
});

//最新版本已经不再需要调用nim::Msglog::BatchStatusReadAsync接口
//老版本还需要以下这么调用
nim::Msglog::BatchStatusReadAsync(sessionId, sessionType, [&]((nim::NIMResCode res_code, const std::string& uid, nim::NIMSessionType to_type)
{
    ···
});

删除指定最近联系人

删除会话项时本地和服务器会同步删除

static bool DeleteRecentSession(nim::NIMSessionType to_type, const std::string& id, const DeleteRecentSessionCallabck& cb, const std::string& json_extension = "");
参数 说明
to_type 会话类型
id 最近联系人的 ID(好友帐号,群 ID 等)
cb 当前操作的回调函数
json_extension 预留扩展字段
NIMSessionType toType = kNIMSessionTypeP2P; //个人类型
std::string id = "test_account";//会话id
nim::Session::DeleteRecentSession(toType, id, [&](NIMResCode code, const SessionData& session, int total_unread_counts)
{
    ...
});

删除全部最近联系人

删除所有会话列表项,但是不会将消息数据库设置为已读状态,如果同时需要更新消息数据库的已读状态,请使用删除所有历史记录接口

static void DeleteAllRecentSession(const DeleteAllRecentSessionCallabck& cb, const std::string& json_extension = "");
参数 说明
cb 当前操作的回调函数
json_extension 预留扩展字段

nim::Session::DeleteAllRecentSession([&](NIMResCode code, const SessionData& session, int total_unread_counts)
{
    ...
});