Recent Local Session
Update time: 2021/12/03 09:02:41
Overview
Recent session list is the list of recent contacts. When a message is received from a new contact, the SDK will automatically generate a local recent session. It records account and type of contact, time of recent message, status, content, and unread count.
Prototype RecentContact
. interface:
Return | RecentContact interface | Description |
---|---|---|
MsgAttachment | getAttachment() | Get attachment of the recent message. |
String | getContactId() | Get recent contact ID (friend's account, team ID.). |
String | getContent() | Get brief content of the recent message. |
Map | getExtension() | Get the extension field of the recent session object. |
String | getFromAccount() | Get sender account of the recent message. |
String | getFromNick() | Get sender display name of the recent message with the contact. |
MsgStatusEnum | getMsgStatus() | Get state of the recent message. |
MsgTypeEnum | getMsgType() | Get type of the recent message. |
String | getRecentMessageId() | Get client ID of the recent message, i.e. IMMessage#getUuid(). |
SessionTypeEnum | getSessionType() | Get session type (one-to-one chat or team chat). |
long | getTag() | Get tag attribute. |
long | getTime() | Get time of the recent message, unit: ms. |
int | getUnreadCount() | Get unread count. |
void | setExtension(Map extension) | Set extension field of the recent session object. |
void | setMsgStatus(MsgStatusEnum msgStatus) | Set the recent message status. |
void | setTag(long tag) | Sticky tag for extension purposes, for example, setting contacts to top, ranking recent session list. |
Getting the most recent session
Get the recent session list for display session list on home page.
Getting the most recent sessions
- Asynchronous interface:
java/**
* Query the list of recent contacts.
*
* @return InvocationFuture.
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts();
- Synchronous interface:
java/**
* Query the list of recent contacts (synchronous interface).
*
* @return InvocationFuture.
*/
public List<RecentContact> queryRecentContactsBlock();
- Example
javaNIMClient.getService(MsgService.class).queryRecentContacts()
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
The parameter "// recents" is the list of recent contacts (list of recent sessions)
}
});
Geting recent session list (custom)
Filtering messages of specified type
If the recent message of returned session is not a certain type of message, the following filtering interface can be used.
If the recent message is not text message, then returned session from the interface is used and the recent non-text message is taken as the recent message.
- Asynchronous interface:
java/**
* Query the list of recent contacts.
*
* @return InvocationFuture.
*/
public InvocationFuture<List<RecentContact>> queryRecentContacts(MsgTypeEnum filterMsgType);
- Synchronous interface:
java/**
* Query the list of recent contacts, and filter specified message type (synchronous interface).
*
* @return InvocationFuture
*/
public List<RecentContact> queryRecentContactsBlock(MsgTypeEnum filterMsgType);
- Example
java NIMClient.getService(MsgService.class).queryRecentContacts(MsgTypeEnum.text)
.setCallback(new RequestCallbackWrapper<List<RecentContact>>() {
@Override
public void onResult(int code, List<RecentContact> recents, Throwable e) {
The parameter "// recents" is the list of recent contacts (list of recent sessions)
}
});
Getting a few sessions
Get specified number of recent sessions:
- Asynchronous interface
java/**
* Query the list of sessions with recent contacts. It can be set with limit to avoid slow loading for the first time due to more local sessions.
*
* "@param limit" is to get count of local sessions, with max. count 100. Otherwise, it will be modified to 100.
* @return InvocationFuture
*/
InvocationFuture<List<RecentContact>> queryRecentContacts(int limit);
- Synchronous interface
java/**
* Query the list of sessions with recent contacts (synchronous interface). It can be set with limit to avoid slow loading for the first time due to more local sessions.
*
* "@param limit" is to get count of local sessions, with max. count 100. Otherwise, it will be modified to 100.
*/
List<RecentContact> queryRecentContactsBlock(int limit);
- Example
javaNIMClient.getService(MsgService.class).queryRecentContacts(10);
Get the specified recent session
Starting with v5.9.0, you can get the corresponding sessions by session ID.
java/**
* Query the list of sessions with recent contacts (synchronous interface). It can be set with limit to avoid slow loading for the first time due to more local sessions.
* @param contactId - Session id, account of the other party or team ID.
* @param sessionType - Session type.
*/
RecentContact queryRecentContact(java.lang.String contactId, SessionTypeEnum sessionType);
Creating a recent session
- Create an empty recent session:
java/**
* Create an empty contact session
*
* @param contactId - Session id, account of the other party or team id.
* @param sessionType session type
* @param tag Session tag, eg: sticky tag (implementation in UIKit: RECENT_TAG_STICKY). Users can implement as per their own tag. Otherwise, 0 must be input. <br/>
* @param time Session time, unit: ms.
* @param saveToDB - It determines to store the session in DB. Notes: <br/>
* 1. If there is the same session (with same contactId and sessionType), it will not be stored in db; <br/>
* 2. If there is not the same session and needSaveToDB is true, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
* <b/>
* @return InvocationFuture<RecentContact>
*/
RecentContact createEmptyRecentContact(String contactId, SessionTypeEnum sessionType, long tag, long time,
boolean saveToDB);
- Configure the interface from which the final message searched from the local database is input.
java/**
* Create an empty contact session
*
* @param contactId - Session id, account of the other party or team id.
* @param sessionType session type.
* @param tag Session tag, eg: sticky tag (implementation in UIKit: RECENT_TAG_STICKY). Users can implement as per their own tag. Otherwise, 0 must be input. <br/>
* @param time Session time, unit: ms.
* @param saveToDB - It determines to store the session in DB. Notes: <br/>
* 1. If there is the same session (with same contactId and sessionType), it will not be stored in db; <br/>
* 2. If there is not the same session and needSaveToDB is true, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
* <b/>
* @param withLastMsg - It determines to input related information about the final message.
* @return InvocationFuture<RecentContact>
*/
RecentContact createEmptyRecentContact(String contactId, SessionTypeEnum sessionType, long tag, long time,
boolean saveToDB, boolean withLastMsg);
If a message has no corresponding recent local session, the recent local session can be created upon message using the following interface.
java/**
* @param message - Message.
* @param needNotify - It determines to trigger notification of MsgServiceObserve.observeRecentContact(Observer, boolean).
*/
void updateRecentByMessage(IMMessage message, boolean needNotify);
Updating recent sessions
Updating recent sessions
java/**
* Update attributes of a session with recent contact Now,
* @param recent - Data of session with recent contact to be updated.
*/
void updateRecent(RecentContact recent);
If you want to receive the notification of MsgServiceObserve.observeRecentContact(Observer, boolean), update can be made using the following interface:
java/**
* Update attributes of a session with recent contact Now
* @param recent - Data of session with recent contact to be updated.
*/
void updateRecentAndNotify(RecentContact recent);
Listening for changes of recent sessions
If the recent session object and its attributes have any change, SDK will update information about recent contact of corresponding chat object and send update notification of recent contact.
- API prototype
java/**
* Register or cancel observer for change in the list of recent contacts
* @param observer - Observer. The parameter is the list of changed recent contacts.
* @param register true indicates registered, and true indicates unregistered.
*/
public void observeRecentContact(Observer<List<RecentContact>> observer, boolean register);
- Example
java// Create observer object
Observer<List<RecentContact>> messageObserver = new Observer<List<RecentContact>>() {
@Override
public void onEvent(List<RecentContact> messages) {
}
}
// Register or cancel observer
NIMClient.getService(MsgServiceObserve.class).observeRecentContact(messageObserver, register);
Unread count
Get the unread count
Get the total unread count
java/**
* Get total unread count.
*/
public int getTotalUnreadCount();
Example
javaint unreadNum = NIMClient.getService(MsgService.class).getTotalUnreadCount();
Getting the number of unread count in a session
by RecentContact - getUnreadCount()
method.
Resetting the unread count
When you call the following interface to reset current session, SDK will manage the unread count automatically. The interface will call clearUnreadCount(String, SessionTypeEnum)
automatically to clear the unread count for the object who is chatting. If there is new message from the object who is chatting, the unread count will not increase.
java/**
* Set current session.
* @param account, - Account of chat object, or the following two values: MSG_CHATTING_ACCOUNT_ALL and MSG_CHATTING_ACCOUNT_NONE.
* @param sessionType Session type. If account is not the detailed object, the parameter will be ignored.
*/
void setChattingAccount(java.lang.String account, SessionTypeEnum sessionType);
Generally, the unread count must be recovered when leaving the chat interface:
java// Recover to update unread count.
NIMClient.getService(MsgService.class).setChattingAccount(MsgService.MSG_CHATTING_ACCOUNT_NONE, SessionTypeEnum.None);
If the unread count is cleared without joining chat window, the following interface can be called to implement:
java/**
* Clear unread count of specified recent contact (marked as "read"). <br>
* If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
*
* @param account - Account of chat room object
* @param sessionType session type
* @return - Send ack result
*/
InvocationFuture<Void> clearUnreadCount(String account, SessionTypeEnum sessionType);
/**
* Clear unread count of specified recent contact (marked as "read"). <br>
* If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
*
* @param sessionKeyList - List of accounts of chat object. For {@link Pair}, the first option is session ID and the second option is session type.
* The session type supports to input {@link SessionTypeEnum#peer-to-peer} and {@link SessionTypeEnum#Team}.
* @return - Send ack result. Elements in the list are failed parts.
*/
InvocationFuture<List<SessionAckInfo>> clearUnreadCount(List<Pair<String, SessionTypeEnum>> sessionKeyList);
/**
* Clear unread count of all contact (marked as "read")
* If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContact(Observer, boolean)} will be triggered.
*/
void clearAllUnreadCount();
Syncing the unread count on multiple devices
When the multi-client synchronization for number of unread session is enabled, the session read from one client will also be marked as "Read" in other clients.
Enable method: Setting SDKOptions - sessionReadAck
attribute to true.
Deleting recent sessions
Deleting a recent session
The SDK allows you to delete specified recent local and cloud session. However, messages in the session will be retained. When it is called, the total unread count will subtract the number of current unread session.
MsgService provides three methods: The distinction between deleteRecentContact(RecentContact) and deleteRecentContact2(String, SessionTypeEnum) is that the latter can trigger notification "MsgServiceObserve#observeRecentContactDeleted". The other interface cannot trigger "MsgServiceObserve#observeRecentContactDeleted", but support to set whether to delete roaming message simultaneously.
- API prototype
Version without triggering observer notification:
java/**
* Delete one option in the list of recent contacts.
* Invoke the interface to delete data will not generate observer notification.
*
* @param recent - Option of recent contact to be deleted.
*/
public void deleteRecentContact(RecentContact recent);
Version triggering observer notification:
java/**
* Delete history of recent contact.
* If the interface is invoked, the notification {@link MsgServiceObserve#observeRecentContactDeleted(Observer, boolean)} will be triggered.
*
* @param account
* @param sessionType
*/
public void deleteRecentContact2(String account, SessionTypeEnum sessionType);
Configurable version:
java/**
* Delete history of recent contact.<br>
*
* @param account - Session ID.
* @param sessionType - Session type. Only {@link SessionTypeEnum#peer-to-peer} and {@link SessionTypeEnum#Team} can be selected, and roaming message will be deleted.
* @param deleteType - Deletion type. It determines to delete local history and roaming history.
* If the value is null, it is considered as {@link DeleteTypeEnum#REMAIN}.
* @param sendAck - It determines to mark the session as "read" at other clients if the parameter is legal.
*/
InvocationFuture<Void> deleteRecentContact(String account, SessionTypeEnum sessionType, DeleteTypeEnum deleteType, boolean sendAck);
- Example
java// Not trigger the observer notification version.
NIMClient.getService(MsgService.class).deleteRecentContact(recent);
// Trigger the observer notification version.
NIMClient.getService(MsgService.class).deleteRecentContact2(account, SessionTypeEnum.peer-to-peer);
// Configurable version. It is configured to delete local session and roaming message. Besides, ACK must be sent.
NIMClient.getService(MsgService.class).deleteRecentContact(sessionId, sessionType, DeleteTypeEnum.LOCAL_AND_REMOTE, true)
.setCallback(deleteRecentCallback);
Delete roaming messages
The SDK allows you to delete roaming message of specified contact by the following method:
- API prototype
java/**
* Delete roaming messages that belong to specified recent contact.
* Not delete local message. If login occurs at other clients, messages generated in the session at current time point will not be roamed.
*
* @return InvocationFuture - Configurable callback feature. It can monitor the deletion result.
*/
public InvocationFuture<Void> deleteRoamingRecentContact(String contactId, SessionTypeEnum sessionTypeEnum);
- Parameters
Parameter | Description |
---|---|
contactId | ID of recent contact (friend ID, team ID.) |
sessionTypeEnum | Session type |
- Example
javaNIMClient.getService(MsgService.class)
.deleteRoamingRecentContact(contactId, sessionTypeEnum)
.setCallback(new RequestCallback<Void>() {... });