最近会话
最近会话列表由 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.
获取最近会话列表
- API 介绍
获取最近的会话列表数据。
- API 原型
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);
监听最近会话变更
- API 介绍
在收发消息的同时,SDK 会更新对应聊天对象的最近联系人资料。当有消息收发时,SDK 会发出最近联系人更新通知,通过注册该事件来监听会话项变化。
- API 原型
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);
未读数清零
- API 介绍
如果需要将当前会话的未读数清零,则需要调用nim_session_set_unread_count_zero_async
接口来设置,在较老的版本中,在调用nim_session_set_unread_count_zero_async
接口之后还需要调用 nim_msglog_batch_status_read_async
接口来设置消息数据库的已读状态。
- API 原型
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);
删除指定最近联系人
删除会话项时本地和服务器会同步删除
- API 原型
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);
删除全部最近联系人
- API 介绍
删除所有会话列表项,但是不会将消息数据库设置为已读状态,如果同时需要更新消息数据库的已读状态,请使用删除所有历史记录接口
- API 原型
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);
本篇文档内容是否对您有帮助?


此文档对你是否有帮助
×


×