聊天室

开发聊天室功能前可以先查阅聊天室FAQ,以对聊天室功能有大概的了解。

聊天室功能概述

聊天室特点:

初始化与清理

使用聊天室功能时必须调用 nim_chatroom::ChatRoom::Init() 进行初始化,退出使用聊天室功能时需调用 nim_chatroom::ChatRoom::Cleanup() 进行清理工作。两者必须配对使用,避免造成不必要的异常。

聊天室事件通知

聊天室的登录、登出,收到消息等等操作都是通过监听全局事件来通知给调用者。必须在调用登录操作之前,先监听所有的聊天室事件通知。建议在初始化完成后就注册事件监听。

登录聊天室事件

在开发者调用登录聊天室接口后,通过此事件通知开发者登录进度和结果。登录步骤按本地服务初始,连接服务器中,服务器连接完成,登录鉴权中,登录鉴权完成五个步骤顺序进行,当登录鉴权成功后,可以获取得到当前聊天室的信息和本人在聊天室中的成员信息。

NIMChatRoomLoginStep枚举说明

枚举 说明
kNIMChatRoomLoginStepInit 1 本地服务初始化
kNIMChatRoomLoginStepServerConnecting 2 服务器连接中
kNIMChatRoomLoginStepServerConnectOver 3 服务器连接结束,连接结果error_code
kNIMChatRoomLoginStepRoomAuthing 4 聊天室鉴权中
kNIMChatRoomLoginStepRoomAuthOver 5 聊天室鉴权结束,鉴权结果见error_code, error_code非408则需要开发者重新请求聊天室登录信息
static void RegEnterCb(const EnterCallback& cb, const std::string& json_extension = "");
参数 说明
cb 异步回调通知
json_extension 扩展字段,预留
//监听登录事件
nim_chatroom::ChatRoom::RegEnterCb([&](int64_t room_id, NIMChatRoomEnterStep step, int error_code,const ChatRoomInfo& info, const ChatRoomMemberInfo& member_info)
{
    if (step == NIMChatRoomEnterStep::kNIMChatRoomEnterStepRoomAuthOver && error_code == kNIMResSuccess)
    {
        //进入聊天室成功
    }
    if (error_code != kNIMResSuccess)
    {
         //进入聊天室出错
    }
});

//取消监听
nim_chatroom::ChatRoom::RegEnterCb(nullptr);

退出聊天室事件

通知已经退出聊天室,除了主动退出聊天室之外,还包括被多端、主播和管理员踢出,以及聊天室被关闭或者被解散也会收到离开聊天室的通知。收到该通知后,该聊天不再自动重连进入聊天室。重新登录需要重新获取token

NIMChatRoomExitReason枚举参数说明

