Local Record

A relatively complete message record management feature is provided, which allows developers to view, delete, and clear (local and online) chat history, write message records，and import/export historical messages (can only input records of the current user). Please note that operations such as deletion and status changes (such as sending failure or success) of local message history will be automatically synchronized to the message status in the session list. Therefore, the top-level app needs to process corresponding notification events according to monitored session list notification.

Global Notification of Message Status Change

• API introduction

Register the global notification of message status change (currently only covers the read status change). Upon receiving message read status from the other party, the caller will receive this registered callback.

• API prototype

static void RegMessageStatusChangedCb(const MessageStatusChangedCallback& cb, const std::string &json_extension = "");

• Example

//Register global notification of message status change
nim::MsgLog::RegMessageStatusChangedCb([&](const MessageStatusChangedResult& result)
{
	...
});

Query Message History

• API introduction

SDK provides an interface for querying local message history based on anchor time, and the results of which are sorted according to time (the reverse order of time determines that the results are sorted in reverse order). You can use the extension field to query earlier or later messages.

• API prototype

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

• Parameter Description

Parameter	Description
account_id	Session ID, account ID of the other party or team tid
to_type	Session type
limit_count	The number of sessions for one query, 20 is the recommended value
anchor_msg_time	The timestamp of the last message of the last query (The reverse order of time determines the timestamp is the smallest.)
cb	Query result callback notification
json_extension	Extension field, only supports query for earlier or later messages, such as {"direction":0}, 0: query messages that are earlier than the anchor time, 1: query messages that are later than the anchor time

Direction Attribute description:

Enumeration	Value	Description
kForward	0	Query message earlier than anchor time
kBackward	1	Query message later than anchor time

• Example

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


//Control the time range, towards earlier or later messages
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));

Message Query based on Message uuid

• API prototype

static bool QueryMsgByIDAysnc(const std::string &client_msg_id, const QuerySingleMsgCallback &cb, const std::string &json_extension = "");

• Parameter Description

Parameter	Description
client_msg_id	Message ID used in the query
cb	Query result callback notification
json_extension	Extension field. Reserved

• Example

string clientMsgId="msg_id";//Follow the actual message ID
nim::MsgLog::QueryMsgByIDAysnc(clientMsgId, [&](NIMResCode ret, const std::string& id, const nim::IMMessage& msg) 
{
	...
});

Query Local Messages based on Specified Conditions

• API introduction

Query local messages based on specified conditions. This interface can be used to perform features such as global search. See the development manual for details. Currently, it only supports queries by a single ID, which means you can add only oneidsuid for the query. The parameter searchContent cannot be empty.

• API prototype

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

• Parameter Description

Parameter	Description
query_range	Searchable range of message history
ids	Session ID, a collection of other parties' account IDs or team tids, currently only single ID query is supported
limit_count	Quantity limit for query results
from_time	Starting timestamp, unit: milliseconds
end_time	Ending timestamp, unit: milliseconds
end_client_msg_id	client_msg_id of the last message at the end of query (not included in the query results) (not enabled for the time being)
reverse	true: reverse query (searched in positive order by time, sorted in positive order), false: searched in reverse order by time, sorted in reverse order (We recommend searching in reverse order by time)
msg_type	Searchable message types (only three types are supported for the time being, namely kNIMMessageTypeText, kNIMMessageTypeImage and kNIMMessageTypeFile)
search_content	Text search (currently only keyword search in text and file name are supported) is available for two types of messages, namely kNIMMessageTypeText and kNIMMessageTypeFile. Combined search requires using kNIMMessageTypeUnknown
cb	Query result callback
json_extension	Extension field. Reserved

NIMMsgLogQueryRange Enumeration type

Enumeration	Value	Description
kNIMMsgLogQueryRangeP2P	0	Specified user (p2p session) (Note: Search by specifying multiple users is not supported for the time being.)
kNIMMsgLogQueryRangeTeam	1	Specified team (Note: Search by specifying multiple teams is not supported for the time being.)
kNIMMsgLogQueryRangeAll	100	All
kNIMMsgLogQueryRangeAllP2P	101	All individual sessions
kNIMMsgLogQueryRangeAllTeam	102	All teams
kNIMMsgLogQueryRangeUnknown	200	Query is not supported

