CommsEase provides three built-in user relations, such as friend list, blocklist, and Do Not Disturb list. The three relations are independent. The three relations can exist between two users.

Friend list

Getting the friend list

Getting accounts of all friends

The API is synchronous and returns the accounts of all friends.

• API prototype

java/**
 * Get accounts of all friends.
 *
 * @return - friend accounts.
 */
List<String> getFriendAccounts();

• Example

javaList<String> friends = NIMClient.getService(FriendService.class).getFriendAccounts();

Getting the profiles of all friends

• API prototype

java/**
 * Get the profiles of all friends.
 *
 * @return - Friends set.
 */
java.util.List<Friend> getFriends();

Getting the friend list by account

• API prototype

java/**
 * Get the friend list by user account.
 *
 * @param account - User account.
 * @return - Corresponding friends of the account.
 */
Friend getFriendByAccount(String account);

• Example

javaFriend friend = NIMClient.getService(FriendService.class).getFriendByAccount("account");

Get accounts by alias

Get the list of friend accounts with specified alias from the local database.

• API prototype

java/**
 * Query accounts by alias.
 *
 * @param alias - Alias.
 * @return - List of accounts.
 */
InvocationFuture<List<String>> searchAccountByAlias(String alias);

• Example

javaNIMClient.getService(FriendService.class).searchAccountByAlias("alias").setCallback(new RequestCallbackWrapper<List<String>>() {
    @Override
    public void onResult(int code, List<String> result, Throwable exception) {
        if (code == ResponseCode.RES_SUCCESS) {
            // Success.
        } else {
            // Failure. See the code for error code
        }

        if (exception != null) {
            // Error
        }
    }
});

Getting friends by keyword

java/**
 * Search all friends by keyword.
 *
 * @param keyword - Keyword.
 * @return - friend list.
 */
InvocationFuture<java.util.List<Friend>> searchFriendsByKeyword(java.lang.String keyword);

Managing the friend list

Requesting for friendship

Two verification types for adding friends (see VerifyType): add as friend or send a friend request. By the latter, friendship can be created with the permission of the peer.

When adding friends, you must create AddFriendData and join the account of the peer, friend verification type, and additional information (optional).

VerifyType attribute:

VerifyType attribute	Description
DIRECT_ADD	Add as friend.
VERIFY_REQUEST	Send a friend request.

AddFriendData interface:

Return	AddFriendData interface	Description
String	getAccount()	Get an account.
String	getMsg()	Get additional information for friend requests.
VerifyType	getVerifyType()	Get the type of friend requests.

• API prototype

java/**
 * Friend requests.
 *
 * @param data - Friend request information (including account of the peer, verification type of friend request, P.S.)
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error codes will be returned.
 */
InvocationFuture<Void> addFriend(AddFriendData data);

• Parameters

Parameter	Description
data	Friend request information (including account of the peer, verification type of friend request, and remark)

• Example

javafinal VerifyType verifyType = VerifyType.VERIFY_REQUEST; // Initiate the request for friend verification
String msg = "P.S. for friend request";
NIMClient.getService(FriendService.class).addFriend(new AddFriendData(account, verifyType, msg))
	.setCallback(new RequestCallback<Void>() {... });

Response to friend requests

Accepts or rejects the received friend request.

• API prototype

