SDK supports user friendship management and message settings for user sessions. CommsEase supports chats between users who are not friends. User relationship not managed by CommsEase needs to be maintained by the developer on the application server.

Friendship

Get friends list

Get the collection of friend accounts, then you can get the corresponding user information based on the accounts, see User information hosting. Local cache is available for friends list, which will be synced and updated automatically with the server after manual/auto login. The callback function contains the nim::FriendProfileobject list.

• API prototype

c++/** @fn static void GetList(const GetFriendsListCallback& cb, const std::string& json_extension = "")
* Get friends list
* @param[in] cb Callback function of getting friends list
* @param[in] json_extension json extension parameter is not required in some cases
* @return void No value is returned
* @note Error code	200: success
*/
static void GetList(const GetFriendsListCallback& cb, const std::string& json_extension = "");

• Example

c++void OnGetFriendList(nim::NIMResCode res_code, const std::list<nim::FriendProfile>& user_profile_list)
{
    //Process friends list
}

void foo()
{
    nim::Friend::GetList(&OnGetFriendList);
}

Add Friends

Currently, there are two verification modes for adding friend: directly adding friend and initiating add friend verification request. The difference between the two is whether the verification by the other party is required to complete the operation.

• API prototype

c++/** @fn static bool Request(const std::string &accid, NIMVerifyType verify_type, const std::string &msg, const FriendOptCallback &cb, const std::string& json_extension = "")
* Add friend and process verification request
* @param[in] accid account of the other party
* @param[in] verify_type add friend verification type
* @param[in] msg verification message
* @param[in] cb friend request callback function
* @param[in] json_extension json extension parameter is not required in some cases
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success
* 404: User does not exist
* 500: Unknown error
*/
static bool Request(const std::string &accid, NIMVerifyType verify_type, const std::string &msg, const FriendOptCallback &cb, const std::string& json_extension = "");

• Friend verification method

  Requestfunction, based on theverify_typeparameter, features four operating modes:

  NIMVerifyType enumeration	Description
  kNIMVerifyTypeAdd	Add friend directly
  kNIMVerifyTypeAsk	Request to add as friend, and the verification by the other is required
  kNIMVerifyTypeAgree	Accept another user's friend request
  kNIMVerifyTypeReject	Reject friend request

• Example

c++void OnFriendRequest(int res_code)
{
    //Process the result of adding friends according to res_code
}

void foo()
{
    //Add friend directly
    nim::Friend::Request("id", nim::kNIMVerifyTypeAdd, "", &OnFriendRequest);
    //Request to add as friend
    nim::Friend::Request("id", nim::kNIMVerifyTypeAsk, "Friend request from xx", &OnFriendRequest);
}

Accept or Reject Requests Used to Add Friends

After receiving the system notification of add friend verification request, you can accept or reject the request, for which you can use the API for adding friend and enter kNIMVerifyTypeAgree (accept) or kNIMVerifyTypeReject (reject) in verify_type.

Delete Friend

The friendship will be terminated automatically after deleting the friend. Neither party has the other in its friends list. After you delete your friend, you can still chat with the other.

• API prototype

c++/** @fn static bool Delete(const std::string &accid, const FriendOptCallback &cb, const std::string& json_extension = "")
* Delete friends
* @param[in] accid account of the other party
* @param[in] cb delete friend callback function
* @param[in] json_extension json extension parameter is not required in some cases
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success
* 404: User does not exist
* 500: Unknown error
*/
static bool Delete(const std::string &accid, const FriendOptCallback &cb, const std::string& json_extension = "");

• Example

c++void OnDeleteFriend(int res_code)
{
    if (res_code == kNIMResSuccess)
        //deleted
    else
        //deletion failed
}

void foo()
{
    nim::Friend::Delete("id", &OnDeleteFriend);
}

Notification of Friendship Change

After registering the callback for friend information change vianim::Friend::RegChangeCb, you will be notified once friendship changes. Types of friendship changes include:

• kNIMFriendChangeTypeRequest add friend/process friend request

• kNIMFriendChangeTypeDel delete friend