• Example

//Take P2P message as an example
std::list<std::string> ids;
ids.push_back("testAccount");
int64_t sTimetag = 1519977874123; //13-bit timestamp in milliseconds
int64_t eTimetag = 1519978139567; 13-bit timestamp in milliseconds, it should be later than sTimetag, that is, eTimetag> sTimetag
std::string endMsgId = "lastmsgid";//The message id corresponding to eTimetag
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){
        ···
    }
})

Insert Local Message

Save the message to the local database. If the message already exists, it will be updated without being sent to the server. You need to ensure that the entire message conforms to the content requirements for message sending and receiving.

• API prototype

static bool WriteMsglogToLocalAsync(const std::string& talk_id, const IMMessage& msg, bool need_update_session, const WriteMsglogCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
talk_id	Session ID, account ID of the other party or team tid
need_update_session	It determines whether to update the session list (generally required for the latest message)
msg	Message body, see IMMessage for details
cb	Callback function of operation result
json_extension	Extension field. Reserved

• Example

//Create a text message, taking the receiver's testAccount as an example

nim::IMMessage msg;
msg.receiver_accid_ = "testAccount"; receiver's account
msg.sender_accid_ = "myUid";//Sender's account
msg.client_msg_id_ = "uuid";//The unique ID of the message
msg.session_type_ = kNIMSessionTypeP2P;
msg.type_ = kNIMMessageTypeText;
msg.local_talk_id_="testAccount";The receiver's account
msg.timetag_=1519977874123;//13-bit timestamp in milliseconds
msg.status_=kNIMMsgLogStatusDraft;//It can be set to other message status
msg.content_ = "111";

...
// Save a message to the local database without sending it to server
nim::MsgLog::WriteMsglogToLocalAsync("testAccount", msg, true,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
	...
});

Delete Message History

You can delete a message with a specified msgid, or delete messages in batches.

1. Delete a specified message

• API introduction

Delete message history according to specified receiver account or team ID, msgId.

• API prototype