java/**
 * Accept or reject a friend request.
 *
 * @param account - Account of the peer.
 * @param agree - "true" indicates to accept request; "false" indicates to reject request.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> ackAddFriendRequest(String account, boolean agree);

• Parameters

Parameter	Description
account	Account of the peer.
agree	"true" indicates approve; "false" indicates reject.

• Example

java// Take "Accept friend request of the peer" for an example
NIMClient.getService(FriendService.class).ackAddFriendRequest(account, true).setCallback(...);

Listening for friendship related operations

After friends related operations are implemented, the peer will receive a system notification SystemMessage. See System Notification.

• The field value of friends related system notification "SystemMessage - getType()" is "SystemMessageType.AddFriend".
• "getEvent()" of "AddFriendNotify" type object that is acquired through "SystemMessage - getAttachObject()" is used to get detailed operation event.

AddFriendNotify.Event attribute

AddFriendNotify.Event attribute	Description
RECV_ADD_FRIEND_DIRECT	The peer adds you as friend.
RECV_ADD_FRIEND_VERIFY_REQUEST	Send friend request by the peer.
RECV_AGREE_ADD_FRIEND	Approve friend request by the peer.
RECV_REJECT_ADD_FRIEND	Reject friend request by the peer.

• Example

javaNIMClient.getService(SystemMessageObserver.class).observeReceiveSystemMsg(systemMessageObserver, register);

Observer<SystemMessage> systemMessageObserver = new Observer<SystemMessage>() {
    @Override
    public void onEvent(SystemMessage systemMessage) {
        if (systemMessage.getType() == SystemMessageType.AddFriend) {
            AddFriendNotify attachData = (AddFriendNotify) message.getAttachObject();
            if (attachData != null) {
            // Handle different events.
                if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_DIRECT) {
                // The peer  adds you as friend.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_AGREE_ADD_FRIEND) {
                // The peer accepts your request for friend verification.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_REJECT_ADD_FRIEND) {
                // The peer rejects your request for friend verification.
                } else if (attachData.getEvent() == AddFriendNotify.Event.RECV_ADD_FRIEND_VERIFY_REQUEST) {
                // The peer requests for adding you as friends. In general scene, users may accept or reject friend request of the peer.
                // Get additional information for friend verification request using message.getContent().
                }
            }
        }
    }
};

Listening for friendship changes

Friendship changes may trigger a callback:

• API prototype

java/**
 * Listen for notification for friends changes.
 *
 * @param observer - Observer. The parameter is received notification for friends change.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeFriendChangedNotify(Observer<FriendChangedNotify> observer, boolean register);

• Parameters

FriendChangedNotify interface

Return	Method	Description
List	getAddedOrUpdatedFriends()	Return added or updated friends.
List	getDeletedFriends()	Return deleted friends.

Friend interface

Return	Method	Description
String	getAccount()	Get friend account.
String	getAlias()	Get friend alias.
Map	getExtension()	Get the extension field.
String	getServerExtension()	Get the extension field of server. Only server interface can be changed.

• Example

javaNIMClient.getService(FriendServiceObserve.class).observeFriendChangedNotify(friendChangedNotifyObserver, true);
private Observer<FriendChangedNotify> friendChangedNotifyObserver = new Observer<FriendChangedNotify>() {
    @Override
    public void onEvent(FriendChangedNotify friendChangedNotify) {
        List<Friend> addedOrUpdatedFriends = friendChangedNotify.getAddedOrUpdatedFriends(); // New added friends
        List<String> deletedFriendAccounts = friendChangedNotify.getDeletedFriends(); // Deleted or removed friends
       ...
    }
};

Delete a friend

The relationship will be relieved automatically after deleting friends. Both parties will be disappeared from the list of friends. By default, both parties can still chat with each other after deleting friends.

• API prototype

java/**
 * Delete friends.
 *
 * @param account - account whose friends are removed.
 * @param deleteAlias - It determines to clear alias.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<java.lang.Void> deleteFriend(java.lang.String account,boolean deleteAlias);

• Example

javaNIMClient.getService(FriendService.class).deleteFriend(account,true)
	.setCallback(new RequestCallback<Void>() {... });

Checking friendship

• API prototype

java/**
 * The API determines whether a user is in the friend list.
 *
 * @param account - Account of the peer.
 * It determines that the account is in the friend list.
 */
boolean isMyFriend(String account);

• Example

javaboolean isMyFriend = NIMClient.getService(FriendService.class).isMyFriend(account);

Modifying friend remarks

Updates friend's alias and friend extension field. See FriendFieldEnum.

FriendFieldEnum schema:

Field	Description
ALIAS	The alias of the user account.
EXTENSION	Extension field.
undefined	Undefined domain.

• API prototype

java/**
 * Update friends.
 *
 * @param friendAccount - Friend account to be updated.
 * @param fields - Set of all fields to be updated. It is available to update alias and extension field now.
 * Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; SDK is responsible for converting it into Json String; the maximum length is 256 characters.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> updateFriendFields(String friendAccount, Map<FriendFieldEnum, Object> fields);

• Parameters

Parameter	Description
friendAccount	Friend account to be updated.
fields	Set of all fields to be updated. You can update alias and extension field now. Notes: The maximum length of alias is 128 characters. Extension field must be input to Map; key is String; Value is Object; The SDK converts it into JSON String; the maximum length is 256 characters.

• Example

java// Update the alias.
Map<FriendFieldEnum, Object> map = new HashMap<>();
map.put(FriendFieldEnum.ALIAS, content);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

// Update the extension field.
Map<FriendFieldEnum, Object> map = new HashMap<>();
Map<String, Object> exts = new HashMap<>();
exts.put("ext", "ext");
map.put(FriendFieldEnum.EXTENSION, exts);
NIMClient.getService(FriendService.class).updateFriendFields(data, map).setCallback(callback);

Blocklist

When a user is added to the blocklist, you will not receive any message or request from the user. For example, if user A adds user B to the blocklist, user A will not receive any message from user B. But user B can read any message sent from user A.

Getting the blocklist

• API prototype

java/**
 * Return the users in Blocklist.
 *
 * @return - all accounts in the blocklist.
 */
List<String> getBlocklist();

• Example

javaList<String> accounts = NIMClient.getService(FriendService.class).getBlocklist();