• kNIMFriendChangeTypeUpdate update friend information

• kNIMFriendChangeTypeSyncList friends list synchronization

• API prototype

c++/** @fn static void RegChangeCb(const FriendChangeCallback &cb, const std::string& json_extension = "")
* (Global callback) Uniformly register callback function for friend change notification (multi-terminal sync of addition, deletion, update, and friends list synchronization)
* @param[in] cb callback function for friend change notification
* @param[in] json_extension json extension parameter is not required in some cases
* @return void No value is returned
*/
static void RegChangeCb(const FriendChangeCallback &cb, const std::string& json_extension = "");

• Example

c++void OnFriendListChange(const nim::FriendChangeEvent& change_event)
{
    switch (change_event.type_)
    {
    case nim::kNIMFriendChangeTypeDel:
    {
        break;
    }
    case nim::kNIMFriendChangeTypeRequest:
    {
        break;
    }
    case nim::kNIMFriendChangeTypeSyncList:
    {
        break;
    }
    case nim::kNIMFriendChangeTypeUpdate:
    {
        break;
    }
    default:
        break;
    }
}

void foo()
{
    // register with SDK to observe friends list change
    nim::Friend::RegChangeCb(&OnFriendListChange);
}

Get friendship according to user account

• API prototype

c++/** @fn static void GetFriendProfile(const std::string &accid, const GetFriendProfileCallback& cb, const std::string& json_extension = "")
* Get friend information
* @param[in] accid account of the other party
* @param[in] cb Get friend information callback function
* @param[in] json_extension json extension parameter is not required in some cases
* @return void No value is returned
*/
static void GetFriendProfile(const std::string &accid, const GetFriendProfileCallback& cb, const std::string& json_extension = "");

Update friendship

Currently only updating friend's remark is supported

• API prototype

c++/** @fn static bool Update(const std::string &friend_json, const FriendOptCallback &cb, const std::string& json_extension = "")
* Update friend profile
* @param[in] friend_profile friend profile
* @param[in] cb callback function for friend profile update
* @param[in] json_extension json extension parameter is not required in some cases
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success 
* 404: User does not exist
* 500: Unknown error
*/
static bool Update(const FriendProfile &friend_profile, const FriendOptCallback &cb, const std::string& json_extension = "");

• Example

c++void foo()
{
    nim::FriendProfile profile;
    profile.SetAccId("FRIEND ID");
    profile.SetAlias("ALIAS");
    nim::Friend::Update(profile, nullptr);
}

Blacklist

In CommsEase, blacklist and user relationship are independent of each other, so updating either of the two won't affect the other. When a user is added to the blacklist, you will not receive any message or request from this user. For example, if user A blacklists user B, A will not receive any message from B. But B can read any message sent from A.

Add to/Remove from the Blacklist

• API prototype

c++/** @fn static bool SetBlack(const std::string& accid, bool set_black, const SetBlackCallback& cb, const std::string& json_extension = "")
* Set or revoke blacklist
* @param[in] accid friend's id
* @param[in] set_black set or revoke
* @param[in] json_extension json extension parameter is not required in some cases
* @param[in] cb
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success
* 419: Exceeded the maximum number of blacklist entries 
*/
static bool SetBlack(const std::string& accid, bool set_black, const SetBlackCallback& cb, const std::string& json_extension = "");

• Example

c++void OnSetBlackCb(int res_code, const std::string& accid, bool opt)
{
    //res_code: operation result
    //accid: user ID
    //opt:true-add to blacklist, false-remove from blacklist
}

void foo()
{
    nim::User::SetBlack("accid", true, &OnSetBlackCb);
}

Get Blacklist

• API prototype

c++/** @fn static void GetBlacklist(const GetBlackListCallback& cb, const std::string& json_extension = "")
* Get blacklist
* @param[in] json_extension json extension parameter is not required in some cases
* @param[in] cb
* @return void No value is returned
*/
static void GetBlacklist(const GetBlackListCallback& cb, const std::string& json_extension = "");

• Example