static bool DeleteAsync(const std::string& session_id, NIMSessionType to_type, const std::string& msg_id, const DeleteCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
session_id	Receiver account or team ID
to_type	Type of current session, specified enumeration typeNIMSessionType
msg_id	Specify the unique ID of the message to be deleted
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

//Taking p2p messages of the testAccount as an example
nim::MsgLog::DeleteAsync("testAccout",kNIMSessionTypeP2P,"client_msgid",[&](nim::NIMResCode res_code, const std::string& msg_id)
{
	...
});

2. Delete all messages of the specified session type

• API introduction

Delete the history from the databaseto_typespecified in the notification, operation is limited to the local database without syncing with the server.

• API prototype

static bool DeleteBySessionTypeAsync(bool delete_sessions, NIMSessionType to_type, const DeleteBySessionTypeCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
to_type	Type of the current session, specifying the enumeration type NIMSessionType
delete_sessions	It determines whether to delete the session list item synchronously. If it is true, delete the session list item. If it is false, do not delete the item but only tag the message status as deleted.
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

// delete p2p message records in batches
nim::MsgLog::DeleteBySessionTypeAsync(true,kNIMSessionTypeP2P,[&](nim::NIMResCode res_code, const std::string& uid, nim::NIMSessionType to_type)
{
	...
});

3. Delete all history

• API introduction

Delete all local message history, and specify whether to synchronously delete the items in the corresponding session list.

• API prototype

static bool DeleteAllAsync(bool delete_sessions, const DeleteAllCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
delete_sessions	It determines whether to delete the session list item synchronously. If it is true, delete the session list item. If it is false, do not delete the item but only tag the message status as deleted.
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

// delete p2p message records in batches
nim::MsgLog::DeleteAllAsync(kNIMSessionTypeP2P,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
	...
});

Update Message Status

The SDK supports updating message status to draft, etc., and sub-status of audio messages, such as played and unplayed, etc.

NIMMsgLogStatusMessage status

Enumeration	Value	Description
kNIMMsgLogStatusNone	0	This is the default value. The value cannot be used as a search condition because it has no definite scope.
kNIMMsgLogStatusUnread	1	The message is received but unread
kNIMMsgLogStatusRead	2	The message is received and read
kNIMMsgLogStatusDeleted	3	The message is deleted
kNIMMsgLogStatusSending	4	The message is being sent
kNIMMsgLogStatusSendFailed	5	: The message is not sent successfully
kNIMMsgLogStatusSent	6	Message sent
kNIMMsgLogStatusReceipt	7	The other party has read the message sent
kNIMMsgLogStatusDraft	8	Draft
kNIMMsgLogStatusSendCancel	9	Cancel sending
kNIMMsgLogStatusRefused	10	The message is rejected by the other party, due to reasons such as being blacklisted.

NIMMsgLogSubStatusMessage substatus

Enumeration	Value	Description
kNIMMsgLogSubStatusNone	0	Default
kNIMMsgLogSubStatusNotPlaying	1	Not played
kNIMMsgLogSubStatusPlayed	2	Played

1. Set message status

• API prototype

static bool SetStatusAsync(const std::string& msg_id, nim::NIMMsgLogStatus msglog_status, const SetStatusCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
msg_id	Unique ID of the specified message
msglog_status	Specify the status that needs to be updated
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

// Set client_msgid to kNIMMsgLogStatusSent;
nim::MsgLog::SetStatusAsync("client_msgid",kNIMMsgLogStatusSent,[&](nim::NIMResCode res_code, const std::string& msg_id)
{
	...
});

2. Set message sub-status

• API prototype

static bool SetSubStatusAsync(const std::string& msg_id, nim::NIMMsgLogSubStatus msglog_sub_status, const SetSubStatusCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
msg_id	Unique id of the specified message
msglog_sub_status	Specify the message sub-status that needs to be updated, see NIMMsgLogSubStatus for details
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

// Set client_msgid to kNIMMsgLogStatusSent;
nim::MsgLog::SetSubStatusAsync("client_msgid",kNIMMsgLogSubStatusPlayed,(nim::NIMResCode res_code, const std::string& msg_id)
{
	...
});

Query Server Message History

• API introduction

Get the message history from the server by message types and limit the scope of retrievalby specifying the starting and ending timestamps as well as the limit.

• API prototype

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

• Parameter Description

Parameter	Description
id	Session ID, account ID of the other party or team tid
to_type	Session type
limit_count	Quantity limit for query results
from_time	Starting timestamp, unit: milliseconds
end_time	Ending timestamp, unit: milliseconds
end_msg_id	The server-side message id of the last message at the end of query (server_msg_id) (not included in the query result)
reverse	true: reverse query (searched in positive order by time, sorted in positive order), false: searched in reverse order by time, sorted in reverse order (We recommend searching in reverse order by time)
need_save_to_local	true: Save online query results to the local database, false: Not to save
cb	Query result callback
json_extension	Extension field. Reserved

• Example

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

Import and Export Message History

For the convenience of users, SDK provides interfaces for importing and exporting message history files, for which the absolute path of the imported or exported file must be provided.

Export Message History

• API introduction

Export DB file of the entire message history (system message history is excluded, not available for android and ios platforms)

• API prototype

static bool ExportDbAsync(const std::string& dst_path, const DBFunctionCallback& cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
dst_path	The target absolute path saved when exporting, you need to ensure that you can write the file in this path
cb	Callback notification of operation result
json_extension	Extension field. Reserved

• Example

//Take the windows platform as an example
nim::MsgLog::ExportDbAsync("D：\\msg.db",[&](nim::NIMResCode res_code)
{
	...
});

Import Message History

• API introduction

Import message history (system notifications are excluded, and importing other's message history files is not allowed). Calling this interface requires inputting the absolute path of message history.

• API prototype

static bool ImportDbAsync(const std::string& src_path, const DBFunctionCallback& cb	, const ImportDbPrgCallback& prg_cb, const std::string& json_extension = "");

• Parameter Description

Parameter	Description
src_path	The target absolute path saved when exporting, you need to ensure that you can write the file in this path
cb	Callback notification of operation result
prg_cb	Operation progress callback notification
json_extension	Extension field. Reserved

• Example

//Take the windows platform as an example
nim::MsgLog::ImportDbAsync("D：\\msg.db",[&](nim::NIMResCode res_code)
{
	...
},[&](int64_t imported_count, int64_t total_count)=>
{
    //Notification of operation progress
	...
});