本地记录

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

全局消息状态变更通知

• API 介绍

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

• API 原型

public static void RegMsglogStatusChangedCb(MsglogStatusChangedDelegate cb);

• 示例

//注册全局的消息状态变更通知
NIM.Messagelog.MessagelogAPI.RegMsglogStatusChangedCb((code，result)=>
{
	//result为json字符串,示例：[{"talk_id":"test1","msg_timetag":"1520500638234","status":2}]
	...
});

查询消息历史

• API 介绍

SDK 提供了一个根据锚点查询本地消息历史记录的接口，结果使用 time 作为排序字段（按时间逆序起查，逆序排列）。

• API 原型

public static void QueryMsglogLocally(string accountId, NIMSessionType sType, int limit, long msgAnchorTimetag, QueryMsglogResultDelegate action)

• 参数说明

参数	说明
accountId	会话id，对方的account id或者群组tid
sType	会话类型
limit	一次查询数量，建议20
msgAnchorTimetag	上次查询最后一条消息的时间戳（按时间逆序起查，即最小的时间戳）
action	查询结果回调通知

• 示例

NIM.Messagelog.MessagelogAPI.QueryMsglogLocally("session_id", NIM.Session.NIMSessionType.kNIMSessionTypeP2P, 20, 0, (code, accountId, sType, result) =>
{
	if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
});

包含起止时间的本地消息历史查询

• API 介绍

该接口使用方法与查询历史消息类似， 根据MsgAnchorTimttag时间查询更早或更晚的消息，返回 limit 条记录，如果小于 limit 条，返回实际条数。目前仅是查询消息历史基础上支持Direction，暂时不支持EndTimetag和Reverse。

• API 原型

public static void QueryMsglogLocally(QueryMsglogParams args, QueryMsglogResultDelegate action);

• 参数说明

QueryMsglogParams 重要参数说明

类型	参数	说明
string	AccountId	会话id，对方的account id或者群组tid
NIMSessionType	SessionType	会话类型
int	CountLimit	查询条数上限 必须大于0
long	MsgAnchorTimttag	查询时间锚点时间戳（毫秒）
long	EndTimetag	查询时间截止点时间戳（毫秒），暂不支持
MsglogSearchDirection	Direction	查询更早或更晚的消息
bool	Reverse	true：反向查询(按时间正序起查，正序排列)，false：按时间逆序起查，逆序排列（建议默认为false），暂不支持

MsglogSearchDirection 属性说明:

枚举	值	说明
kForward	0	查询比锚点时间更早的消息
kBackward	1	查询比锚点时间更晚的消息

• 示例

// 以P2P类型为例，testAccount为测试帐号
QueryMsglogParams param = new QueryMsglogParams{
	AccountId="testAccount为测试帐号",
    SessionType=kNIMSessionTypeP2P,
    CountLimit = 20,
    MsgAnchorTimttag = 1519977874123,//13位时间戳毫秒
    EndTimetag = 1519978139567，//13位时间戳毫秒
    Direction = MsglogSearchDirection.kBackward
};
NIM.Messagelog.MessagelogAPI.QueryMsglogLocally(param, (code, accountId, sType, result) =>
{
	if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
});

根据消息 uuid 查询消息

• API 原型

public static void QuerylogById(string clientMsgId, QueryLogByMsgIdResultDelegate action);

• 参数说明

参数	说明
clientMsgId	所查询的消息id
action	查询结果回调通知

• 示例

string clientMsgId="msg_id";//以实际的消息id为准
MessagelogAPI.QuerylogById(clientMsgId, (code, msdId, msg)=>
{
    ...
});

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

• API 介绍

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

• API 原型

 public static void QueryMsglogByCustomCondition(NIMMsgLogQueryRange range, string[] ids, int limit,
            long sTimetag, long eTimetag, string endMsgId, bool reverse,
            NIMMessageType msgType, string searchContent, QueryMsglogResultDelegate action)；

• 参数说明

