最近会话

最近会话列表由 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.

获取最近会话列表

• API 介绍

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

• API 原型

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_)
    {
        ...
    }
});

监听最近会话变更

• API 介绍

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

• API 原型

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);

未读数清零

• API 介绍

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

• API 原型

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)
{
    ···
});

删除指定最近联系人

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

• API 原型

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)
{
    ...
});

删除全部最近联系人

• API 介绍

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

• API 原型

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)
{
    ...
});