历史记录

本地记录

提供了比较完善的消息记录管理功能,开发者可本地查阅、在线查阅、删除和清空聊天记录,还可以写入消息记录,导入/导出历史消息(仅能导入当前用户的记录)。此外,还要注意:本地消息历史操作(如删除)及状态变化(如发送失败或成功)会与会话列表里的消息状态自动同步,App 上层需要根据监听会话列表通知回调进行相应通知事件的处理。

全局消息状态变更通知

注册全局的消息状态变更通知(目前只支持已读状态的通知)。当收到对方的消息已读回执时,会通过此注册的回调通知给调用者。

static void RegMessageStatusChangedCb(const MessageStatusChangedCallback& cb, const std::string &json_extension = "");
//注册全局的消息状态变更通知
nim::MsgLog::RegMessageStatusChangedCb([&](const MessageStatusChangedResult& result)
{
    ...
});

查询消息历史

SDK 提供了一个根据锚点查询本地消息历史记录的接口,结果使用 time 作为排序字段(按时间逆序起查,逆序排列)。支持在扩展字段对查询更早或者更晚消息的控制。

static bool QueryMsgAsync(const std::string& account_id, nim::NIMSessionType to_type, int limit_count, int64_t anchor_msg_time, const QueryMsgCallback& cb, const std::string& json_extension = "");
参数 说明
account_id 会话id,对方的account id或者群组tid
to_type 会话类型
limit_count 一次查询数量,建议20
anchor_msg_time 上次查询最后一条消息的时间戳(按时间逆序起查,即最小的时间戳)
cb 查询结果回调通知
json_extension 扩展字段,仅支持查询更早或更晚的消息,如{"direction":0},0:查询比锚点时间更早的消息,1:查询比锚点时间更晚的消息

Direction 属性说明:

枚举 说明
kForward 0 查询比锚点时间更早的消息
kBackward 1 查询比锚点时间更晚的消息
//测试账号test1
std::string session_id = "test1";
nim::MsgLog::QueryMsgAsync(session_id, kNIMSessionTypeP2P, 20, 0, [&](NIMResCode res_code, const std::string& id, NIMSessionType to_type, const nim::QueryMsglogResult & result)
{
    if (res_code == kNIMResSuccess){
        ···
    }
});


//控制查询方向,查询更早或者更晚的消息
Json::Value values;
values["direction"] = 1;
nim::MsgLog::QueryMsgAsync(session_id, kNIMSessionTypeP2P, 20, 1519977874123, [&](NIMResCode res_code, const std::string& id, NIMSessionType to_type, const nim::QueryMsglogResult & result)
{
    if (res_code == kNIMResSuccess){
        ···
    }
},GetJsonStringWithNoStyled(values));

根据消息 uuid 查询消息

static bool QueryMsgByIDAysnc(const std::string &client_msg_id, const QuerySingleMsgCallback &cb, const std::string &json_extension = "");
参数 说明
client_msg_id 所查询的消息id
cb 查询结果回调通知
json_extension 扩展字段,预留
string clientMsgId="msg_id";//以实际的消息id为准
nim::MsgLog::QueryMsgByIDAysnc(clientMsgId, [&](NIMResCode ret, const std::string& id, const nim::IMMessage& msg) 
{
    ...
});

根据指定条件查询本地消息

根据指定条件查询本地消息,使用此接口可以完成全局搜索等功能,具体请参阅开发手册。暂时仅支持单个id的查询,即ids只能添加一个,不支持多个uid。searchContent参数不能为空。