参数	说明
range	消息历史的检索范围
ids	会话id，对方的account id的集合或者群组tid的集合，目前仅支持单个id的查询
limit	搜索结果的条数限制
sTimetag	起始时间戳，单位：毫秒
eTimetag	结束时间戳，单位：毫秒
endMsgId	结束查询的最后一条消息的client_msg_id(不包含在查询结果中)（暂不启用）
reverse	true：反向查询(按时间正序起查，正序排列)，false：按时间逆序起查，逆序排列（建议默认为false）
msgType	检索的消息类型（目前只支持kNIMMessageTypeText、kNIMMessageTypeImage和kNIMMessageTypeFile这三种类型消息）
searchContent	检索文本（目前只支持kNIMMessageTypeText和kNIMMessageTypeFile这两种类型消息的文本关键字检索，即支持文字消息和文件名的检索。如果合并检索，需使用未知类型消息kNIMMessageTypeUnknown
action	查询结果回调

NIMMsgLogQueryRange枚举类型

枚举	值	说明
kNIMMsgLogQueryRangeP2P	0	指定的个人（点对点会话）（注意：暂不支持指定多个人的检索！）
kNIMMsgLogQueryRangeTeam	1	指定的群组（注意：暂不支持指定多个群组的检索！）
kNIMMsgLogQueryRangeAll	100	全部
kNIMMsgLogQueryRangeAllP2P	101	所有个人会话
kNIMMsgLogQueryRangeAllTeam	102	所有群组
kNIMMsgLogQueryRangeUnknown	200	不支持查询

• 示例

//以P2P消息为例
string[] ids = new string[]();
ids.add("testAccount");
long sTimetag = 1519977874123;//13位时间戳毫秒
long eTimetag = 1519978139567;13位时间戳毫秒,需要比sTimetag更晚，即eTimetag > sTimetag
NIM.Messagelog.QueryMsglogByCustomCondition(NIMMsgLogQueryRange.kNIMMsgLogQueryRangeP2P, ids, 20,
            sTimetag, eTimetag, "", false, NIMMessageType.kNIMMessageTypeText, "111", (code, accountId, sType, result) =>
{
	if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
})

插入本地消息

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

• API 原型

public static void WriteMsglog(string uid, bool need_update_session, NIMIMMessage msg, OperateSingleLogResultDelegate action);

• 参数说明

参数	说明
uid	会话id，对方的account id或者群组tid
need_update_session	是否更新会话列表（一般最新一条消息会有更新的需求）
msg	消息体，详见NIMIMMessage
action	操作结果的回调函数

• 示例

// 创建一条文本消息,以对方账号testAccount为例
NIMTextMessage msg = new NIMTextMessage();
msg.ClientMsgID="uuid";//该条消息唯一id
msg.TalkID="testAccount";对方账号
msg.ReceiverID="testAccount";对方账号
msg.TimeStamp=1519977874123;//13位时间戳毫秒
msg.MsgLogStatus=NIMMsgLogStatus.kNIMMsgLogStatusDraft;//可设置其他消息状态
msg.TextContent="111";
...
// 保存消息到本地数据库，但不发送到服务器
NIM.Messagelog.MessagelogAPI.WriteMsglog("testAccount",true, msg, (code, msgId)=>
{
	...
});

删除历史消息

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

1. 删除指定的一条消息

• API 介绍

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

• API 原型

public static void DeleteSpecifiedMsglog(string sid, NIMSessionType sType, string msgId, OperateSingleLogResultDelegate action);

• 参数说明

参数	说明
sid	对方account或者群id
sType	当前会话的类型，指定枚举类型NIMSessionType
msgId	指定要删除的消息唯一id
action	操作结果回调通知

• 示例

//以p2p消息为例，测试账号testAccount
NIM.Messagelog.MessagelogAPI.DeleteSpecifiedMsglog("testAccout",NIMSessionType.kNIMSessionTypeP2P,"client_msgid",(code,msgId)=>
{
	...
});

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

• API 介绍

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

• API 原型

public static void DeleteMsglogsBySessionType(NIMSessionType sType, bool deleteSessions, OperateMsglogResultDelegate action));

• 参数说明

参数	说明
sType	当前会话的类型，指定枚举类型NIMSessionType
deleteSessions	是否要同步删除会话列表项，true：删除，false:不删除，仅标记消息状态为已删除
action	操作结果回调通知

• 示例

// 批量删除点对点消息记录
NIM.Messagelog.MessagelogAPI.DeleteMsglogsBySessionType(NIMSessionType.kNIMSessionTypeP2P,true,(code,msgId)=>
{
	...
});