Adding a user to a blocklist

• API prototype

java/**
 * Add a user to a blocklist.
 *
 * @param account - User account.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> addToBlocklist(String account);

• Example

javaNIMClient.getService(FriendService.class).addToBlocklist(account)
   .setCallback(new RequestCallback<Void>() {... });

Remove a user from a blocklist

• API prototype

java/**
 * Remove a user from the blocklist.
 *
 * @param account - User account.
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> removeFromBlocklist(String account);

• Example

javaNIMClient.getService(FriendService.class).removeFromBlocklist(user.getAccount())
	.setCallback(new RequestCallback<Void>() {... });

Listening for blocklist changes

• API prototype

java/**
 * Listen for notification for blocklist change.
 *
 * @param observer - Observer. The parameter is received notification for blocklist change.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeBlocklistChangedNotify(Observer<BlocklistChangedNotify> observer, boolean register);

• Parameters

BlocklistChangedNotify interface:

Return	Method	Description
List	getAddedAccounts()	Return user accounts added to the blocklist.
List	getRemovedAccounts()	Return user accounts removed from the blocklist.

• Example

javaNIMClient.getService(FriendServiceObserve.class)
   .observeBlocklistChangedNotify(BlocklistChangedNotifyObserver, true);

private Observer<BlocklistChangedNotify> BlocklistChangedNotifyObserver
    = new Observer<BlocklistChangedNotify>() {
    @Override
    public void onEvent(BlocklistChangedNotify BlocklistChangedNotify) {
        List<String> addedAccounts = BlocklistChangedNotify.getAddedAccounts(); // Set of accounts added to the blocklist
        List<String> removedAccounts = BlocklistChangedNotify.getRemovedAccounts(); // Set of accounts removed from Blocklist
       ...
    }
};

Determining whether a user is in the blocklist

• API prototype

java/**
 * The API determines whether a user is added to the blocklist.
 *
 * @param account - User account.
 * @return - The API determines that a user is added to the blocklist.
 */
boolean isInBlocklist(String account);

• Example

javaboolean black = NIMClient.getService(FriendService.class).isInBlocklist(account);

Do Not Disturb setting

Sets mute for users. When the message from a user is received, you will not be reminded by notification bar, vibration and bell in the range of YunXin. Message reminding setting for individual user supports multi-client synchronization.

Get the Do Not Disturb list

• API prototype

java/**
 * Get the list of all accounts without message alert (list of accounts  that apply Do Not Disturb).
 *
 * @return - Accounts without message alert.
 */
List<String> getMuteList();

• Example

javaList<String> accounts = NIMClient.getService(FriendService.class).getMuteList();

Do Not Disturb setting

• API prototype

java/**
 * Configure the Do Not Disturb setting.
 *
 * @return InvocationFuture - Configurable callback feature. It can be invoked only when the message is sent. If an error occurs, detailed error code will be returned.
 */
InvocationFuture<Void> setMessageNotify(String account, boolean notify);

• Parameters

Parameter	Description
account	Account to be set with notification.
notify	Whether to notify the message from a user. false represents no notification.

• Example

javaNIMClient.getService(FriendService.class).setMessageNotify(account, checkState)
	.setCallback(new RequestCallback<Void>() {
		@Override
		public void onSuccess(Void param) {
			if (checkState) {
				Toast.makeText(UserProfileActivity.this, "Enable message alert", Toast.LENGTH_SHORT).show();
			} else {
				Toast.makeText(UserProfileActivity.this, "Disable message alert", Toast.LENGTH_SHORT).show();
			}
});

Listening for change in the Do Not Disturb list

• API prototype

java/**
 * Listen for the notification for change in the Do Not Disturb list.
 *
 * @param observer - Observer. The parameter is received notification for change in mute list.
 * @param register - "true" indicates to register Listen foring, "false" is to cancel Listen foring.
 */
void observeMuteListChangedNotify(Observer<MuteListChangedNotify> observer, boolean register);

• Parameters

MuteListChangedNotify interface

Return	Method	Description
String	getAccount()	User with change in mute setting.
boolean	isMute()	Set that the user is muted.

• Example

javaNIMClient.getService(FriendServiceObserve.class).observeMuteListChangedNotify(
    new Observer<MuteListChangedNotify>() {
        @Override
        public void onEvent(MuteListChangedNotify notify) {
            // notify.isMute() - It determines to be muted.
        }
    }, register);

Checking the Do Not Disturb status

• API prototype

java/**
 * The API determines that a user requires message alert/mute.
 *
 * @param account - User account.
 * @return - true: to set tip, false: to set mute.
 */
boolean isNeedMessageNotify(String account);

• Example

javaboolean notice = NIMClient.getService(FriendService.class).isNeedMessageNotify(account);