static bool QueryMsgByOptionsAsync(NIMMsgLogQueryRange query_range, const std::list<std::string>& ids, int limit_count, int64_t from_time, int64_t end_time, const std::string& end_client_msg_id, bool reverse, NIMMessageType msg_type, const std::string& search_content, const QueryMsgCallback& cb, const std::string& json_extension = "");
参数 说明
query_range 消息历史的检索范围
ids 会话id,对方的account id的集合或者群组tid的集合,目前仅支持单个id的查询
limit_count 搜索结果的条数限制
from_time 起始时间戳,单位:毫秒
end_time 结束时间戳,单位:毫秒
end_client_msg_id 结束查询的最后一条消息的client_msg_id(不包含在查询结果中)(暂不启用)
reverse true:反向查询(按时间正序起查,正序排列),false:按时间逆序起查,逆序排列(建议默认为false)
msg_type 检索的消息类型(目前只支持kNIMMessageTypeText、kNIMMessageTypeImage和kNIMMessageTypeFile这三种类型消息)
search_content 检索文本(目前只支持kNIMMessageTypeText和kNIMMessageTypeFile这两种类型消息的文本关键字检索,即支持文字消息和文件名的检索。如果合并检索,需使用未知类型消息kNIMMessageTypeUnknown
cb 查询结果回调
json_extension 扩展字段,预留

NIMMsgLogQueryRange枚举类型

枚举 说明
kNIMMsgLogQueryRangeP2P 0 指定的个人(点对点会话)(注意:暂不支持指定多个人的检索!)
kNIMMsgLogQueryRangeTeam 1 指定的群组(注意:暂不支持指定多个群组的检索!)
kNIMMsgLogQueryRangeAll 100 全部
kNIMMsgLogQueryRangeAllP2P 101 所有个人会话
kNIMMsgLogQueryRangeAllTeam 102 所有群组
kNIMMsgLogQueryRangeUnknown 200 不支持查询
//以P2P消息为例
std::list<std::string> ids;
ids.push_back("testAccount");
int64_t sTimetag = 1519977874123;//13位时间戳毫秒
int64_t eTimetag = 1519978139567;13位时间戳毫秒,需要比sTimetag更晚,即eTimetag > sTimetag
std::string endMsgId = "lastmsgid";//对应eTimetag时间点的消息id
nim::MsgLog::QueryMsglogByCustomCondition(kNIMMsgLogQueryRangeP2P, ids, 20,
            sTimetag, eTimetag, endMsgId, false, kNIMMessageTypeText, "111", [&](nim::NIMResCode res_code, const std::string& id, nim::NIMSessionType to_type, const nim::QueryMsglogResult& result)
{
    if (res_code == kNIMResSuccess){
        ···
    }
})

插入本地消息

保存消息到本地数据库,如果已存在这条消息,则更新,但不发送到服务器端。需要保证整条消息内容是符合消息收发的规范。

static bool WriteMsglogToLocalAsync(const std::string& talk_id, const IMMessage& msg, bool need_update_session, const WriteMsglogCallback& cb, const std::string& json_extension = "");
参数 说明
talk_id 会话id,对方的account id或者群组tid
need_update_session 是否更新会话列表(一般最新一条消息会有更新的需求)
msg 消息体,详见IMMessage
cb 操作结果的回调函数
json_extension 扩展字段,预留
// 创建一条文本消息,以对方账号testAccount为例

nim::IMMessage msg;
msg.receiver_accid_ = "testAccount";对方账号
msg.sender_accid_ = "myUid";//发送者账号
msg.client_msg_id_ = "uuid";//该条消息唯一id
msg.session_type_ = kNIMSessionTypeP2P;
msg.type_ = kNIMMessageTypeText;
msg.local_talk_id_="testAccount";对方账号
msg.timetag_=1519977874123;//13位时间戳毫秒
msg.status_=kNIMMsgLogStatusDraft;//可设置其他消息状态
msg.content_ = "111";

...
// 保存消息到本地数据库,但不发送到服务器
nim::MsgLog::WriteMsglogToLocalAsync("testAccount", msg, true,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
    ...
});

删除历史消息

可以删除指定msgid的消息,也可以批量删除消息。

1. 删除指定的一条消息

通过指定对方account或者群id,msgId来删除历史消息

static bool DeleteAsync(const std::string& session_id, NIMSessionType to_type, const std::string& msg_id, const DeleteCallback& cb, const std::string& json_extension = "");
参数 说明
session_id 对方account或者群id
to_type 当前会话的类型,指定枚举类型NIMSessionType
msg_id 指定要删除的消息唯一id
cb 操作结果回调通知
json_extension 扩展字段,预留
//以p2p消息为例,测试账号testAccount
nim::MsgLog::DeleteAsync("testAccout",kNIMSessionTypeP2P,"client_msgid",[&](nim::NIMResCode res_code, const std::string& msg_id)
{
    ...
});

2. 删除指定会话类型的所有消息

通知指定to_type批量删除数据库中的历史记录,只操作本地数据库,不同步服务器。

static bool DeleteBySessionTypeAsync(bool delete_sessions, NIMSessionType to_type, const DeleteBySessionTypeCallback& cb, const std::string& json_extension = "");
参数 说明
to_type 当前会话的类型,指定枚举类型NIMSessionType
delete_sessions 是否要同步删除会话列表项,true:删除,false:不删除,仅标记消息状态为已删除
cb 操作结果回调通知
json_extension 扩展字段,预留
// 批量删除点对点消息记录
nim::MsgLog::DeleteBySessionTypeAsync(true,kNIMSessionTypeP2P,[&](nim::NIMResCode res_code, const std::string& uid, nim::NIMSessionType to_type)
{
    ...
});

3. 删除所有历史记录

删除全部本地的历史消息,并可以选择同步删除会话列表项。

static bool DeleteAllAsync(bool delete_sessions, const DeleteAllCallback& cb, const std::string& json_extension = "");
参数 说明
delete_sessions 是否要同步删除会话列表项,true:删除,false:不删除,仅标记消息状态为已删除
cb 操作结果回调通知
json_extension 扩展字段,预留
// 批量删除点对点消息记录
nim::MsgLog::DeleteAllAsync(kNIMSessionTypeP2P,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
    ...
});

修改消息状态

SDK 提供了修改消息为草稿等状态,也可以修改语音消息等的已播放和未播放的子状态

NIMMsgLogStatus消息状态