3. 删除所有历史记录

• API 介绍

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

• API 原型

public static void ClearAll(bool deleteSessions, CommonOperationResultDelegate action);

• 参数说明

参数	说明
deleteSessions	是否要同步删除会话列表项，true：删除，false:不删除，仅标记消息状态为已删除
action	操作结果回调通知

• 示例

// 批量删除点对点消息记录
NIM.Messagelog.MessagelogAPI.ClearAll(true,(code,msgId)=>
{
	...
});

修改消息状态

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. 设置消息状态

• API 原型

public static void SetMsglogStatus(string msgId, NIMMsgLogStatus status, OperateSingleLogResultDelegate action);

• 参数说明

参数	说明
msgId	指定的消息唯一id
status	指定需要修改的状态
action	操作结果回调通知

• 示例

// 设置client_msgid为kNIMMsgLogStatusSent状态;
NIM.Messagelog.MessagelogAPI.SetMsglogStatus("client_msgid",NIMMsgLogStatus.kNIMMsgLogStatusSent,(code,msgId)=>
{
	...
});

2. 设置消息子状态

• API 原型

public static void SetMsglogSubStatus(string msgId, NIMMsgLogSubStatus status, OperateSingleLogResultDelegate action);

• 参数说明

参数	说明
msgId	指定的消息唯一id
status	指定需要修改的消息子状态，详见NIMMsgLogSubStatus
action	操作结果回调通知

• 示例

// 设置client_msgid为kNIMMsgLogStatusSent状态;
NIM.Messagelog.MessagelogAPI.SetMsglogSubStatus("client_msgid",NIMMsgLogSubStatus.kNIMMsgLogSubStatusPlayed,(code,msgId)=>
{
	...
});

查询服务器消息历史

• API 介绍

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

• API 原型

public static void QueryMsglogOnline(string id, NIMSessionType sType, int limit, long sTimetag, long eTimetag,
    long endMsgId, bool reverse, bool saveLocal,bool autoDownloadAttach, QueryMsglogResultDelegate action)；

• 参数说明

参数	说明
id	会话id，对方的account id或者群组tid
sType	会话类型
limit	搜索结果的条数限制
sTimetag	起始时间戳，单位：毫秒
eTimetag	结束时间戳，单位：毫秒
endMsgId	结束查询的最后一条消息的服务器端消息id(server_msg_id)(不包含在查询结果中)
reverse	true：反向查询(按时间正序起查，正序排列)，false：按时间逆序起查，逆序排列（建议默认为false）
saveLocal	true: 将在线查询结果保存到本地，false: 不保存
autoDownloadAttach	查询结果回来后，是否需要sdk自动下载消息附件（暂时不支持）,默认由全ClientAPI.Init传入的NimUtility.NimConfig来控制
action	查询结果回调

• 示例

NIM.Messagelog.QueryMsglogOnline(id, sType, limit, sTimetag, eTimetag,
    endMsgId, false, true, true, (code, accountId, sType, result) =>
{
	if (code == ResponseCode.kNIMResSuccess){
        foreach(var i in result.MsglogCollection)
        {
            ···
        }
    }
})

导入导出消息历史

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

导出消息历史

• API 介绍

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

• API 原型

public static void ExportDatabaseFile(string destPath, CommonOperationResultDelegate action);

• 参数说明

参数	说明
destPath	导出时保存的目标绝对路径，必须保证该路径下可写入文件
action	操作结果回调通知

• 示例

//以windows平台路径为例
NIM.Messagelog.MessagelogAPI.ExportDatabaseFile("D：\\msg.db",(code)=>
{
	...
});

导入消息历史

• API介绍

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

• API 原型

public static void ImportDatabase(string srcPath, CommonOperationResultDelegate action, ImportProgressDelegate prg);

• 参数说明

参数	说明
srcPath	导出时保存的目标绝对路径，必须保证该路径下可写入文件
action	操作结果回调通知
prg	操作进度回调通知

• 示例

//以windows平台路径为例
NIM.Messagelog.MessagelogAPI.ImportDatabase("D：\\msg.db",(code)=>
{
	...
},(importedCount, totalCount)=>
{
    //通知操作进度
	...
});