IM即时通讯 > SDK开发集成 > Linux开发集成 > 最近会话

最近会话

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

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

SessionData重要参数说明：

参数类型 字段 说明
string kNIMSessionId 最近联系人的 ID（好友帐号，群 ID 等）
int kNIMSessionType 会话的类型（群会话、点对点消息）,详见NIMSessionType
int kNIMSessionUnreadCount 当前会话的消息未读数
int kNIMSessionCommand 当前会话的修改操作类型（增加、更新、删除等，详见NIMSessionCommand）
string kNIMSessionMsgClientID 当前会话的最新一条消息的唯一Id
string kNIMSessionMsgFromAccount 当前会话最新一条消息发送方的ID
int64_t kNIMSessionMsgTime 当前会话最新一条消息时间戳（毫秒）
int kNIMSessionMsgType 最近一条消息的消息类型 （如文本、图片、视频、语音消息等等 详见NIMMessageType）
string kNIMSessionMsgBody 当前会话最近一条消息内容
string kNIMSessionMsgAttach 当前会话最近一条消息的附件内容
int kNIMSessionMsgStatus 当前会话最近一条消息状态（已读、未读等状态，详见消息状态）
int kNIMSessionMsgSubStatus 当前会话最近一条消息子状态（已播放、未播放等状态，详见消息子状态）
bool kNIMSessionLastUpdatedMsg 在批量消息通知时，消息变更或增加时是否是最后一条变更的信息
bool kNIMSessionOnTop 是否会话置顶（暂不支持）
bool kNIMSessionRobotFlag 是否是机器人消息（暂不支持）
string kNIMSessionExtendedData 本地扩展字段, 限4096（暂不支持）

NIMSessionType枚举值说明：

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

NIMSessionType枚举值说明：

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

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

获取最近会话列表

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

void nim_session_query_all_recent_session_async(const char *json_extension, nim_session_query_recent_session_cb_func cb, const void *user_data);
参数 说明
cb 通知查询结果的异步回调函数
user_data APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理
json_extension 预留字段 
void my_nim_session_query_recent_session_cb_func(int total_unread_count, const char *result, const char *json_extension, const void *user_data){
    Json::Value values;
    Json::Reader reader;
    if (reader.parse(result, values) && values.isObject())
    {
        int count = values[kNIMSessionListCount].asUInt();
        int unread_count = values[kNIMSessionListUnreadCount].asUInt();
        Json::Value sessions = values[kNIMSessionListContent];
        int len = sessions.size();
        for (int i = 0; i < len; i++)
        {
            //解析为 SessionData 字段数据;
            ...
        }
    }
    ...
}
//调用c接口
nim_session_query_all_recent_session_async（null,my_nim_session_query_recent_session_cb_func,null);

监听最近会话变更

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

void nim_session_reg_change_cb(const char *json_extension, nim_session_change_cb_func cb, const void *user_data);

回调nim_session_change_cb_func返回参数说明：

类型 参数 说明
int rescode 错误码（详见NIMResCode）
string result 会话信息，详见SessionData
int total_unread_counts 所有会话的未读数计数总和
void* user_data APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理 
void my_nim_session_change_cb_func(int rescode, const char *result, int total_unread_counts, const char *json_extension, const void *user_data)
{
    Json::Value values;
    Json::Reader reader;
    if (reader.parse(result, values) && values.isObject())
    {
        //解析为 SessionData 字段数据;
        ...
    }
    ...
}
//监听事件通知
nim_session_reg_change_cb(0,my_nim_session_change_cb_func,0);

//如果不再需要，则注销事件监听
nim_session_reg_change_cb(0,0,0);

未读数清零

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

void nim_session_set_unread_count_zero_async(enum NIMSessionType to_type, const char *id, const char *json_extension, nim_session_change_cb_func cb, const void *user_data);
参数 说明
to_type 会话类型,详见NIMSessionType
id 会话id(对方账号或者群id)
cb 异步通知回调函数
json_extension 预留扩展字段
user_data APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理 
void my_nim_session_change_cb_func(int rescode, const char *result, int total_unread_counts, const char *json_extension, const void *user_data)
{
    ...
}

void nim_msglog_res_ex_cb_func(int res_code, const char *uid, enum NIMSessionType type, const char *json_extension, const void *user_data)
{
    ...
}
//指定需要设置已读的会话类型和会话id;
NIMSessionType sessionType = kNIMSessionTypeP2P;
char* sessionId = "test1";

//设置会话未读计数清零
nim_session_set_unread_count_zero_async(sessionType, sessionId, 0,my_nim_session_change_cb_func,0);

//最新版本已经不再需要调用nim_msglog_batch_status_read_async接口
//老版本还需要以下这么调用
nim_msglog_batch_status_read_async(sessionId, sessionType, 0,nim_msglog_res_ex_cb_func,0);

删除指定最近联系人

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

void nim_session_delete_recent_session_async(enum NIMSessionType to_type, const char *id, const char *json_extension, nim_session_change_cb_func cb, const void *user_data);
参数 说明
to_type 会话类型
id 最近联系人的 ID（好友帐号，群 ID 等）
cb 当前操作的回调函数
json_extension 预留扩展字段
user_data APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理 
void my_nim_session_change_cb_func(int rescode, const char *result, int total_unread_counts, const char *json_extension, const void *user_data)
{
    ...
}


NIMSessionType toType = kNIMSessionTypeP2P; //个人类型
char* id = "test_account";//会话id
nim_session_delete_recent_session_async(toType, id,0, my_nim_session_change_cb_func,0);

删除全部最近联系人

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

void nim_session_query_all_recent_session_async(const char *json_extension, nim_session_query_recent_session_cb_func cb, const void *user_data);
参数 说明
cb 当前操作的回调函数
json_extension 预留扩展字段
user_data APP的自定义用户数据，SDK只负责传回给回调函数cb，不做任何处理 
void my_nim_session_change_cb_func(int rescode, const char *result, int total_unread_counts, const char *json_extension, const void *user_data)
{
    ...
}

nim_session_query_all_recent_session_async(0,my_nim_session_change_cb_func,0);

相关文档

相关产品