枚举 说明
kNIMMsgLogStatusNone 0 默认,不能当查询条件,意义太多
kNIMMsgLogStatusUnread 1 收到消息,未读
kNIMMsgLogStatusRead 2 收到消息,已读
kNIMMsgLogStatusDeleted 3 消息已删
kNIMMsgLogStatusSending 4 消息发送中
kNIMMsgLogStatusSendFailed 5 发送失败
kNIMMsgLogStatusSent 6 已发送
kNIMMsgLogStatusReceipt 7 对方已读发送的内容
kNIMMsgLogStatusDraft 8 草稿
kNIMMsgLogStatusSendCancel 9 发送取消
kNIMMsgLogStatusRefused 10 被对方拒绝,比如被对方加入黑名单等等

NIMMsgLogSubStatus消息子状态

枚举 说明
kNIMMsgLogSubStatusNone 0 默认
kNIMMsgLogSubStatusNotPlaying 1 未播放
kNIMMsgLogSubStatusPlayed 2 已播放

1. 设置消息状态

static bool SetStatusAsync(const std::string& msg_id, nim::NIMMsgLogStatus msglog_status, const SetStatusCallback& cb, const std::string& json_extension = "");
参数 说明
msg_id 指定的消息唯一id
msglog_status 指定需要修改的状态
cb 操作结果回调通知
json_extension 扩展字段,预留
// 设置client_msgid为kNIMMsgLogStatusSent状态;
nim::MsgLog::SetStatusAsync("client_msgid",kNIMMsgLogStatusSent,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
    ...
});

2. 设置消息子状态

static bool SetSubStatusAsync(const std::string& msg_id, nim::NIMMsgLogSubStatus msglog_sub_status, const SetSubStatusCallback& cb, const std::string& json_extension = "");
参数 说明
msg_id 指定的消息唯一id
msglog_sub_status 指定需要修改的消息子状态,详见NIMMsgLogSubStatus
cb 操作结果回调通知
json_extension 扩展字段,预留
// 设置client_msgid为kNIMMsgLogStatusSent状态;
nim::MsgLog::SetSubStatusAsync("client_msgid",kNIMMsgLogSubStatusPlayed,(nim::NIMResCode res_code, const std::string& msg_id)
{
    ...
});

查询服务器消息历史

通过消息类型从服务器端获取消息历史,通过起止时间错和limit的显示来限制获取的范围。

static bool QueryMsgOnlineAsync(const std::string &id, nim::NIMSessionType to_type, int limit_count, int64_t from_time, int64_t end_time, int64_t end_msg_id, bool reverse, bool need_save_to_local, const QueryMsgCallback& cb, const std::string& json_extension = "");
参数 说明
id 会话id,对方的account id或者群组tid
to_type 会话类型
limit_count 搜索结果的条数限制
from_time 起始时间戳,单位:毫秒
end_time 结束时间戳,单位:毫秒
end_msg_id 结束查询的最后一条消息的服务器端消息id(server_msg_id)(不包含在查询结果中)
reverse true:反向查询(按时间正序起查,正序排列),false:按时间逆序起查,逆序排列(建议默认为false)
need_save_to_local true: 将在线查询结果保存到本地,false: 不保存
cb 查询结果回调
json_extension 扩展字段,预留
NIM.Messagelog.QueryMsglogOnline(id, to_type, limit, from_time, end_time,
    end_msg_id, false, true, true, [&](nim::NIMResCode res_code, const std::string& id, nim::NIMSessionType to_type, const nim::QueryMsglogResult& result)
{
    if (res_code == kNIMResSuccess){
        ···
    }
})

导入导出消息历史

SDK为了方便用户,提供导入和导出消息历史文件的接口,必须提供导入或者导出文件的绝对路径。

导出消息历史

导出整个消息历史DB文件(不包括系统消息历史,android 和 ios 平台下不可用)

static bool ExportDbAsync(const std::string& dst_path, const DBFunctionCallback& cb, const std::string& json_extension = "");
参数 说明
dst_path 导出时保存的目标绝对路径,必须保证该路径下可写入文件
cb 操作结果回调通知
json_extension 扩展字段,预留
//以windows平台路径为例
nim::MsgLog::ExportDbAsync("D:\\msg.db",[&](nim::NIMResCode res_code)
{
    ...
});

导入消息历史

导入消息历史记录(不包括系统通知),且不允许拿别人的消息历史记录文件来导入。调用此接口需要传入消息历史文件的绝对路径。

static bool ImportDbAsync(const std::string& src_path, const DBFunctionCallback& cb    , const ImportDbPrgCallback& prg_cb, const std::string& json_extension = "");
参数 说明
src_path 导出时保存的目标绝对路径,必须保证该路径下可写入文件
cb 操作结果回调通知
prg_cb 操作进度回调通知
json_extension 扩展字段,预留
//以windows平台路径为例
nim::MsgLog::ImportDbAsync("D:\\msg.db",[&](nim::NIMResCode res_code)
{
    ...
},[&](int64_t imported_count, int64_t total_count)=>
{
    //通知操作进度
    ...
});