群组功能

群组功能概述

群组功能对应的API为 nim_team_xxx,提供了普通群 (Normal) 以及高级群 (Advanced) 两种形式的群聊功能。高级群拥有更多的权限操作,两种群聊形式在共有操作上保持了接口一致。推荐 APP 开发时只选择一种群类型进行开发。普通群和高级群在原则上是不能互相转换的,他们的群类型在创建时就已经确定。目前版本中,高级群覆盖普通群的全部功能,推荐使用高级群进行开发。

开发手册中所提及的普通群都等同于DEMO中的讨论组。普通群(讨论组)没有权限操作,适用于快速创建多人会话的场景。每个普通群只有一个管理员。管理员可以对群进行增减员操作,普通成员只能对群进行增员操作。在添加新成员的时候,并不需要经过对方同意。

高级群在权限上有更多的限制,权限分为群主、管理员、以及群成员。在添加成员的时候需要对方接受邀请。高级群的群成员资料提供了实时同步功能,并提供了群开关设置字段、第三方扩展字段(仅负责存储和透传)和第三方服务器扩展字段(该配置项只能通过服务器接口设置,对客户端只读)。

群操作 普通群 高级群
邀请成员 任何人 群主、管理员
踢出成员 群主 群主、管理员(管理员之间无法互相踢)
解散群 群主 群主
退群 任何人 管理员、普通成员
处理入群申请 / 群主、管理员
更改自己的群昵称 / 任何人
更改他人群昵称 / 群主、管理员
更改群名称 任何人 群主、管理员
更改群公告 / 群主、管理员
更改群介绍 / 群主、管理员
更新验证方式 / 群主、管理员
添加(删除)管理员 / 群主
移交群主 / 群主
成员禁言 / 群主、管理员
更新群头像 / 群主、管理员

NIMTeamType枚举说明

枚举 说明
kNIMTeamTypeNormal 0 普通群
kNIMTeamTypeAdvanced 1 高级群

NIMTeamUserType枚举说明

枚举 说明
kNIMTeamUserTypeNomal 0 普通成员
kNIMTeamUserTypeCreator 1 创建者
kNIMTeamUserTypeManager 2 管理员
kNIMTeamUserTypeApply 3 申请加入用户
kNIMTeamUserTypeLocalWaitAccept 100 本地记录等待正在入群的用户

群聊消息收发和管理与双人聊天完全相同,仅在消息类型上做了区分,详见消息收发

群通知事件

注册该事件监听群信息变更,包括群组的创建、解散、邀请入群、踢出群组等群相关操作的都通过该事件通知给调用者。

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}
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. 获取有效群信息列表

 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. 获取本人所在群列表

仅获取本人所在群的群id列表,

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. 获取本地群信息(同步版本)

  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.获取本地群信息(异步版本)

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.获取云端群信息

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);

获取云端禁言列表

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支持查询指定群的有效群成员列表,也支持查询已经退出群的本地群成员。

 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. 获取群成员信息(同步版本)

 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.获取群成员信息(异步版本)

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,会发送给群中的每个成员。

 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);

加入群组

用户可以通过被动接受邀请主动加入两种方式进入群组。

邀请用户入群

请求完成后,如果是普通群,被邀请者将直接入群;如果是高级群,云信服务器会下发一条系统消息到目标用户,目标用户可以选择同意或者拒绝入群。

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);

注意:普通群需要在邀请好友入群后,同时给这个群发一条消息,好友才会收到邀请通知。

收到通知后,高级群用户可以进行以下操作:

代码示例

//以测试群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);

代码示例

//以测试群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);

用户主动申请入群

发送请求后,云信服务器会下发一条系统消息给群管理员,管理员可以选择通过或者拒绝申请。仅高级群支持。

 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);

群管理人员可以进行一下操作:

代码示例:


//以测试群1231232,测试账号test1为例
char* tid = "1231232";
char* uid = "test1";//申请者的账号
nim_team_pass_join_apply_async(tid, uid,0,my_nim_team_event_cb_func,0);

代码示例:

//以测试群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);

退出群组

退出群组包括主动退出群组和被动退出。群管理员和群主都拥有踢出群的权限。被踢出群后,会收到系统通知,通过群通知事件通知给用户。

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);

解散群

高级群群主拥有解散群的权限,其他成员均没有此权限。仅高级群支持。

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);

踢人出群

群主可以踢出任何群成员,高级群管理员可以踢出普通群成员。

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);

群成员禁言

支持管理员和群主对普通成员的禁言、解除禁言操作。

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);

编辑群组资料

普通群成员都可以修改群名等信息,高级群只有管理员才有权限修改。

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提供允许管理员修改他人在群内的昵称,也允许用户修改自己在群内的信息

更新本人的群成员资料

群内成员可以修改本人的资料信息。

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,最好能先通过接口获取本人的完整的群成员信息,然后再将需要修改的字段更新为新的值,kNIMTeamUserKeyIDkNIMTeamUserKeyAccID字段必填
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);

修改其他成员的群昵称

群管理员和群主可以修改其他成员的群昵称。

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 群成员信息,详见TeamMemberPropertykNIMTeamUserKeyIDkNIMTeamUserKeyAccID字段必填,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提供了对高级群的权限管理功能,仅管理员和群主可以进行操作。可以增加,移除管理员,转让群主等。

添加管理员

jsonlist_admin_ids 中包含的账号全部设置为群管理员

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);

移除管理员

managerIdArray 中包含的账号全部移除群管理员身份

 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);

移交群主

将群主转让给其他群成员。is_leave为true时,移交成功后,同时退出本群。

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);