枚举 说明
kNIMChatRoomExitReasonExit 0 自行退出,重登前需要重新请求登录
kNIMChatRoomExitReasonRoomInvalid 1 聊天室已经被解散,重登前需要重新请求登录
kNIMChatRoomExitReasonKickByManager 2 被管理员踢出,重登前需要重新请求登录
kNIMChatRoomExitReasonKickByMultiSpot 3 多端登录被踢
kNIMChatRoomExitReasonIllegalState 4 当前链接状态异常
kNIMChatRoomExitReasonBeBlacklisted 5 被管理员加入黑名单
static void RegExitCb(const ExitCallback& cb, const std::string& json_extension = "");
参数 说明
cb 异步回调通知
json_extension 扩展字段,预留
void OnExitHandler(long roomId, ResponseCode errorCode, NIMChatRoomExitReason reason)
{
    ...
}
//监听事件
nim_chatroom::ChatRoom::RegExitCb([&](::int64_t room_id, int error_code, NIMChatRoomExitReason reason)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegExitCb(nullptr);

聊天室连接状态更改通知

网络出现波动导致聊天室断开连接时,会通知开发者聊天室的连接状态。SDK 会监听网络状况,自动重连。

NIMChatRoomLinkCondition枚举参数说明

枚举 说明
kNIMChatRoomLinkConditionAlive 0 连接正常
kNIMChatRoomLinkConditionDeadAndRetry 1 连接失败,尝试重连
kNIMChatRoomLinkConditionDead 2 开发者需要重新申请聊天室登录信息
static void RegLinkConditionCb(const LinkConditionCallback& cb, const std::string& json_extension = "");
参数 说明
cb 异步回调通知
json_extension 扩展字段,预留
//监听事件
nim_chatroom::ChatRoom::RegLinkConditionCb([&](::int64_t room_id, NIMChatRoomLinkCondition condition)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegLinkConditionCb(nullptr);

接收消息事件

收到一条聊天室消息,消息内容为ChatRoomMessage。多个聊天室的消息都是通过该事件通知,开发者通过区分roomId来区分各自的聊天室。所有的聊天室消息本地都不做存储。

NIMChatRoomMsgType枚举说明

枚举 说明
kNIMChatRoomMsgTypeText 0 文本类型消息
kNIMChatRoomMsgTypeImage 1 图片类型消息
kNIMChatRoomMsgTypeAudio 2 声音类型消息
kNIMChatRoomMsgTypeVideo 3 视频类型消息
kNIMChatRoomMsgTypeLocation 4 位置类型消息
kNIMChatRoomMsgTypeNotification 5 活动室通知
kNIMChatRoomMsgTypeFile 6 文件类型消息
kNIMChatRoomMsgTypeTips 10 提醒类型消息
kNIMChatRoomMsgTypeRobot 11 波特机器人消息
kNIMChatRoomMsgTypeCustom 100 自定义消息
kNIMChatRoomMsgTypeUnknown 1000 未知类型消息,作为默认值

ChatRoomMessage重要参数说明

类型 参数 说明
int64_t room_id_ 消息所属的聊天室id(服务器填充)
string from_id_ 消息发送者
int64_t timetag_ 消息发送的时间戳(毫秒)(服务器填充)
NIMChatRoomClientType from_client_type_ 消息发送方客户端类型,发送方不需要填写(服务器填充)
string from_nick_ 消息发送者昵称(服务器填充)
string from_avatar_ 消息发送者头像(服务器填充)
string from_ext_ 消息发送者身份扩展字段(服务器填充)
NIMChatRoomMsgType msg_type_ 消息类型,详见NIMChatRoomMsgType
string msg_attach_ 消息内容,长度限制2048,如果约定的是json字符串,必须为可以解析为json的非格式化的字符串,除文本消息外,其他图片、语音、视频、地理位置、自定义消息都需要是目前约定好的json串,此内容是透传内容,本质上是IM消息的附件内容。参考发送消息的相应类型消息
string client_msg_id_ 客户端消息id,发送方填写
ChatRoomMessageSetting msg_setting_ 消息设置,详见ChatRoomMessageSetting
string local_res_path_ 媒体文件本地绝对路径(客户端)(暂不支持)
string local_res_id_ 本地媒体文件ID(客户端)(暂不支持)

ChatRoomMessageSetting消息设置重要参数说明

类型 参数 说明
bool resend_flag 消息是否需要重发,true:需要,false:不需要,默认是false(暂不支持)
string ext_ 第三方扩展字段, 长度限制4096, 必须为可以解析为Json的非格式化的字符串
bool anti_spam_enable_ 是否需要过易盾反垃圾,true:需要,false:不需要,默认false,参考IM消息的反垃圾设置
string anti_spam_content_ (可选)开发者自定义的反垃圾字段,长度限制:5000字符
bool history_save_ 是否存云端消息历史,默认存(暂不支持)
static void RegReceiveMsgCb(const ReceiveMsgCallback& cb, const std::string& json_extension = "");
参数 说明
cb 异步回调通知
json_extension 扩展字段,预留
//监听事件
nim_chatroom::ChatRoom::RegReceiveMsgCb([&](::int64_t room_id, const ChatRoomMessage& result)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegReceiveMsgCb(nullptr);

发送消息结果通知

通过该事件,用户可以知道消息发送成功与否。

static void RegSendMsgAckCb(const SendMsgAckCallback& cb, const std::string& json_extension = "");
参数 说明
cb 异步回调通知
json_extension 扩展字段,预留
//监听事件
nim_chatroom::ChatRoom::RegSendMsgAckCb([&](::int64_t room_id, int error_code,const ChatRoomMessage& result)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegSendMsgAckCb(nullptr);

收到聊天室通知消息事件

聊天室的所有通知消息都通过该事件接收。包括成员进入/离开聊天室,禁言/解除禁言,加黑/取消加黑等等,详见ChatRoomNotification说明。

NIMChatRoomNotificationId枚举说明

枚举值 说明
kNIMChatRoomNotificationIdMemberIn 成员进入聊天室
kNIMChatRoomNotificationIdMemberExit 成员离开聊天室
kNIMChatRoomNotificationIdAddBlack 成员被加入黑名单
kNIMChatRoomNotificationIdRemoveBlack 成员被取消黑名单
kNIMChatRoomNotificationIdAddMute 成员被禁言
kNIMChatRoomNotificationIdRemoveMute 成员被取消禁言
kNIMChatRoomNotificationIdAddManager 设置为管理员
kNIMChatRoomNotificationIdRemoveManager 被取消管理员
kNIMChatRoomNotificationIdAddFixed 设置为聊天室固定成员
kNIMChatRoomNotificationIdRemoveFixed 被取消聊天室固定成员
kNIMChatRoomNotificationIdClosed 聊天室被关闭了
kNIMChatRoomNotificationIdInfoUpdated 聊天室信息更新
kNIMChatRoomNotificationIdMemberKicked 成员被踢出聊天室
kNIMChatRoomNotificationIdMemberTempMute 临时禁言
kNIMChatRoomNotificationIdMemberTempUnMute 解除临时禁言
kNIMChatRoomNotificationIdMyRoleUpdated 成员主动更新了聊天室内的角色信息(仅指nick/avator/ext)
kNIMChatRoomNotificationIdRoomMuted 聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
kNIMChatRoomNotificationIdRoomDeMuted 聊天室解除全体禁言状态

再来看下ChatRoomNotification参数说明

类型 参数 说明
NIMChatRoomNotificationId id_ 通知类型
string ext_ 上层开发自定义的事件通知扩展字段, 必须为可以解析为Json的非格式化的字符串
string operator_id_ 操作者的账号id
string operator_nick_ 操作者昵称
std::list< std::string > target_nick_ 被操作者的nick列表
std::list< std::string > target_ids_ 操作者的账号id列表
bool muted_ 当通知类型为成员进入时有该值,代表是否禁言状态,1:是 缺省或0:不是
bool temp_muted_ 当通知类型为成员进入言时有该值,代表临时禁言状态
int64_t temp_mute_duration_ 当通知为临时禁言相关时有该值,禁言时代表本次禁言的时长(秒),取消禁言时代表本次剩余禁言时长(秒);当通知类型为成员进入时,代表临时禁言时长(秒),其他通知不带此数据
string queuechange 当通知为聊天室队列变更事件才有,代表变更的内容(暂不支持)
 static void RegNotificationCb(const NotificationCallback& cb, const std::string& json_extension = "");
//监听事件
nim_chatroom::ChatRoom::RegNotificationCb([&](::int64_t room_id, const ChatRoomNotification& notification)
{
    ...
});

//取消监听
nim_chatroom::ChatRoom::RegNotificationCb(nullptr);

进入聊天室

获取token

聊天室依赖IM,进入聊天室前,需要通过调用IM模块接口获取进入聊天室的授权信息,在开发者调用登录聊天室接口时将此授权信息传入接口。聊天室可以同时登录多个,每个聊天室都要各自根据roomId请求授权信息.

注意:这里调用的是 IM SDK 模块的接口

static void ChatRoomRequestEnterAsync(const int64_t room_id, const ChatRoomRequestEnterCallback &callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
callback 结果通知回调
json_ext 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
string _token = "";

nim::PluginIn::ChatRoomRequestEnterAsync(roomId, [&](int error_code, const std::string& result)
{
    if (error_code == kNIMResSuccess)
    {
        _token = result; //此token即为所需要的授权信息
        //nim_chatroom::ChatRoom::Enter,尽量请抛一个异步任务去操作,如下;
        scheduleOnce([&](float dt)
        {
            ChatRoomEnterInfo loginData;
            loginData.SetNick("nickName");
            loginData.SetIcon("https://xxxx.png");//图片url
            loginData.SetExt("{\"myExt\:\"111\"}");
            loginData.SetNotifyExt("{\"myNotifyExt\:\"2222\"}") ;
            nim_chatroom::ChatRoom::Enter(roomId,_token,loginData);
        });
    }
});

登录聊天室

进入聊天室时,可以通过ChatRoomEnterInfo设置本人在聊天室的昵称,头像,以及传递通知信息和扩展信息等。登录过程通过登录聊天室事件通知开发者。

ChatRoomEnterInfo参数说明

类型 参数 说明
string SetNick 进入聊天室后展示的昵称,选填
string SetIcon 进入聊天室的头像,填头像的url,选填
string SetExt 扩展字段信息,必须是json字符串,选填
string SetNotifyExt 进入聊天室通知扩展字段,必须是json字符串,选填
static bool Enter(const int64_t room_id, const std::string& request_login_data, const ChatRoomEnterInfo& info = ChatRoomEnterInfo(), const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
requestrequest_login_data 通过接口获取token获取的授权信息,必填
info 进入聊天室时附带的个人信息,选填
json_extension 扩展信息,预留

查阅示例代码

离开聊天室

离开聊天室,会断开聊天室对应的链接,并不再收到该聊天室的任何消息。如果用户要离开聊天室,可以手动调用离开聊天室接口。

static void Exit(const int64_t room_id, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::Exit(roomId);

发送聊天室消息

先创建消息内容Message,然后通过nim_chatroom::ChatRoom::SendMsg接口。发送结果通过发送消息结果通知给用户。可发送多种类型消息,包括文本,图片,语音,视频,地理位置等等各种自定义消息,具体消息内容可参见IM的消息收发。本地没有保存消息历史记录,可以查询云端历史消息记录

创建聊天室消息

static std::string CreateRoomMessage(const NIMChatRoomMsgType msg_type, const std::string& client_msg_id, const std::string& attach, const std::string& msg_body, const ChatRoomMessageSetting& msg_setting, int64_t timetag = 0);
参数 说明
msg_type 消息类型)
client_msg_id 消息id)
attach 消息内容 详见ChatRoomMessageattach说明
msg_body 文本消息内容(暂不支持)
msg_setting 消息设置,详见ChatRoomMessageSetting
timetag 当前UNIX时间戳,毫秒

发送消息

static void SendMsg(const int64_t room_id, const std::string& json_msg, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
json_msg 消息内容 详见ChatRoomMessage,可以使用创建聊天室消息接口创建
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
//消息设置
ChatRoomMessageSetting setting;
setting.ext_ = "{\"ext\":\"自定义扩展内容\"}";
...

std::string msg = nim_chatroom::ChatRoom::CreateRoomMessage(kNIMChatRoomMsgTypeText,"消息唯一uuid","这是一条文本消息","",setting);
nim_chatroom::ChatRoom::SendMsg(roomId,msg);

查询云端历史消息记录

SDK支持查询在云端的聊天室历史消息记录。

ChatRoomGetMsgHistoryParameters参数说明

类型 参数 说明
int64_t start_timetag_ 开始时间,单位毫秒
int limit_ 查询最大条数上限,必须为大于0的值
bool reverse_ 是否反向查询
static void GetMessageHistoryOnlineAsync(const int64_t room_id,    const ChatRoomGetMsgHistoryParameters &parameters,    const GetMsgHistoryCallback &callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
parameters 获取聊天室消息历史参数
callback 结果回调通知
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.startTimetag = 1520391909233;//13位时间戳(毫秒)
params.reverse_ = false;
nim_chatroom::ChatRoom::GetMessageHistoryOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMessage>& messages)
{
   ...
});

聊天室管理

获取聊天室信息

进入聊天室的事件中会有聊天室的信息,此外还能通过单独的接口获取聊天室信息。SDK 本地不缓存聊天室信息,只提供向服务器查询的接口,因此接口调用遵循服务器接口使用频率限制。

ChatRoomInfo重要参数说明

类型 参数 说明
int64_t id_ 聊天室id,即房间号
string name_ 聊天室名称,管理员可以更新此信息
string announcement_ 聊天室公告
string broadcast_url_ 视频直播流地址
string creator_id_ 聊天室创建者账号id
int valid_flag_ 聊天室有效标记,1:有效,0: 无效
string ext_ 第三方扩展字段, 必须为可以解析为Json的非格式化的字符串, 长度4k
int online_count_ 在线人数
bool mute_all_ 聊天室禁言标志,1:禁言 0:不禁言
static void GetInfoAsync(const int64_t room_id,const GetChatRoomInfoCallback& callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
callback 结果回调通知
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::GetInfoAsync(roomId, [&](int64_t room_id, int error_code, const ChatRoomInfo& info)
{
    ...
});

更新聊天室信息

SDK支持更新聊天室信息,仅管理员拥有此权限。目前只支持更新ChatRoomInfoname_announcement_broadcast_url_ext_ 四个属性。同时,在更新时可以设置是否在聊天室内广播通知。

static void UpdateRoomInfoAsync(const int64_t room_id, const ChatRoomInfo& info, bool need_notify, const std::string& notify_ext, const UpdateRoomInfoCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填
info 聊天室更新信息
need_notify 是否聊天室内广播通知,true:通知,此时notify_ext不为空 false:不通知
notify_ext 通知中的自定义字段,长度限制2048
callback 结果回调通知
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomInfo info;
info.id_ = roomId,
info.announcement_ ="聊天室公告",
info.name_ = "newName",
info.broadcast_url_ = "http://xxxxx",
info.ext_ = "{\"test"\:\"1111\"}", //自定义扩展字串
nim_chatroom::ChatRoom::UpdateRoomInfoAsync(roomId, info,false,null,[&](::int64_t room_id, int error_code)
{
    ...
});

获取聊天室成员列表

该接口可以获取固定成员信息、仅在线的固定成员信息及游客信息 ChatRoomMemberInfo,其中的扩展字段由该用户进入聊天室时填写。 固定成员有四种类型,分别是创建者,管理员,普通用户,受限用户。禁言用户和黑名单用户都属于受限用户。本地不缓存成员列表信息,均直接从云端获取。

ChatRoomMemberInfo重要参数说明

类型 参数 说明
int64_t room_id_ 聊天室id,即房间号
string account_id_ 成员账号
ChatRoomMemberType type_ 成员类型,-1:受限用户; 0:普通;1:创建者;2:管理员 ,详见ChatRoomMemberType
int level_ 成员级别: >=0,表示用户开发者可以自定义的级别
string nick_ 聊天室内的昵称字段,可以由用户进聊天室时提交
string avatar_ 聊天室内的头像,可以由用户进聊天室时提交
string ext_ 第三方扩展字段, 必须为可以解析为Json的非格式化的字符串, 长度4k
NIMChatRoomOnlineState state_ 成员是否处于在线状态, 仅特殊成员才可能离线, 对游客/匿名用户而言只能是在线,0:离线 1: 在线
NIMChatRoomGuestFlag guest_flag_ 是否是普通游客类型,0:不是游客,1:是游客; 游客身份在聊天室中没有持久化, 只有在线时才会有内存状态
int64_t enter_timetag_ 进入聊天室的时间戳(毫秒),对于离线成员该字段为空
bool is_blacklist_ 是否在黑名单 1:是 0:否
bool is_muted_ 是否被禁言 1:是 0:否
bool is_valid_ 是否有效 1:是 0:否
bool temp_muted_ 是否被临时禁言 1:是 0:否
int64_t temp_muted_duration_ 临时禁言剩余时长,单位秒
int64_t update_timetag_ 固定成员的记录更新时间戳,用于固定成员列表的排列查询

NIMChatRoomGetMemberType枚举说明

枚举 说明
kNIMChatRoomGetMemberTypeSolid 0 固定成员,固定成员,包括创建者,管理员,普通等级用户,受限用户(禁言+黑名单),即使非在线也可以在列表中看到,有数量限制
kNIMChatRoomGetMemberTypeTemp 1 非固定成员,非固定成员,又称临时成员,只有在线时才能在列表中看到,数量无上限

ChatRoomMemberType枚举说明

枚举 说明
Restricted -1 受限制成员
Normal 0 普通成员
Creator 1 创建者

ChatRoomGetMembersParameters参数说明

类型 参数 说明
NIMChatRoomGetMemberType type_ 成员类型,详见NIMChatRoomGetMemberType
int64_t timestamp_offset_ 距离当前时间的时间戳
int limit_ 查询最大条数上限,必须为大于0的值
static void GetMembersOnlineAsync(const int64_t room_id,const ChatRoomGetMembersParameters &parameters,const GetMembersCallback& callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
parameters 查询参数设置,详见ChatRoomGetMembersParameters
callback 结果回调通知
json_extension 扩展信息,预留
//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomGetMembersParameters params;
params.limit_ = 20;
params.timestamp_offset_ = 0;//距离当前时间的时间戳
params.type_ = kNIMChatRoomGetMemberTypeSolid;
nim_chatroom::ChatRoom::GetMembersOnlineAsync(roomId, params, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMemberInfo>& infos)
{
    ...
});

获取指定聊天室成员信息

该接口可以获取指定多个账号的成员信息ChatRoomMemberInfo,从云端获取。

static void GetMemberInfoByIDsAsync(const int64_t room_id,const std::list<std::string>& ids,const GetMembersCallback& callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
ids 成员id集合
callback 结果回调通知
json_extension 扩展信息,预留
//以测试房间号3001,聊天室成员test1,test2为例
int64_t roomId = 3001;
std::list<string> ids;
ids.push_back("test1");
ids.push_back("test2");

nim_chatroom::ChatRoom::GetMemberInfoByIDsAsync(roomId,ids, [&](::int64_t room_id, int error_code, const std::list<ChatRoomMemberInfo>& infos)
{
    ...
});

更新自己的聊天室信息

目前支持更新本人聊天室成员信息。目前只支持昵称,头像和扩展字段的更新。可以设置更新是否通知,如果设置通知,则通过收到聊天室通知消息事件通知给用户。

static void UpdateMyRoomRoleAsync(const int64_t room_id, const ChatRoomMemberInfo& info, bool need_notify, const std::string& notify_ext, const UpdateMyRoomRoleCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
info 成员信息,将需要修改的字段修改为新的字段,目前只支持更新 ChatRoomMemberInfoNick, MemberIcon,Extension 三个属性。详见ChatRoomMemberInfo
callback 结果回调通知
notify 是否聊天室内广播通知,true:通知,此时notify_ext不为空 false:不通知
notify_ext 通知中的自定义字段,长度限制2048
json_extension 预留字段
//以测试房间号3001
int64_t roomId = 3001;
ChatRoomMemberInfo ri;
ri.room_id_ = roomId;
ri.avatar_ = "http://xxxx/newIcon.png";
ri.nick_ = "newNick";

nim_chatroom::ChatRoom::UpdateMyRoomRoleAsync(roomId,ri,false,null, [&](::int64_t room_id, int error_code)
{
    ...
});

聊天室权限管理

设置成员身份标识

设置/取消管理员时, 服务器会通过收到聊天室通知消息事件通知给用户。通知类型查看说明。如果游客被设为管理员,再被取消管理员,该成员不再变为游客,而成为普通成员。

NIMChatRoomMemberAttribute枚举说明

枚举 说明
kNIMChatRoomMemberAttributeAdminister 1 管理员(固定成员),仅创建者拥有操作提升权限
kNIMChatRoomMemberAttributeNomalSold 2 普通成员,操作者必须是创建者或管理员
kNIMChatRoomMemberAttributeBlackList -1 黑名单成员,操作者必须是创建者或管理员
kNIMChatRoomMemberAttributeMuteList -2 被永久禁言成员,操作者必须是创建者或管理员

ChatRoomSetMemberAttributeParameters参数说明

类型 参数 说明
string account_id_ 成员账号id
NIMChatRoomMemberAttribute attribute_ 成员身份标识,详见NIMChatRoomMemberAttribute
bool opt_ 对应设置成员身份标识,1:设置 0:取消设置
int level_ 用户等级,opt_= 1 or 2时才有效
string notifyext 操作产生的通知事件中开发者自定义的扩展字段,需要是json字符串
static void SetMemberAttributeOnlineAsync(const int64_t room_id,const ChatRoomSetMemberAttributeParameters& parameters,const SetMemberAttributeCallback& callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
parameters 成员属性信息,详见ChatRoomSetMemberAttributeParameters
callback 操作结果回调
json_extension 预留字段
//以测试房间号3001,聊天室成员test1为例
int64_t roomId = 3001;

//设置/取消管理员
ChatRoomSetMemberAttributeParameters ri;
ri.account_id_ = "test1",
ri.attribute_ = kNIMChatRoomMemberAttributeAdminister,
ri.opt_ = true,//如果设置为false,则为取消管理员

nim_chatroom::ChatRoom::SetMemberAttributeOnlineAsync(roomId,ri,[&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
    ...
});

//设置/取消永久禁言
ChatRoomSetMemberAttributeParameters prop;
prop.account_id_ = "test1",
prop.attribute_ = kNIMChatRoomMemberAttributeMuteList,
prop.opt_ = true,//如果设置为false,则为取消禁言

nim_chatroom::ChatRoom::SetMemberAttributeOnlineAsync(roomId,prop, [&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
    ...
});

临时禁言成员

此接口提供临时禁言/解除临时禁言成员的功能。如果需要永久禁言,请通过设置成员身份标识接口将用户设置为禁言用户。 如果禁言时长时间到了,自动取消禁言。设置临时禁言成功后的通知消息中,包含的时长是禁言剩余时长。若设置禁言时长为0,表示取消临时禁言。若第一次设置的禁言时长还没结束,又设置第二次临时禁言,以第二次设置的时间开始计时。

static void TempMuteMemberAsync(const int64_t room_id, const std::string& accid, const int64_t duration, bool need_notify, const std::string& notify_ext, const TempMuteMemberCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
accid 成员账号,必填)
duration 临时禁言时长(秒),解禁填0
callback 操作结果回调
notify 是否聊天室内广播通知
notify_ext 通知中的自定义字段,长度限制2048,json字符串
json_extension 预留字段
//以测试房间号3001,聊天室成员test1为例,禁言60秒
int64_t roomId = 3001;
nim_chatroom::ChatRoom::TempMuteMemberAsync(roomId,"test1", 60,false,null,[&](::int64_t room_id, int error_code, const ChatRoomMemberInfo& info)
{
    ...
});

踢出在线成员

踢出成员。仅管理员可以踢;如目标是管理员仅创建者可以踢。可以添加被踢通知扩展字段,这个字段会放到被踢通知的扩展字段中。被踢出聊天室的通知通过聊天室通知事件下发给开发者。

static void KickMemberAsync(const int64_t room_id,const std::string& id,const std::string& notify_ext,const KickMemberCallback& callback,const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
id 成员账号)
notify_ext 放到事件通知中的扩展字段
callback 操作结果回调
json_extension 预留字段
//以测试房间号3001,聊天室成员test1为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::KickMemberAsync(roomId,"test1","notify" ,[&](::int64_t room_id, int error_code)
{
    ...
});

聊天室队列服务

聊天室提供队列服务,针对直播连麦场景使用。

新加(更新)麦序队列元素

聊天室队列服务:加入或者更新队列元素(聊天室管理员权限).当 key 不存在时候,调用该接口,表示加入新元素。 当 key 已存在的时候,调用该接口,表示修改对应 keyvalue

ChatRoomQueueElement麦序队列元素说明

类型 参数 说明
string key_ 元素的唯一key,长度限制128字节
string value_ 元素的内容,长度限制4096字节
static void QueueOfferAsync(const int64_t room_id, const ChatRoomQueueElement& element, const QueueOfferCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填
element 麦序队列元素数据
callback 操作结果回调
json_extension 扩展参数,预留
//以测试房间号3001为例
int64_t roomId = 3001;
ChatRoomQueueElement element;
element.key_ = "key1";
element.value_ = "value1";
nim_chatroom::ChatRoom::QueueOfferAsync(roomId,element, [&](::int64_t room_id, int error_code)
{
    ...
},null);

取出麦序队列元素

element_key是唯一键,element_key 若为空, 则表示取出头元素。若不为空, 则表示取出指定元素。操作成功后,在回调通知中result获得该元素的key和value。

 static void QueuePollAsync(const int64_t room_id, const std::string& element_key, const QueuePollCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
element_key 元素的唯一key,长度限制128字节
callback 操作结果回调
json_extension 扩展参数,预留
//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueuePollAsync(roomId,"key1", [&](::int64_t room_id, int error_code, const ChatRoomQueueElement& element)
{
    //result:获取的队列元素的json字符串,如{"key":"key1","value":"value1"}
    ...
});

获取所有队列元素

排序列出所有队列元素,在result返回队列元素的json数组。

static void QueueListAsync(const int64_t room_id, const QueueListCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
callback 操作结果回调
json_extension 扩展参数,预留
//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueListAsync(roomId,[&](::int64_t room_id, int error_code, const ChatRoomQueue& queue)
{
    //result:获取的队列元素的json数组,如[{"key":"key1","value":"value1"},{"key":"key2","value":"value2"}]
    ...
});

删除麦序队列

将整个麦序队列删除,需要管理员权限。

static void QueueDropAsync(const int64_t room_id, const QueueDropCallback& callback, const std::string& json_extension = "");
参数 说明
room_id 聊天室id,即房间号, 必填)
callback 操作结果回调
json_extension 扩展参数,预留
//以测试房间号3001为例
int64_t roomId = 3001;
nim_chatroom::ChatRoom::QueueDropAsync(roomId,[&](::int64_t room_id, int error_code)
{
    ...
});