群组功能
群组功能概述
群组功能对应的API为 nim_team_xxx
,提供了普通群 (Normal) 以及高级群 (Advanced) 两种形式的群聊功能。高级群拥有更多的权限操作,两种群聊形式在共有操作上保持了接口一致。推荐 APP 开发时只选择一种群类型进行开发。普通群和高级群在原则上是不能互相转换的,他们的群类型在创建时就已经确定。目前版本中,高级群覆盖普通群的全部功能,推荐使用高级群进行开发。
- 普通群
开发手册中所提及的普通群都等同于DEMO中的讨论组。普通群(讨论组)没有权限操作,适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对群进行增减员操作,普通成员只能对群进行增员操作。在添加新成员的时候,并不需要经过对方同意。
- 高级群
高级群在权限上有更多的限制,权限分为群主、管理员、以及群成员。在添加成员的时候需要对方接受邀请。高级群的群成员资料提供了实时同步功能,并提供了群开关设置字段、第三方扩展字段(仅负责存储和透传)和第三方服务器扩展字段(该配置项只能通过服务器接口设置,对客户端只读)。
- 群操作权限对比
群操作 | 普通群 | 高级群 |
---|---|---|
邀请成员 | 任何人 | 群主、管理员 |
踢出成员 | 群主 | 群主、管理员(管理员之间无法互相踢) |
解散群 | 群主 | 群主 |
退群 | 任何人 | 管理员、普通成员 |
处理入群申请 | / | 群主、管理员 |
更改自己的群昵称 | / | 任何人 |
更改他人群昵称 | / | 群主、管理员 |
更改群名称 | 任何人 | 群主、管理员 |
更改群公告 | / | 群主、管理员 |
更改群介绍 | / | 群主、管理员 |
更新验证方式 | / | 群主、管理员 |
添加(删除)管理员 | / | 群主 |
移交群主 | / | 群主 |
成员禁言 | / | 群主、管理员 |
更新群头像 | / | 群主、管理员 |
NIMTeamType
枚举说明
枚举 | 值 | 说明 |
---|---|---|
kNIMTeamTypeNormal | 0 | 普通群 |
kNIMTeamTypeAdvanced | 1 | 高级群 |
NIMTeamUserType
枚举说明
枚举 | 值 | 说明 |
---|---|---|
kNIMTeamUserTypeNomal | 0 | 普通成员 |
kNIMTeamUserTypeCreator | 1 | 创建者 |
kNIMTeamUserTypeManager | 2 | 管理员 |
kNIMTeamUserTypeApply | 3 | 申请加入用户 |
kNIMTeamUserTypeLocalWaitAccept | 100 | 本地记录等待正在入群的用户 |
群聊消息收发和管理与双人聊天完全相同,仅在消息类型上做了区分,详见消息收发。
群通知事件
- API 介绍
注册该事件监听群信息变更,包括群组的创建、解散、邀请入群、踢出群组等群相关操作的都通过该事件通知给调用者。
nim_team_event_cb_func
参数说明
类型 | 参数 | 说明 |
---|---|---|
int | res_code | 错误码 |
int | notification_id | 通知类型,详见NIMNotificationId |
string | tid | 群id |
string | result | 通知内容,详见TeamEvent 说明 |
string | json_extension | 扩展字段,预留 |
void* | user_data | APP的自定义用户数据,SDK只负责传回给回调函数,不做任何处理 |
TeamEvent
说明
类型 | 参数 | 说明 |
---|---|---|
NIMNotificationId | kNIMNotificationKeyId | 群通知类型,包括创建群、解散群等等(详见NIMNotificationId |
string | kNIMNotificationKeyData | 通知内容,json 字符串,字段定义详见TeamNotificationData |
TeamNotificationData
说明
类型 | 参数 | 说明 |
---|---|---|
string | kNIMNotificationKeyDataIds | 通知可能涉及到的群成员ID,比如增加管理员操作可以添加多个账号,收到通知时ids对应其多个账号,json array |
string | kNIMNotificationKeyDataInvalidIds | 通知可能涉及到的失效的群成员ID,比如邀请入群的成员的群数量超限导致当次邀请失败,json array |
string | kNIMNotificationKeyDataId | 通知对单个成员操作的id,比如禁言群成员,移交群主等操作的被操作方id |
NIMTeamInfo | kNIMNotificationKeyTeamInfo | 群信息数据 |
TeamMemberProperty | kNIMNotificationKeyTeamMember | 群成员信息,比如修改自己的群成员属性时,通过kNIMNotificationIdTeamSyncUpdateMemberProperty 通知类型来通知 |
string | kNIMNotificationKeyUserNameCards | 通知可能涉及到的群成员的用户名片,json array |
int | kNIMNotificationKeyDataMute | 通知禁言,1:禁言 0: 解除禁言 |
string | kNIMNotificationKeyDataAttach | 扩展字段,目前仅kick和invite事件可选(暂不支持) |
TeamEvent
解析示例
void ParseTeamEvent(Json::Value values)
{
Json::Value data = values[kNIMNotificationKeyData];
if (values.isObject())
{
//群信息
if (data.isMember(kNIMNotificationKeyTeamInfo))
{
//参考群信息解析
ParseTeamInfo(data[kNIMNotificationKeyTeamInfo]);
...
}
//操作者和被操作者用户名片
Json::Value name_cards = data[kNIMNotificationKeyUserNameCards];
if (!name_cards.empty() && name_cards.isArray())
{
//参考用户资料托管部分的数据解析
//ParseNamesCard()
...
}
switch (notification_id)
{
case kNIMNotificationIdTeamKick:
case kNIMNotificationIdTeamInvite:
case kNIMNotificationIdTeamAddManager:
case kNIMNotificationIdTeamRemoveManager:
case kNIMNotificationIdLocalCreateTeam:
{
//ids
Json::Value ids = data[kNIMNotificationKeyDataIds];
int len = ids.size();
for (int i = 0; i < len; i++)
{
char* uid = ids[i].asString();
...
}
//判断是否存在此字段
if (data.isMember(kNIMNotificationKeyDataInvalidIds))
{
ids = data[kNIMNotificationKeyDataInvalidIds];
int len = ids.size();
for (int i = 0; i < len; i++)
{
char* invalidUid = ids[i].asString();
...
}
}
}
break;
case kNIMNotificationIdTeamLeave:
case kNIMNotificationIdTeamApplyPass:
case kNIMNotificationIdTeamInviteAccept:
case kNIMNotificationIdLocalRejectApply:
case kNIMNotificationIdLocalRejectInvite:
{
//id
char* id = data[kNIMNotificationKeyDataId].asString();
...
}
break;
case kNIMNotificationIdTeamUpdate:
case kNIMNotificationIdTeamSyncCreate:
case kNIMNotificationIdLocalGetTeamInfo:
case kNIMNotificationIdTeamDismiss:
case kNIMNotificationIdLocalApplyTeam:
case kNIMNotificationIdLocalGetTeamList:
break;
case kNIMNotificationIdTeamOwnerTransfer:
{
bool opt = data[kNIMNotificationKeyDataLeave].asBool();
char* id = data[kNIMNotificationKeyDataId].asString();
...
}
break;
case kNIMNotificationIdTeamMemberChanged:
case kNIMNotificationIdLocalUpdateOtherNick:
case kNIMNotificationIdTeamSyncUpdateMemberProperty:
case kNIMNotificationIdLocalUpdateMemberProperty:
{
//群成员信息解析,参考ParseTeamMemberProperty
ParseTeamMemberProperty(data[kNIMNotificationKeyTeamMember]);
...
}
break;
case kNIMNotificationIdTeamMuteMember:
case kNIMNotificationIdLocalMuteMember:
{
bool mute = data[kNIMNotificationKeyDataMute].asInt() == 1;
char* id = data[kNIMNotificationKeyDataId].asString();
...
}
break;
default:
break;
}
}
}
NIMNotificationId
枚举类型说明
枚举 | 值 | 说明 |
---|---|---|
kNIMNotificationIdTeamInvite | 0 | 普通群拉人,{“tinfo”:team_info,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]},json串对应NIMTeamEvent 字段的数据,下同 |
kNIMNotificationIdTeamKick | 1 | 普通群踢人,{“tinfo”:tinfo,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamLeave | 2 | 退出群,{"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamUpdate | 3 | 群信息更新,{"tinfo":tinfo,"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamDismiss | 4 | 群解散,{"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamApplyPass | 5 | 高级群申请加入成功,{"tinfo":tinfo,"id":"a1","uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamOwnerTransfer | 6 | 高级群移交群主,{"id":"a1","uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamAddManager | 7 | 增加管理员,{"ids":["a1","a2"],"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamRemoveManager | 8 | 移除管理员,{"ids":["a1","a2"],"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamInviteAccept | 9 | 高级群接受邀请进群,{"tinfo":tinfo,"id":"a1","uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdTeamMuteMember | 10 | 禁言/解禁群成员,{"uinfos":["uinfo1", "uinfo2"],“tinfo”:tinfo,"id":"a1","mute":1-禁言,0-解禁} |
kNIMNotificationIdNetcallMiss | 101 | 未接电话(暂不支持),{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471} |
kNIMNotificationIdNetcallBill | 102 | 话单(暂不支持),{"calltype":2,"channel":6146077129466446197,"duration":8,"ids":["id1","id2"],"time":1430995117398} |
kNIMNotificationIdTeamSyncCreate | 1000 | 创建群{"tinfo" : tinfo} |
kNIMNotificationIdTeamMemberChanged | 1001 | 群成员变更{"team_member" : team_member_info} |
kNIMNotificationIdTeamSyncUpdateMemberProperty | 1002 | 同步通知:修改自己的群属性{"team_member" : team_member_info} 目前只需kNIMTeamUserKeyNick和kNIMTeamUserKeyBits,接收到该通知时,MemberInfo 字段会通知更新的信息 |
kNIMNotificationIdLocalCreateTeam | 2000 | 本地操作创建群 {"ids" : ["a1", "a2"]} |
kNIMNotificationIdLocalApplyTeam | 2001 | 本地操作申请加入群 |
kNIMNotificationIdLocalRejectApply | 2002 | 本地操作拒绝申请 {"id":"a1"} |
kNIMNotificationIdLocalRejectInvite | 2003 | 本地操作拒绝邀请 {"id":"a1"} |
kNIMNotificationIdLocalUpdateMemberProperty | 2004 | 本地操作更新群成员属性 |
kNIMNotificationIdLocalUpdateOtherNick | 2005 | 本地操作更新他人nickname |
kNIMNotificationIdLocalGetTeamInfo | 2006 | 普通群踢人,{“tinfo”:tinfo,"ids":["a1", "a2"],"uinfos":["uinfo1", "uinfo2"]} |
kNIMNotificationIdLocalGetTeamList | 2007 | 本地操作获取群成员信息 |
kNIMNotificationIdLocalMuteMember | 2008 | 本地操作对群成员禁言 |
kNIMNotificationIdLocalNetcallReject | 3103 | 拒绝电话(暂不支持),{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471} |
kNIMNotificationIdLocalNetcallNoResponse | 3104 | 无应答,未接通电话(暂不支持),{"calltype":1,"channel":6146078138783760761,"from":"id1","ids":["id1","id2"],"time":1430995380471} |
- API 原型
nim_team_reg_team_event_cb(const char *json_extension, nim_team_event_cb_func cb, const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 异步通知回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//解析result示例
Json::Reader reader;
Json::Value values;
if (reader.parse(result, values) && values.isObject())
{
//解析通知内容,参考ParseTeamEvent
ParseTeamEvent(values);
...
}
...
}
//注册事件监听
nim_team_reg_team_event_cb(0,my_nim_team_event_cb_func,0);
//不需要时,取消事件监听
nim_team_reg_team_event_cb(0,0,0);
获取群组
NIM SDK 在程序启动时会对本地群信息进行同步,所以只需要调用本地缓存接口获取群就可以了。 SDK 提供了批量获取自己的群接口、以及根据单个群 id 查询的接口。同样 SDK 也提供了远程获取群信息的接口。 群信息。
TeamInfo
群信息字段说明
类型 | 参数 | 说明 |
---|---|---|
string | kNIMTeamInfoKeyID | 群组id |
string | kNIMTeamInfoKeyName | 群组名称 |
NIMTeamType | kNIMTeamInfoKeyType | 群组类型,分高级群和普通群,详见NIMTeamType |
string | kNIMTeamInfoKeyCreator | 群组的拥有者或创建者 |
int | kNIMTeamInfoKeyLevel | 群组等级 |
string | kNIMTeamInfoKeyProperty | 群组属性预留扩展字段,长度限制:6000字符 |
int | kNIMTeamInfoKeyValidFlag | 此群组是否有效,1为有效,0为无效 |
int | kNIMTeamInfoKeyMemberCount | 群成员数量 |
int64_t | kNIMTeamInfoKeyListTime | 群成员列表最新更新时间戳(毫秒) |
int64_t | kNIMTeamInfoKeyCreateTime | 群组创建时间戳(毫秒) |
int64_t | kNIMTeamInfoKeyUpdateTime | 群信息最新更新时间戳(毫秒) |
bool | kNIMTeamInfoKeyMemberValid | 该群的群成员列表是否还有效,1:有效 0: 无效 |
string | kNIMTeamInfoKeyIntro | 群组简介 |
string | kNIMTeamInfoKeyAnnouncement | 群公告 |
NIMTeamJoinMode | kNIMTeamInfoKeyJoinMode | 入群模式,0-不用验证 1-需要验证 2-拒绝所有人入群(仅高级群) |
string | kNIMTeamInfoKeyCustom | 第三方扩展字段,仅负责存储和透传 |
string | kNIMTeamInfoKeyServerCustom | 服务器预留扩展字段(该配置项只能通过服务器接口设置,对客户端只读)(仅高级群) |
string | kNIMTeamInfoKeyIcon | 群头像 |
NIMTeamBeInviteMode | kNIMTeamInfoKeyBeInviteMode | 被邀请人同意方式,属性本身只有群主管理员可以修改 ,0-需要同意(默认),1-不需要同意(仅高级群) |
NIMTeamInviteMode | kNIMTeamInfoKeyInviteMode | 谁可以邀请他人入群,属性本身只有群主管理员可以修改,0-管理员(默认),1-所有人(仅高级群) |
NIMTeamUpdateInfoMode | kNIMTeamInfoKeyUpdateInfoMode | 谁可以修改群资料,属性本身只有群主管理员可以修改,0-管理员(默认),1-所有人(仅高级群) |
NIMTeamUpdateCustomMode | kNIMTeamInfoKeyUpdateCustomMode | 谁可以更新群自定义属性,属性本身只有群主管理员可以修改(仅高级群) |
bool | kNIMTeamInfoKeyMuteAll | 群全员禁言标记 0:未禁言,1:禁言(仅高级群)(暂不支持) |
注意:当用户退出群或被踢出群或群解散后,
kNIMTeamInfoKeyMemberValid
值为false,对于当前用户而言,此群已不再是此用户的有效群。
TeamInfo
解析示例
//解析群信息内容
void ParseTeamInfo(const Json::Value& team_info)
{
if (team_info.isObject())
{
NIMTeamType type= (NIMTeamType)team_info[kNIMTeamInfoKeyType].asInt();
char* teamID = team_info[kNIMTeamInfoKeyID].asString();
char* ownerID = team_info[kNIMTeamInfoKeyCreator].asString();
char* name = team_info[kNIMTeamInfoKeyName].asString();
char* intro = team_info[kNIMTeamInfoKeyIntro].asString();
char* announcement = team_info[kNIMTeamInfoKeyAnnouncement].asString();
NIMTeamJoinMode joinMode = (NIMTeamJoinMode)team_info[kNIMTeamInfoKeyJoinMode].asInt();
char* serverCustom = team_info[kNIMTeamInfoKeyServerCustom].asString();
int64_t createTimetag = team_info[kNIMTeamInfoKeyCreateTime].asUInt64();
int64_t updateTimetag = team_info[kNIMTeamInfoKeyUpdateTime].asUInt64();
char* custom = team_info[kNIMTeamInfoKeyCustom].asString();
uint memberCount = team_info[kNIMTeamInfoKeyMemberCount].asUInt();
char* Property = team_info[kNIMTeamInfoKeyProperty].asString();
bool isValid = team_info[kNIMTeamInfoKeyValidFlag].asUInt() == 0 ? false : true);
bool isMemberValid = team_info[kNIMTeamInfoKeyMemberValid].asUInt() == 0 ? false : true);
char* icon = team_info[kNIMTeamInfoKeyIcon].asString();
NIMTeamBeInviteMode beInviteMode = team_info[kNIMTeamInfoKeyBeInviteMode].asInt();
NIMTeamInviteMode inviteMode = team_info[kNIMTeamInfoKeyInviteMode].asInt();
NIMTeamUpdateInfoMode UpdateInfoMode = team_info[kNIMTeamInfoKeyUpdateInfoMode].asInt();
NIMTeamUpdateCustomMode UpdateCustomMode = team_info[kNIMTeamInfoKeyUpdateCustomMode].asInt();
bool isAllMemberMute = team_info[kNIMTeamInfoKeyMuteAll].asInt();
...
}
}
TeamMemberProperty
群成员信息字段说明
类型 | 参数 | 说明 |
---|---|---|
string | kNIMTeamUserKeyID | 群组id |
string | kNIMTeamUserKeyAccID | 群成员账号 |
NIMTeamUserType | kNIMTeamUserKeyType | 群成员类型,详见NIMTeamUserType |
int64_t | kNIMTeamUserKeyCreateTime | 入群时间戳 |
int64_t | kNIMTeamUserKeyUpdateTime | 群成员信息更新时间戳 |
bool | kNIMTeamUserKeyValidFlag | 群成员是否有效,如果已退群等 则为false |
string | kNIMTeamUserKeyNick | 群成员昵称 |
int64_t | kNIMTeamUserKeyBits | 配置属性,当前仅用来设置消息提醒,1:提醒 默认为0 |
string | kNIMTeamUserKeyCustom | 自定义第三方扩展信息 |
bool | kNIMTeamUserKeyMute | 是否禁言,true:禁言,false:取消禁言(默认) |
TeamMemberProperty
解析示例
//解析群信息内容
void ParseTeamMemberProperty(const Json::Value& prop)
{
if (prop.isObject())
{
char* teamID = prop[kNIMTeamUserKeyID].asString();
char* userID = prop[kNIMTeamUserKeyAccID].asString();
NIMTeamUserType type = (NIMTeamUserType)prop[kNIMTeamUserKeyType].asUInt();
char* nick = prop[kNIMTeamUserKeyNick].asString();
int64_t bits = prop[kNIMTeamUserKeyBits].asUInt64();
bool isValid = prop[kNIMTeamUserKeyValidFlag].asUInt() == 1;
int64_t createTimetag = prop[kNIMTeamUserKeyCreateTime].asUInt64();
int64_t updateTimetag = prop[kNIMTeamUserKeyUpdateTime].asUInt64();
bool isMute = prop[kNIMTeamUserKeyMute].asUInt() == 1;
char* custom = prop[kNIMTeamUserKeyCustom].asString();
...
}
}
本地获取群列表
SDK最新版本在当用户不在该群组或该群组已经解散时,本地数据库不再清除该缓存的数据,所以同时提供了查询有效群和查询所有群(包含无效群)的接口。
1. 获取有效群信息列表
- API 原型
void nim_team_query_all_my_teams_info_async(const char *json_extension,nim_team_query_all_my_teams_info_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 通知结果回调 |
json_extension | 扩展字段,可选,用于查询包含无效群,格式如:{"include_invalid":1},默认查询有效群 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_all_my_teams_info_cb_func(int team_count, const char *result, const char *json_extension, const void *user_data)
{
//解析result
Json::Value json;
Json::Reader reader;
if (reader.parse(result, json) && json.isArray())
{
int len = json.size();
for (int i = 0; i < len; i++)
{
//解析为TeamInfon内容,参考ParseTeamInfo
参考ParseTeamInfo(json[i]);
...
}
...
}
}
//获取有效群信息列表
nim_team_query_all_my_teams_info_async(0,my_nim_team_query_all_my_teams_info_cb_func,0);
//获取所有群信息列表,包括无效群
Json::FastWriter fw;
Json::Value param;
param["include_invalid"] = true;
nim_team_query_all_my_teams_info_async(0,my_nim_team_query_all_my_teams_info_cb_func,fw.write(param));
2. 获取本人所在群列表
- API 介绍
仅获取本人所在群的群id列表,
- API 原型
void nim_team_query_all_my_teams_async(const char *json_extension,nim_team_query_all_my_teams_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_all_my_teams_cb_func(int team_count, const char *result, const char *json_extension, const void *user_data)
{
//result:json 数组 ["tid1","tid2"]
...
}
//获取本人所在群id列表
nim_team_query_all_my_teams_async(0,my_nim_team_query_all_my_teams_cb_func,0);
获取群信息
SDK提供了同步和异步两个版本来获取本地的群信息,也提供了直接获取云端的群信息的接口。
1. 获取本地群信息(同步版本)
- API 原型
char* nim_team_query_team_info_block(const char *tid);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
- 示例
//获取本地群信息
char* tid = "1243354";
char* tinfo = nim_team_query_team_info_block(tid);
//解析群信息:ParseTeamInfo
if (tinfo != null)
{
Json::Reader reader;
Json::Value values;
if (reader.parse(tinfo,valuses) && values.isObject())
{
//参考ParseTeamInfo
ParseTeamInfo(values);
...
}
}
free(tinfo);//需要释放内存
2.获取本地群信息(异步版本)
- API 原型
void nim_team_query_team_info_async(const char *tid,const char *json_extension,nim_team_query_team_info_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_team_info_cb_func(const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//解析群信息
Json::Reader reader;
Json::Value values;
if (reader.parse(result,valuses) && values.isObject())
{
//参考ParseTeamInfo
ParseTeamInfo(values);
...
}
...
}
//获取本地群信息
char* tid = "1243354";
nim_team_query_team_info_async(tid,0,my_nim_team_query_team_info_cb_func,0);
3.获取云端群信息
- API 原型
void nim_team_query_team_info_online_async(const char *tid, const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
...
}
//获取云端群信息
char* tid = "1243354";
nim_team_query_team_info_online_async(tid, 0,my_nim_team_event_cb_func,0);
获取云端禁言列表
- API 原型
void 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);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_mute_list_cb_func(int res_code, int member_count, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//result:返回TeamMemberProperty的数组
Json::Value values;
Json::Reader reader;
if (reader.parse(result, values) && values.isArray())
{
auto size = values.size();
for (int i = 0; i < size; i++)
{
//解析为TeamMemberProperty定义数据,参考ParseTeamMemberProperty
ParseTeamMemberProperty(values[i]);
...
}
}
...
}
//获取云端的群禁言列表
char* tid = "1243354";
nim_team_query_mute_list_online_async(tid,0,my_nim_team_query_mute_list_cb_func,0);
群成员信息
SDK支持获取群成员列表信息,也支持获取单个群成员的信息。获取单个群成员信息分别提供同步版本和异步版本的接口,以方便开发者调用。
获取群成员列表
SDK支持查询指定群的有效群成员列表,也支持查询已经退出群的本地群成员。
- API 原型
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);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
include_user_info | 是否获取群成员信息,如果为false,返回的数据仅kNIMTeamUserKeyAccID ,kNIMTeamUserKeyID 有效 |
cb | 通知结果回调 |
json_extension | 扩展字段,可选,用于查询包含无效群成员,格式如:{"include_invalid":1},默认查询有效群 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_team_members_cb_func(const char *tid,int member_count,bool include_user_info,const char *result,const char *json_extension,const void *user_data)
{
//result:返回TeamMemberProperty的数组
Json::Value values;
Json::Reader reader;
if (reader.parse(result, values) && values.isArray())
{
auto size = values.size();
for (int i = 0; i < size; i++)
{
//解析为TeamMemberProperty定义数据,参考ParseTeamMemberProperty
ParseTeamMemberProperty(values[i]);
...
}
}
...
}
//获取群有效群成员信息
char* tid = "1243354";
nim_team_query_team_members_async(tid,0,my_nim_team_query_team_members_cb_func,0);
//获取所有群成员列表,包括无效群成员
Json::FastWriter fw;
Json::Value param;
param["include_invalid"] = 1;
nim_team_query_team_members_async(tid,0,my_nim_team_query_team_members_cb_func,fw.write(param));
获取群成员信息
1. 获取群成员信息(同步版本)
- API 原型
char *nim_team_query_team_member_block(const char *tid, const char *user_id);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
user_id | 所要获取的群成员id |
- 示例
//获取群成员test1信息
char* tid = "1243354";
char* uid = "test1";
char* tinfo = nim_team_query_team_member_block(tid,uid);
Json::Value values;
Json::Reader reader;
if (reader.parse(tinfo, values) && values.isObject())
{
//解析为TeamMemberProperty定义数据,参考ParseTeamMemberProperty
ParseTeamMemberProperty(values);
...
}
free(tinfo);//需要外部释放
2.获取群成员信息(异步版本)
- API 原型
void nim_team_query_team_member_async(const char *tid,const char *user_id,const char *json_extension,nim_team_query_team_member_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 所要获取的群id |
user_id | 所要获取的群成员id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_query_team_member_cb_func(const char *tid, const char *user_id,const char *result,const char *json_extension,const void *user_data)
{
Json::Value values;
Json::Reader reader;
if (reader.parse(result, values) && values.isObject())
{
//解析为TeamMemberProperty定义数据,参考ParseTeamMemberProperty
ParseTeamMemberProperty(values);
...
}
...
}
//获取群成员test1信息
char* tid = "1243354";
char* uid = "test1";
nim_team_query_team_member_async(tid,uid,0,my_nim_team_query_team_member_cb_func,0);
创建群组
创建群组可分为普通群和高级群,目前版本的高级群覆盖了所有的普通群功能。TeamInfo 包含群组的详细信息,通过设置该对象可以指定群类型,群组权限,群资料等信息;如果设置了 invitation_postscript
,会发送给群中的每个成员。
- API 原型
void nim_team_create_team_async(const char *team_info,const char *jsonlist_uids,const char *invitation_postscript,const char *json_extension, nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
team_info | 所创建群的基本信息,如群名,群公告等等 |
jsonlist_uids | 创建群组时同时需要加入群的用户账号,不包括自己账号,系统自动会发送邀请给ids 所有成员 |
invitation_postscript | 邀请附言信息 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试账号test1,test2为例
Json::FastWriter fw;
Json::Value ti;
ti[kNIMTeamInfoKeyName] = "teamName";
ti[kNIMTeamInfoKeyAnnouncement] = "群公告";
ti[kNIMTeamInfoKeyIntro] = "群简介";
ti[kNIMTeamInfoKeyType] = kNIMTeamTypeAdvanced;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");
nim_team_create_team_async(fw.write(ti), fw.write(ids), "邀请附言信息",0, my_nim_team_event_cb_func,0);
加入群组
用户可以通过被动接受邀请和主动加入两种方式进入群组。
邀请用户入群
- API 介绍
请求完成后,如果是普通群,被邀请者将直接入群;如果是高级群,云信服务器会下发一条系统消息到目标用户,目标用户可以选择同意或者拒绝入群。
- API 原型
void nim_team_invite_async(const char *tid,const char *jsonlist_uids,const char *invitation_postscript,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
jsonlist_uids | 创建群组时同时需要加入群的用户账号,不包括自己账号 |
invitation_postscript | 邀请附言信息,如果不为空,此信息会通知给被邀请的好友 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试账号test1,test2为例
char* tid = "1231232";
Json::FastWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");
nim_team_invite_async(tid,fw.write(ids),0,"附言信息",0,my_nim_team_event_cb_func,0);
注意:普通群需要在邀请好友入群后,同时给这个群发一条消息,好友才会收到邀请通知。
收到通知后,高级群用户可以进行以下操作:
- 同意群邀请(仅限高级群):
void nim_team_accept_invitation_async(const char *tid,const char *invitor,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
代码示例
//以测试群1231232,邀请者账号testAccount为例
char* tid = "1231232";
char* invitor_uid = "testAccount";//填写邀请方的id
nim_team_accept_invitation_async(tid, invitor_uid, 0,my_nim_team_event_cb_func,0);
- 拒绝群邀请(仅限高级群):
void nim_team_reject_invitation_async(const char *tid,const char *invitor,const char *reason, const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
代码示例
//以测试群1231232,邀请者账号testAccount为例
char* tid = "1231232";
char* invitor_uid = "testAccount";//填写邀请方的id
nim_team_reject_invitation_async(tid, invitor_uid, "拒绝原因", 0,my_nim_team_event_cb_func,0);
用户主动申请入群
- API 介绍
发送请求后,云信服务器会下发一条系统消息给群管理员,管理员可以选择通过或者拒绝申请。仅高级群支持。
- API 原型
void nim_team_apply_join_async(const char *tid,const char *reason,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
reason | 申请附言信息,如果不为空,此信息会通知给被群管理人员 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232为例
cha* tid = "1231232";
nim_team_apply_join_async(tid, "申请附言",0,my_nim_team_event_cb_func,0);
群管理人员可以进行一下操作:
- 通过申请(仅限高级群):
void nim_team_pass_join_apply_async(const char *tid,const char *applicant_id,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
代码示例:
//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1";//申请者的账号
nim_team_pass_join_apply_async(tid, uid,0,my_nim_team_event_cb_func,0);
- 拒绝申请(仅限高级群):
void nim_team_reject_join_apply_async(const char *tid,const char *applicant_id,const char *reason,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
代码示例:
//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1";//申请者的账号
char* reason = "因为你不够美";//拒绝理由
nim_team_reject_join_apply_async(tid, uid, reason,0,my_nim_team_event_cb_func,0);
退出群组
退出群组包括主动退出群组和被动退出。群管理员和群主都拥有踢出群的权限。被踢出群后,会收到系统通知,通过群通知事件通知给用户。
- API 原型
void nim_team_leave_async(const char *tid,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232为例
char* tid = "1231232";
nim_team_leave_async(tid,0,my_nim_team_event_cb_func,0);
解散群
高级群群主拥有解散群的权限,其他成员均没有此权限。仅高级群支持。
- API 原型
void nim_team_dismiss_async(const char *tid,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232为例
char* tid = "1231232";
nim_team_dismiss_async(tid,0,my_nim_team_event_cb_func,0);
踢人出群
群主可以踢出任何群成员,高级群管理员可以踢出普通群成员。
- API 原型
void nim_team_kick_async(const char *tid,const char *jsonlist_uids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
jsonlist_uids | 被踢出的群成员id集合 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FastWriter fw; //序列化json
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");
nim_team_kick_async(tid, fw.write(ids), 0,my_nim_team_event_cb_func,0);
群成员禁言
支持管理员和群主对普通成员的禁言、解除禁言操作。
- API 原型
void 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);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
member_id | 禁言/解除禁言的群成员id |
set_mute | 是否禁言,true:禁言,false:解除禁言 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1");
nim_team_mute_member_async(tid, uid, true, 0,my_nim_team_event_cb_func,0);
编辑群组资料
- API 介绍
普通群成员都可以修改群名等信息,高级群只有管理员才有权限修改。
- API 原型
void nim_team_update_team_info_async(const char *tid,const char *json_info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
json_info | 群信息,详见TeamInfo定义字段,只填入需要修改的字段,不需要修改的不填 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以修改群名称为例
char* tid = "1231232";
Json::FastWriter fw;
Json::Value ti;
ti[kNIMTeamInfoKeyName] = "newTeamName";
ti[kNIMTeamInfoKeyID] = tid;
nim_team_update_team_info_async(tid,fw.write(ti),0,my_nim_team_event_cb_func,0);
修改群成员信息
SDK提供允许管理员修改他人在群内的昵称,也允许用户修改自己在群内的信息
更新本人的群成员资料
- API 介绍
群内成员可以修改本人的资料信息。
- API 原型
void nim_team_update_my_property_async(const char *info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
info | 群信成员息,详见TeamMemberProperty,最好能先通过接口获取本人的完整的群成员信息,然后再将需要修改的字段更新为新的值,kNIMTeamUserKeyID 、kNIMTeamUserKeyAccID 字段必填 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以修改群名称为例
char* tid = "1231232";
//群成员信息最好是先通过接口获取本人的完整的群成员信息,然后再将需要修改的字段更新为新的值,此处仅为示例。
Json::FasterWriter fw;
Json::Value tmi;
tmi[kNIMTeamUserKeyID] = tid;
tmi[kNIMTeamUserKeyNick] = "newNick";
tmi[kNIMTeamUserKeyAccID] = "myUid"; //本人账号;
nim_team_update_my_property_async( fw.write(tmi),0,my_nim_team_event_cb_func,0);
修改其他成员的群昵称
- API 介绍
群管理员和群主可以修改其他成员的群昵称。
- API 原型
void nim_team_update_other_nick_async(const char *info,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
info | 群成员信息,详见TeamMemberProperty,kNIMTeamUserKeyID 、kNIMTeamUserKeyAccID 字段必填,kNIMTeamUserKeyNick 可为空 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以修改群名称为例
char* tid = "1231232";
//群成员信息最好是先通过接口获取完整的群成员信息,然后再将需要修改的字段更新为新的值,此处仅为示例。
Json::FasterWriter fw;
Json::Value tmi;
tmi[kNIMTeamUserKeyID] = tid;
tmi[kNIMTeamUserKeyNick] = "newNick";
tmi[kNIMTeamUserKeyAccID] = "test1"; //账号;
nim_team_update_other_nick_async( fw.write(tmi),0,my_nim_team_event_cb_func,0);
群组权限管理
SDK提供了对高级群的权限管理功能,仅管理员和群主可以进行操作。可以增加,移除管理员,转让群主等。
添加管理员
- API 介绍
将 jsonlist_admin_ids
中包含的账号全部设置为群管理员
- API 原型
void nim_team_add_managers_async(const char *tid,const char *jsonlist_admin_ids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
jsonlist_admin_ids | 群成员账号id集合 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FasterWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");
nim_team_add_managers_async(tmi, fw.write(ids),0,my_nim_team_event_cb_func,0);
移除管理员
- API 介绍
将 managerIdArray
中包含的账号全部移除群管理员身份
- API 原型
void nim_team_remove_managers_async(const char *tid,const char *jsonlist_admin_ids,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
jsonlist_admin_ids | 群成员账号id集合 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232,测试账号test1,test2为例
char* tid = "1231232";
Json::FasterWriter fw;
Json::Value ids; //json array
ids.append("test1");
ids.append("test2");
nim_team_remove_managers_async(tmi, fw.write(ids),0,my_nim_team_event_cb_func,0);
移交群主
- API 介绍
将群主转让给其他群成员。is_leave
为true时,移交成功后,同时退出本群。
- API 原型
void nim_team_transfer_team_async(const char *tid,const char *new_owner,bool is_leave,const char *json_extension,nim_team_opt_cb_func cb,const void *user_data);
- 参数说明
参数 | 说明 |
---|---|
tid | 群id |
new_owner | 新的群主账号id |
is_leave | 是否移交群主成功后退出该群。true:移交群主并退出该群,false:移交群主但不退出本群 |
cb | 通知结果回调 |
json_extension | 扩展字段,预留 |
user_data | APP的自定义用户数据,SDK只负责传回给回调函数cb,不做任何处理 |
- 示例
void my_nim_team_event_cb_func(int res_code, int notification_id, const char *tid, const char *result, const char *json_extension, const void *user_data)
{
//同nim_team_reg_team_event_cb
...
}
//以测试群1231232,测试账号test1
char* tid = "1231232";
char* newOwnerId = "test1";
nim_team_transfer_team_async(tid, newOwnerId,true,0,my_nim_team_event_cb_func,0);


此文档对你是否有帮助