c++void OnGetBlackListCallback(nim::NIMResCode res_code, const std::list<nim::BlackListInfo>& lists)
{
    if (res_code == nim::kNIMResSuccess)
    {
        for (auto& info : lists)
        {
            //Get blacklisted friends from the list
        }
    }
}

void foo()
{
    nim::User::GetBlacklist(&OnGetBlackListCallback);
}

Monitor Blacklist Changes

Local cache is available for blacklist, and will be synced and updated automatically with the server after manual/auto login. Get the current data changes by registering callback of user relationship change notification.

• API prototype

c++/** @fn static void RegSpecialRelationshipChangedCb(const SpecialRelationshipChangedCallback& cb, const std::string& json_extension = "")
* (Global callback) Uniformly register callback function for notification of user attribute change (multi-terminal sync of blacklist, mute list change)
* @param[in] json_extension json extension parameter is not required in some cases
* @param[in] cb
* @return void No value is returned
*/
static void RegSpecialRelationshipChangedCb(const SpecialRelationshipChangedCallback& cb, const std::string& json_extension = "");

• Example

c++void OnMuteBlackEventCallback(const nim::SpecialRelationshipChangeEvent& change_event)
{
    switch (change_event.type_)
    {
    case nim::NIMUserSpecialRelationshipChangeType::kNIMUserSpecialRelationshipChangeTypeMarkBlack:
    {
        //Set or revoke adding to blacklist
        break;
    }
    case nim::NIMUserSpecialRelationshipChangeType::kNIMUserSpecialRelationshipChangeTypeMarkMute:
    {
        //Set or mute message reminder
        break;
    }
    case nim::NIMUserSpecialRelationshipChangeType::kNIMUserSpecialRelationshipChangeTypeSyncMuteAndBlackList:
    {
        //Synchronize blacklist and list of muted members
        break;
    }
    }
}

void foo()
{
    nim::User::RegSpecialRelationshipChangedCb(&OnMuteBlackEventCallback);
}

Message Reminder

CommsEase contains setting option for enabling/disabling reminder for individual user’s message (to unmute/mute that user). Mute and user relationship are mutually independent, so updating either of the two won't affect the other.

Set/mute Message Reminder

• API prototype

c++/** @fn static bool SetMute(const std::string& accid, bool set_mute, const SetMuteCallback& cb, const std::string& json_extension = "")
* Set/mute message reminder
* @param[in] accid friend's id
* @param[in] set_mute set or mute
* @param[in] json_extension json extension parameter is not required in some cases
* @param[in] cb
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success
* 419: Exceeded the maximum number of mute entries 
*/
static bool SetMute(const std::string& accid, bool set_mute, const SetMuteCallback& cb, const std::string& json_extension = "");

• Example

c++void OnSetMuteCb(int res_code, const std::string& accid, bool opt)
{
    //res_code: operation result
    //accid: user ID
    //opt:true-set，false-mute
}

void foo()
{
    nim::User::SetMute("accid", true, &OnSetMuteCb);
}

Get Muted Account List

• API prototype

c++/** @fn static void GetMutelist(const GetMuteListCallback& cb, const std::string& json_extension = "")
* Get muted account list 
* @param[in] json_extension json extension parameter is not required in some cases
* @param[in] cb
* @return bool Return "failure" if the checked parameter does not conform
* @note Error code	200: success
*/
static void GetMutelist(const GetMuteListCallback& cb, const std::string& json_extension = "");

• Example

c++void OnGetMuteListCallback(nim::NIMResCode res_code, const std::list<nim::MuteListInfo>& lists)
{
    if (res_code == nim::kNIMResSuccess)
    {
        for (auto& info : lists)
        {
            //Get muted friends from the list
        }
    }
}

void foo()
{
    nim::User::GetMutelist(&OnGetMuteListCallback);
}

Monitor Messages Reminder Changes

Local cache exists in mute list, and will be synced and updated automatically with the server after manual/auto login. Get the current data changes by registering callback of user relationship change notification via nim::User::RegSpecialRelationshipChangedCb. See "monitoring blacklist changes".