Group Members
Update time: 2023/03/24 02:49:55
NIM SDK can query users, add or remove group members, and manage roles. All members are categorized into group owners, administrators, and regular members by permission.
How it works
The nim::Team
class provides methods used to manage group members with member privilege management.
A group can have members of three roles, group owner (kNIMTeamUserTypeCreator
), administrator (kNIMTeamUserTypeManager
) and regular member (kNIMTeamUserTypeNomal
). For more information, see NIMTeamUserType
.
- The group owner is the group creator by default, and can be transferred by calling the
TransferTeamAsync
method. - Administrators are assigned by the group owner, and the group owner add administrators using
AddManagersAsync
. - After a user join the group, the user becomes regular member by default. The user can request other roles from the group owner.
NIMTeamUserType
also contains thekNIMTeamUserTypeApply
andkNIMTeamUserTypeLocalWaitAccept
types indicating the users that has sent join requests for approval.
The nim_team
header file defines functions used to manage group members with member privilege management.
A group can have members of three roles, group owner (kNIMTeamUserTypeCreator
), administrator (kNIMTeamUserTypeManager
) and regular member (kNIMTeamUserTypeNomal
).
- The group owner is the group creator by default, and can be transferred by calling the
nim_team_transfer_team_async
function. - Administrators are assigned by the group owner, and the group owner add administrators using
nim_team_add_managers_async
. - After a user join the group, the user becomes regular member by default. The user can request other roles from the group owner.
NIMTeamUserType
also contains thekNIMTeamUserTypeApply
andkNIMTeamUserTypeLocalWaitAccept
types indicating the users that has sent join requests for approval.
Prerequisites
- The group is created and the user is in the group. For more information, see Manage groups。
- Listeners for group events are registered. For more information, see [Listeners for group events](https://doc.yunxin.163.com/messaging/docs/Tc4NzcyNDg?platform=pc#Listeners for group events).
Manage administrators
Add administrators
If a member leaves a group. all group members will receive a notification of kNIMMessageTypeNotification
and the trigger event is kNIMNotificationIdTeamAddManager
.
Only the group owner have the permission to add administrators.
Add an administrator by calling the AddManagersAsync
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
ids | Accounts to be assigned administrator. |
json_extension | Custom extension field. |
cb | Callback for adding an administrator. |
Sample code:
void OnTeamEventCallback(const nim::TeamEvent& result)
{
···
}
foo()
{
std::list<std::string> uids_list;
uids_list.push_back("user_id");
nim::Team::AddManagersAsync("tid_", uids_list, &OnTeamEventCallback);
}
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
802 | No permissions |
803 | Group does not exist |
805 | Invalid group type |
Add an administrator by calling the nim_team_add_managers_async
function.
Sample code:
void CallbackTeamOperate(int error, int team_operate, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
if (error == kNIMResSuccess)
{
...
}
else
{
...
}
}
typedef void(*nim_team_add_managers_async)(const char *tid, const char *jsonlist_admin_ids, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);
void foo()
{
Json::Value values;
values.append("user_id");
nim_team_add_managers_async func = (nim_team_add_managers_async) GetProcAddress(hInst, "nim_team_add_managers_async");
func("tid", values.toStyledString().c_str(), nullptr, &CallbackTeamOperate, nullptr);
}
Remove an administrator
If a member leaves a group. all group members will receive a notification of kNIMMessageTypeNotification
and the trigger event is kNIMNotificationIdTeamRemoveManager
.
Only the group owner has the permission to remove administrators.
Remove an administrator by calling the RemoveManagersAsync
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
ids | Accounts to be unassigned administrator. |
json_extension | Custom extension field. |
cb | Callback for removing an administrator. |
Sample code:
void OnTeamEventCallback(const nim::TeamEvent& result)
{
···
}
foo()
{
std::list<std::string> uids_list;
uids_list.push_back("user_id");
nim::Team::RemoveManagersAsync("tid_", uids_list, &OnTeamEventCallback);
}
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
802 | No permissions |
803 | Group does not exist |
805 | Invalid group type |
Remove an administrator by calling the nim_team_remove_managers_async
function.
Sample code:
void CallbackTeamOperate(int error, int team_operate, const char *tid, const char* str, const char *json_exten, const void *user_data)
{
if (error == kNIMResSuccess)
{
...
}
else
{
...
}
}
typedef void(*nim_team_remove_managers_async)(const char *tid, const char *jsonlist_admin_ids, const char *json_extension, nim_team_event_cb_func cb, const void* user_data);
void foo()
{
Json::Value values;
values.append("user_id");
nim_team_remove_managers_async func = (nim_team_remove_managers_async) GetProcAddress(hInst, "nim_team_remove_managers_async");
func("tid", values.toStyledString().c_str(), nullptr, &CallbackTeamOperate, nullptr);
}
Edit the member profile
Edit the nickname of a group member
If the group owner or an administrator edits the nickname of a group member, all group members will receive a notification of kNIMMessageTypeNotification
and the trigger event is kNIMNotificationIdTeamSyncUpdateMemberProperty
.
Only the group owner has the permission to edit the nickname of a group member.
Edit the nickname of a group member by calling the UpdateOtherNickAsync
method.
Parameters:
Parameter | Description |
---|---|
prop | Member attribute. For more information, see TeamMemberProperty |
json_extension | Custom extension field. |
cb | Callback for edit the member profile. |
Sample code:
TeamMemberProperty property;
property.member_info_json_value_ = params;
Team::UpdateOtherNickAsync(property, [this](const TeamEvent& team_event) {
// process team event
});
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
802 | No permissions |
803 | Group does not exist |
804 | The user is not a member of a group. |
805 | Invalid group type |
Edit the nickname of a group member by calling the nim_team_update_other_nick_async
function.
Sample code:
static void CallbackFunc(int res_code,
int notification_id,
const char* tid,
const char* result,
const char* json_extension,
const void* user_data) {
// process result
}
const char* team_member_json;
// ...
nim_team_update_other_nick_async(team_member_json, "", &CallbackFunc, NULL);
Edit the personal profile of the current user in a group
If the current user edits the personal profile, all group members will receive a notification of kNIMMessageTypeNotification
and the trigger event is kNIMNotificationIdTeamSyncUpdateMemberProperty
.
Edit the personal profile of the current user in a group by calling the UpdateMyPropertyAsync
method.
Parameters:
Parameter | Description |
---|---|
prop | Member attribute. For more information, see TeamMemberProperty |
json_extension | Custom extension field. |
cb | Callback for edit the member profile. |
Sample code:
TeamMemberProperty property;
property.member_info_json_value_ = params;
Team::UpdateMyPropertyAsync(property, [this](const TeamEvent& team_event) {
// process team event
});
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
803 | Group does not exist |
804 | The user is not a member of a group. |
805 | Invalid group type |
Edit the personal profile of the current user in a group by calling the nim_team_update_my_property_async
function.
Sample code:
static void CallbackFunc(int res_code,
int notification_id,
const char* tid,
const char* result,
const char* json_extension,
const void* user_data) {
// process result
}
const char* team_member_json;
// ...
nim_team_update_my_property_async(team_member_json, "", &CallbackFunc, NULL);
Mute members
Mute all group members
Only the group owner has the permission to mute or unmute all members.
Two type of mute methods are available for muting all members.
- If the mute type
NIMTeamMuteType
is set tokNIMTeamMuteTypeAllMute
, all members, including the group owner and administrators, are muted. - If the value of
NIMTeamMuteType
is set tokNIMTeamMuteTypeNomalMute
, only regular members, not the group owner and administrators, are muted.
Mute or unmute all members by calling the MuteAsync
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
set_mute | Determine whether to mute all group members. true: mute all group members. false: unmute all group members. |
json_extension | Custom extension field. |
cb | Callback for muting all group members. |
Sample code:
Team::MuteAsync("tid", true, [this](const TeamEvent& team_event) {
// process team event
});
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
414 | Invalid parameters |
Mute or unmute all members by calling the nim_team_mute_async
function.
Sample code:
static void CallbackFunc(int res_code,
int notification_id,
const char* tid,
const char* result,
const char* json_extension,
const void* user_data) {
// process result
}
nim_team_mute_async("tid", true, "", &CallbackFunc, NULL);
Mute a specified member
If a member is muted, all group members will receive a notification of kNIMMessageTypeNotification
and the trigger event is kNIMNotificationIdTeamMuteMember
.
Only the group owner can mute a specified member.
Mute a specified member by calling the MuteMemberAsync
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
Member_id | The member to be muted. |
set_mute | Whether to mute the member. true: mute all group members. false: unmute all group members. |
json_extension | Custom extension field. |
cb | Callback for muting all group members. |
Sample code:
void CallbackMuteMember(const TeamEvent& team_event)
{
// Custom implementation
char log[128];
sprintf_s(log, "id: %s, rescode: %d, tid: %s", GetTeamEventCommandText((nim::NIMNotificationId)team_event.notification_id_).c_str(), team_event.res_code_, team_event.team_id_.c_str());
MessageBoxA(nullptr, log, "team_event", 0);
}
void foo(const std::string& team_id, const std::string& account_id, bool mute)
{
Team::MuteMemberAsync(team_id, account_id, bool, &CallbackMuteMember);
}
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
414 | Invalid parameters |
404 | The target member does not exist. |
803 | Group does not exist. |
802 | No permissions |
Mute a specified member by calling the nim_team_mute_member_async
function.
Sample code:
nim_team_mute_member_async(const char *tid, const char *member_id, bool set_mute, const char *json_extension, nim_team_opt_cb_func cb, const void *user_data);
The result returned by the callback nim_team_opt_cb_func:
//nim_cpp_team.cpp
static void CallbackTeamChange(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
if (user_data)
{
Team::TeamEventCallback* cb_pointer = (Team::TeamEventCallback*)user_data;
if (*cb_pointer)
{
TeamEvent team_event;
ParseTeamEvent(res_code, PCharToString(tid), (nim::NIMNotificationId)notification_id, PCharToString(result), team_event);
(*cb_pointer)(team_event);
}
delete cb_pointer;
}
}
Query group members
Query operations may read cached data from the local database or synchronize data from the server. Therefore, such operations may take a long time.
Query the information about group members
Query the information about group members by calling the QueryTeamMembersAsync
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
json_extension | Custom extension field. |
cb | Callback for querying group members. |
Sample code:
void OnGetTeamMembers(const std::string& team_id, int count, const std::list<nim::TeamMemberProperty>& team_member_list)
{
for (const auto& member : team_member_list)
{
···
}
}
foo()
{
nim::Team::QueryTeamMembersAsync("tid_", &OnGetTeamMembers);
}
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
406 | No data change |
802 | No permissions |
Query the information about group members by calling the nim_team_query_team_members_async
function.
You can specify parameters to query details and whether invalid members are included.
Sample code:
void CallbackQueryTeamMembersCb(const char * tid, int count, bool include_user_info, const char* str, const char *json_exten, const void *user_data)
{
//Parse string
}
typedef void(*nim_team_query_team_members_async)(const char *tid, bool include_user_info, const char *json_extension, nim_team_query_team_members_cb_func cb, const void* user_data);
void foo()
{
nim_team_query_team_members_async func = (nim_team_query_team_members_async) GetProcAddress(hInst, "nim_team_query_team_members_async");
func("tid", include_user_info ? true : false, nullptr, &CallbackQueryTeamMembersCb, nullptr);
}
:::
Query a specified member
Query the information about a specified member by group ID and account by calling the QueryTeamMemberAsync
method or synchronous calling the QueryTeamMemberBlock
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
id | Member ID |
json_extension | Custom extension field. |
cb | Callback for querying group members. |
Sample code:
// asynchronous call
void OnQueryMyTeamMemberInfo(const std::string& tid, const nim::TeamMemberProperty& team_member_info)
{
...
}
foo()
{
nim::Team::QueryTeamMemberAsync("tid_","accid_", OnQueryMyTeamMemberInfo);
}
Query the information about a specified member by group ID and account by calling the nim_team_query_team_member_async
function or synchronous calling the nim_team_query_team_member_block
function.
Sample code:
// asynchronous call
void CallbackQueryTeamMember(const char *tid, const char *accid, const char *result, const char *json_extension, const void *user_data)
{
// Parse the result
}
typedef void(*nim_team_query_team_member_async)(const char *tid, const char *accid, const char *json_extension, nim_team_query_team_member_cb_func cb, const void *user_data);
void foo()
{
nim_team_query_team_member_async func = (nim_team_query_team_member_async) GetProcAddress(hInst, "nim_team_query_team_member_async");
func("tid", "accid", nullptr, &CallbackQueryTeamMember, nullptr);
}
Query the information about the current user in all joined groups
Query the information about the current user in all joined groups by calling the QueryMyAllMemberInfosAsync
method.
Parameters:
Parameter | Description |
---|---|
json_extension | Custom extension field. |
cb | Callback for querying group members. |
Sample code:
Team::QueryMyAllMemberInfosAsync([this](int count, const std::list<TeamMemberProperty>& props) {
// process props
});
Query the information about the current user in all joined groups by calling the nim_team_query_my_all_member_infos_async
function.
Sample code:
static void CallbackFunc(int count, const char* result, const char* json_extension, const void* user_data) {
// process result
}
nim_team_query_my_all_member_infos_async("", &CallbackFunc, NULL);
After retrieving the list of all groups you have joined, you can use the bits
field in the member information to determine whether a notification is sent when a group receives a message.
Query the inviter of a group member
If the value is empty, the member joined the group without invitation.
Query the inviter of a group member by calling the QueryTeamMembersInvitor
method.
Parameters:
Parameter | Description |
---|---|
tid | Group ID |
Members | The list of members whose inviters are queried, up to 200 members are queried at a time If the number of group members is less than or equal to 200, it is an optional parameter. If unspecified, all members are queried by default. If the number of group members is greater than 200, multiple calls are required to get the inviters of all group members. |
cb | Callback for querying group members. |
Sample code:
Team::QueryTeamMembersInvitor("tid", {"member1", "member2"},
[this](NIMResCode res_code, const std::string& tid, const std::map<std::string, std::string>& invitor_map) {
// process result
});
Query the inviter of a group member by calling the nim_team_query_members_invitor
function.
Sample code:
static void CallbackFunc(int res_code, const char* tid, const char* result, const void* user_data) {
// process result
}
nim_team_query_members_invitor("tid", "[\"member1\", \"member2\"]", &,NULL)
Query muted members in a group
Query muted members in a group by calling the QueryMuteListOnlineAsync
method.
Sample code:
void CallbackQueryMembersInfoOnline(NIMResCode error_code, const std::string& tid, const std::list<TeamMemberProperty>& team_member_propertys)
{
// Custom implementation
std::string ids;
for (auto iter = team_member_propertys.begin(); iter != team_member_propertys.end(); ++iter)
{
ids.append(iter->GetAccountID());
ids.append(",");
}
char log[1024];
sprintf_s(log, 1024, "tid: %s, member_count: %d\r\nids: %s", tid.c_str(), team_member_propertys.size(),ids.c_str());
MessageBoxA(nullptr, log, "CallbackQueryMembersInfoOnline", 0);
}
void foo(const std::string& team_id)
{
Team::QueryMuteListOnlineAsync(team_id, &CallbackQueryMembersInfoOnline);
}
Error codes
Code | Description |
---|---|
200 | The operation was successful. |
803 | Group does not exist |
802 | No permissions |
Query muted members in a group by calling the nim_team_query_mute_list_online_async
function.
Sample code:
nim_team_query_mute_list_online_async(const char *tid, const char *json_extension, nim_team_query_mute_list_cb_func cb, const void *user_data)
The result returned by the callback nim_team_query_mute_list_cb_func:
//nim_team_helper.cpp
void ParseTeamMemberPropertyJson(const Json::Value& team_member_prop_json, TeamMemberProperty& team_member_property)
{
team_member_property.SetUserType((nim::NIMTeamUserType)team_member_prop_json[nim::kNIMTeamUserKeyType].asInt());
if (team_member_property.GetUserType() != nim::kNIMTeamUserTypeApply && team_member_property.GetUserType() != nim::kNIMTeamUserTypeLocalWaitAccept)
{
team_member_property.SetAccountID(team_member_prop_json[nim::kNIMTeamUserKeyAccID].asString());
team_member_property.SetNick(team_member_prop_json[nim::kNIMTeamUserKeyNick].asString());
team_member_property.SetBits(team_member_prop_json[nim::kNIMTeamUserKeyBits].asUInt64());
team_member_property.SetCreateTimetag(team_member_prop_json[nim::kNIMTeamUserKeyCreateTime].asUInt64());
team_member_property.SetUpdateTimetag(team_member_prop_json[nim::kNIMTeamUserKeyUpdateTime].asUInt64());
team_member_property.SetTeamID(team_member_prop_json[nim::kNIMTeamUserKeyID].asString());
team_member_property.SetValid(team_member_prop_json[nim::kNIMTeamUserKeyValidFlag].asUInt() == 0 ? false : true);
team_member_property.SetCustom(team_member_prop_json[nim::kNIMTeamUserKeyCustom].asString());
team_member_property.SetMute(team_member_prop_json[nim::kNIMTeamUserKeyMute].asInt() == 1);
}
}
//nim_cpp_team.cpp
static void CallbackQueryMembersOnline(int res_code, int count, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
if (user_data)
{
Team::QueryTeamMembersOnlineCallback* cb_pointer = (Team::QueryTeamMembersOnlineCallback*)user_data;
if (*cb_pointer)
{
Json::Value values;
Json::Reader reader;
std::list<TeamMemberProperty> members;
if (reader.parse(PCharToString(result), values) && values.isArray())
{
auto size = values.size();
for (size_t i = 0; i < size; i++)
{
TeamMemberProperty prop;
ParseTeamMemberPropertyJson(values[i], prop);
members.push_back(prop);
}
}
(*cb_pointer)((NIMResCode)res_code, PCharToString(tid), members);
}
delete cb_pointer;
}
}
API reference
API |
Description |
---|---|
AddManagersAsync |
Add an administrator |
RemoveManagersAsync |
Remove an administrator |
UpdateOtherNickAsync |
Edit the nickname of a member. |
UpdateMyPropertyAsync |
Edit the personal profile of the current user in a group. |
MuteMemberAsync |
Mute a specified member. |
MuteAsync |
Mute all group members. |
QueryTeamMembersInvitor |
Query the inviter of a group member. |
QueryTeamMembersAsync |
Query the information about group members. |
QueryTeamMemberAsync |
Query the specified group member information (asynchronous interface). |
QueryTeamMemberBlock |
Query a specified group member by asynchronous call. |
QueryMyAllMemberInfosAsync |
Query the information about the current user in all joined groups. |
QueryMuteListOnlineAsync |
Query muted members in a group. |
API |
Description |
---|---|
nim_team_add_managers_async |
Add an administrator |
nim_team_remove_managers_async |
Remove an administrator |
nim_team_update_other_nick_async |
Edit the nickname of a member. |
nim_team_update_my_property_async |
Edit the personal profile of the current user in a group. |
nim_team_mute_member_async |
Mute a specified member. |
nim_team_mute_async |
Mute all group members. |
nim_team_query_members_invitor |
Query the inviter of a group member. |
nim_team_query_team_members_async |
Query the information about group members. |
nim_team_query_team_member_async |
Query the specified group member information (asynchronous interface). |
nim_team_query_team_member_block |
Query a specified group member by asynchronous call. |
nim_team_query_my_all_member_infos_async |
Query the information about the current user in all joined groups. |
nim_team_query_mute_list_online_async |
Query muted members in a group. |