聊天室

功能概述

云信提供聊天室功能,人数无上限,用户可自由进出聊天室。聊天室的创建与关闭需要通过服务端API来完成。

聊天室原型:

@interface NIMChatroom : NSObject
/**
 *  聊天室Id
 */
@property (nullable,nonatomic,copy)     NSString    *roomId;

/**
 *  聊天室名
 */
@property (nullable,nonatomic,copy)     NSString    *name;

/**
 *  公告
 */
@property (nullable,nonatomic,copy)     NSString    *announcement;


/**
 *  创建者
 */
@property (nullable,nonatomic,copy)     NSString    *creator;


/**
 *  第三方扩展字段,长度限制4K
 */
@property (nullable,nonatomic,copy)     NSString *ext;

/**
 *  当前在线用户数量
 */
@property (nonatomic,assign)   NSInteger onlineUserCount;

/**
 *  直播地址。当与直播业务搭配时,可以将直播推拉流地址设置于此。
 */
@property (nullable,nonatomic,copy)   NSString *broadcastUrl;

/**
 *  聊天室队列修改权限等级
 */
@property (nonatomic,assign)   NIMChatroomQueueModificationLevel queueModificationLevel;

/**
 *  聊天室是否正在全员禁言标记,禁言后只有管理员可以发言
 */
- (BOOL)inAllMuteMode;
@end

进入聊天室

用户要在聊天室收发消息之前,必须先调用接口进入聊天室。聊天室只允许用户手动进入,无法进行邀请。支持同时进入10个聊天室。

进入聊天室可以有两种方式:以独立模式进入聊天室和非独立模式进入聊天室。

@protocol NIMChatroomManager <NSObject>
/**
 *  进入聊天室
 *
 *  @param request    进入聊天室请求
 *  @param completion 进入完成后的回调
 */
- (void)enterChatroom:(NIMChatroomEnterRequest *)request
           completion:(NIMChatroomEnterHandler)completion;
@end           

NIMChatroomEnterRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
roomNickname NSString 聊天室昵称
roomAvatar NSString 聊天室头像,上层可以自主设置在聊天室内的头像,没有设置则使用用户本身的信息
roomExt NSString 本人的聊天室成员信息拓展字段,仅对当次进入有效
roomNotifyExt NSString 聊天室事件通知拓展字段
retryCount NSInteger 聊天室重连次数,默认为三次,设置成 0 后一旦一次连接失败后,SDK 将不在重试。 APP 可以根据自己的需求进行设置
mode NIMChatroomIndependentMode 聊天室独立模式. 默认为 nil。

其中:

非独立模式

非独立模式较为简单,在IM处于登录状态时,无需设置NIMChatroomIndependentMode,直接调用进入聊天室方法即可。

独立模式

当选择以独立模式进入聊天室时,必须设置NIMChatroomIndependentMode的各项属性。

NIMChatroomIndependentMode 参数列表:

参数 类型 说明
username NSString 独立模式下的用户名,若设置为 nil ,SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatroomEnterRequest 必须设置昵称和头像信息
token NSString 独立模式下的 Token。 当用户名为空时,token 无效。
chatroomAppKey NSString 聊天室 AppKey, 可选填, 如果不填则使用云信IM AppKey。

进入聊天室后,可以通过如下接口获取进入该聊天室时所设置的模式:

@protocol  NIMChatroomManager <NSObject>
/**
*  获取聊天室登录使用的模式
*/
- (NSInteger)chatroomAuthMode:(NSString *)roomId;

独立模式下又可分为匿名模式与非匿名模式。匿名模式只能收消息,不能发消息。

NIMChatroomIndependentMode - username设置为nil时,则为匿名模式。SDK 将使用自动生成的匿名账号进行登录。在匿名模式下,NIMChatroomEnterRequest中必须设置昵称和头像信息。

独立模式由于不依赖IM连接,SDK无法自动获取聊天室服务器的地址,需要客户端向开发者应用服务器请求该地址,而应用服务器需要向网易云信服务器请求,然后将请求结果原路返回给客户端,即请求路径为:客户端 <-> 开发者应用服务器 <-> 网易云信服务器(API:请求聊天室地址)。

首先需要注册获取聊天室地址的回调方法:

@interface NIMChatroomIndependentMode : NSObject
/**
 *  注册获取聊天室地址的回调方法
 *
 *  @param handler 获取聊天室地址信息的方法
 *  @discussion 在进入聊天室和刷新聊天室 IP 时,SDK 都会主动调用这个回调方法,并传入相应的两个参数 `roomId` 和 `callback`。当前回调接口要求上层使用 `roomId` 走自己的网络请求获取对应聊天室地址并通过 callback 回调给 SDK。需要注意的时候无论请求成功,都需要通过 callback 进行回调,否则进入聊天室请求将会一直等待。同时此接口只需注册一次即可,多次注册将使用后者覆盖前者。
 */
+ (void)registerRequestChatroomAddressesHandler:(NIMRequestChatroomAddressesHandler)handler
@end

代码示例

 [NIMChatroomIndependentMode registerRequestChatroomAddressesHandler:^(NSString * _Nonnull roomId, NIMRequestChatroomAddressesCallback  _Nonnull callback) {
             [YourHTTPService request:roomId completion:^(NSError *error,NSArray *addresses)
             {
                 //无论请求是否成功,都需要进行回调
                 if(callback)
                 {
                     callback(error,addresses);
                 }
             }];
         }];

其中 YourHTTPService 为 App 的应用服务器接口,应用服务器可以调用云信服务端的请求聊天室地址 API 来获取具体的聊天室地址。

即针对独立模式进入聊天室,需要进行以下步骤:

聊天室多端登录

支持设置聊天室多端登录策略,即当同账号在不同客户端登录时,是否可以同时进入同一个聊天室。可以进入云信控制台进行设置:

监听聊天室连接变化

进入聊天室会建立新的连接,不同的聊天室对应着不同的连接,开发者可以监听连接状态做一些业务处理。

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  监听聊天室连接状态变化
 *
 *  @param roomId 聊天室Id
 *  @param state  当前状态
 */
- (void)chatroom:(NSString *)roomId 
connectionStateChanged:(NIMChatroomConnectionState)state;
@end

NIMChatroomConnectionState 枚举列表

参数 说明
NIMChatroomConnectionStateEntering 0 正在进入聊天室
NIMChatroomConnectionStateEnterOK 1 进入聊天室成功
NIMChatroomConnectionStateEnterFailed 2 进入聊天室失败
NIMChatroomConnectionStateLoseConnection 3 和聊天室失去连接

当成功进入聊天室后,若再发生掉线问题时,SDK 将进行自动重连,无需开发者再次调用进入房间接口。

在重连时,可能遇到一些特殊网络错误(如聊天室用户被封禁,聊天室状态异常),会触发以下回调,开发者应该在这个回调中退出聊天室界面。

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  聊天室自动登录出错
 *
 *  @param roomId 聊天室Id
 *  @param error  自动登录出错原因
 */
- (void)chatroom:(NSString *)roomId 
 autoLoginFailed:(NSError *)error;
@end

监听被踢出

当用户被踢出聊天室或者聊天室关闭时,会触发被踢回调:

@protocol NIMChatroomManagerDelegate <NSObject>
/**
 *  被踢回调
 *
 *  @param roomId   被踢的聊天室Id
 *  @param result   被踢的结果详情
 */
- (void)chatroomBeKicked:(NIMChatroomBeKickedResult *)result;
@end

被踢详情 NIMChatroomBeKickedResult

/**
 *  聊天室被踢结果
 */
@interface NIMChatroomBeKickedResult : NSObject

/**
 *  被踢的聊天室 Id
 */
@property (nonatomic, copy)      NSString    *roomId;

/**
 *  被踢的原因
 */
@property (nonatomic, assign)    NIMChatroomKickReason   reason;

/**
 *  被踢的扩展字段
 */
@property (nonatomic, copy)      NSString    *ext;

@end

NIMChatroomKickReason 枚举列表

参数 说明
NIMChatroomKickReasonInvalidRoom 1 聊天室已经解散
NIMChatroomKickReasonByManager 2 被聊天室管理员踢出
NIMChatroomKickReasonByConflictLogin 3 多端被踢
NIMChatroomKickReasonBlacklist 5 被拉黑

离开聊天室

离开聊天室时,会断开聊天室对应的连接,并不再收到关于此聊天室的任何消息。

@protocol NIMChatroomManager <NSObject>
/**
 *  离开聊天室
 *
 *  @param roomId     聊天室ID
 *  @param completion 离开聊天室的回调
 */
- (void)exitChatroom:(NSString *)roomId
          completion:(NIMChatroomHandler)completion;
@end

参数列表

参数 类型 说明
roomId NSString 聊天室 ID
completion NIMChatroomHandler 离开聊天室的回调

聊天室消息收发

聊天室消息收发接口与普通消息收发统一,在发送消息时指定会话类型为聊天室即可。会话 id 即为聊天室 id。值得注意的是:针对聊天室消息,SDK不会持久化在本地。

聊天室通知消息

在聊天室中进行部分操作会产生聊天室通知消息。目前当出现以下事件,会产生通知消息:

NIMChatroomEventType 说明
NIMChatroomEventTypeEnter = 301 成员进入聊天室
NIMChatroomEventTypeExit = 302 成员离开聊天室
NIMChatroomEventTypeAddBlack = 303 成员被拉黑
NIMChatroomEventTypeRemoveBlack = 304 成员被取消拉黑
NIMChatroomEventTypeAddMute = 305 成员被设置禁言
NIMChatroomEventTypeRemoveMute = 306 成员被取消禁言
NIMChatroomEventTypeAddManager = 307 设置为管理员
NIMChatroomEventTypeRemoveManager = 308 移除管理员
NIMChatroomEventTypeAddCommon = 309 设置为固定成员
NIMChatroomEventTypeRemoveCommon = 310 取消固定成员
NIMChatroomEventTypeClosed = 311 聊天室被关闭
NIMChatroomEventTypeInfoUpdated = 312 聊天室信息更新
NIMChatroomEventTypeKicked = 313 聊天室成员被踢
NIMChatroomEventTypeAddMuteTemporarily = 314 聊天室成员被临时禁言
NIMChatroomEventTypeRemoveMuteTemporarily = 315 聊天室成员被解除临时禁言
NIMChatroomEventTypeMemberUpdateInfo = 316 聊天室成员主动更新了聊天室的角色信息
NIMChatroomEventTypeQueueChange = 317 聊天室通用队列变更的通知
NIMChatroomEventTypeRoomMuted = 318 聊天室被禁言了,只有管理员可以发言,其他人都处于禁言状态
NIMChatroomEventTypeRoomUnMuted = 319 聊天室解除禁言状态
NIMChatroomEventTypeQueueBatchChange = 320 聊天室通用队列批量变更的通知

特别地,支持设置成员进出聊天室通知是否下发:

所有的聊天室通知都以消息 NIMMessage 的形式封装。聊天室通知的解析如下:

  1. 判断消息是否为通知消息。

    • 判断 NIMMessage - messageType 字段是否为 NIMMessageTypeNotification
  2. 再判断是否为聊天室通知消息。

    • NIMMessage - messageObject 强类型转换为 NIMNotificationObject
    • 判断转换后的 NIMNotificationObject - notificationType 字段是否为 NIMNotificationTypeChatroom
  3. 解析具体内容。

    • NIMNotificationObject - content 字段强类型转换为 NIMChatroomNotificationContent

聊天室通知内容 NIMChatroomNotificationContent 的字段说明:

下面针对聊天室队列元素变更通知消息的解析进行示例:

NIMChatroomNotificationContenteventType 事件中,有两种事件属于聊天室变更事件分别为NIMChatroomEventTypeQueueChangeNIMChatroomEventTypeQueueBatchChange

消息解析示例:

- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages
{
    for (NIMMessage *message in messages)
    {
        if (message.messageType == NIMMessageTypeNotification)
        {
            if (notification.notificationType == NIMNotificationTypeChatroom)
            {
                NIMChatroomNotificationContent *content = (NIMChatroomNotificationContent *)notification.content;
                NSDictionary *info = content.ext;
                if (content.eventType == NIMChatroomEventTypeQueueChange)
                {
                    //change type
                    //NIMChatroomQueueChangeTypeOffer, NIMChatroomQueueChangeTypePoll, NIMChatroomQueueChangeTypeDrop,NIMChatroomQueueChangeTypeUpdate
                    NIMChatroomQueueChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    //key
                    NSString *key = [info objectForKey:NIMChatroomEventInfoQueueChangeItemKey];
                    //value
                    NSString *value = [info objectForKey:NIMChatroomEventInfoQueueChangeItemValueKey];
                    //deal with key and value
                }
                if (content.eventType == NIMChatroomEventTypeQueueBatchChange)
                {
                    //change type
                    //NIMChatroomQueueBatchChangeTypePartClear
                    NIMChatroomQueueBatchChangeType changeType = [[info objectForKey:NIMChatroomEventInfoQueueChangeTypeKey] integerValue];
                    NSDictionary *batch = [info objectForKey:NIMChatroomEventInfoQueueChangeItemsKey];
                    for (NSString *key in batch)
                    {
                        NSString *value = [batch objectForKey:key];
                        //deal with key and value
                    }
                }
            }
        }
    }
}

NIMChatroomNotificationContenteventTypeNIMChatroomEventTypeQueueChange, 则changeTypeNIMChatroomQueueChangeType:

NIMChatroomNotificationContenteventTypeNIMChatroomEventTypeQueueBatchChange, 则changeTypeNIMChatroomQueueBatchChangeType:

查询云端历史消息

聊天室没有离线消息和漫游消息。可以通过下面的接口查询聊天室消息历史。服务器只保存最近10天的聊天室消息记录。但是10天之前发送的文件(例如:图片、音频、视频等),其url链接地址仍然是有效的(不过开发者需要自行保存这些url,因为无法通过已过期的消息来查询这些文件url)。如需延长「聊天室历史消息天数」,请联系商务顾问。

@protocol NIMChatroomManager <NSObject>
/**
 *  查询服务器保存的聊天室消息记录
 * 
 *  @param roomId  聊天室ID
 *  @param option  查询选项
 *  @param result   完成回调
 */
- (void)fetchMessageHistory:(NSString *)roomId
                     option:(NIMHistoryMessageSearchOption *)option
                     result:(NIMFetchChatroomHistoryBlock)completion;
@end                     

NIMHistoryMessageSearchOption 参数列表 (部分字段对聊天室消息搜索选项无效,已过滤)

参数 类型 说明
startTime NSTimeInterval 检索消息起始时间,需要检索的起始时间,没有则传入0。即以该时间为起点,往前或往后查询。
limit NSUInteger 检索条数,最大限制 100 条
order NIMMessageSearchOrder 检索顺序
messageTypes NSArray 查询的消息类型,默认为 nil ,搜索全类型。

聊天室信息管理

获取聊天室信息

此接口可以远程获取聊天室信息,NIM SDK 不会缓存聊天室信息,开发者需要根据业务自己做好缓存。

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室信息
 *
 *  @param roomId     聊天室ID
 *  @param completion 获取聊天室信息的回调
 *  @discussion 只有已进入聊天室才能够获取对应的聊天室信息
 */
- (void)fetchChatroomInfo:(NSString *)roomId
               completion:(NIMChatroomInfoHandler)completion;
@end               

参数列表

参数 类型 说明
roomId NSString 聊天室 ID
completion NIMChatroomInfoHandler 离开聊天室的回调

修改聊天室信息

@protocol NIMChatroomManager <NSObject>
/**
 *  修改聊天室信息
 *
 *  @param request    聊天室修改请求
 *  @param completion 修改后完成的回调
 */
- (void)updateChatroomInfo:(NIMChatroomUpdateRequest *)request
                completion:(nullable NIMChatroomHandler)completion;
@end  

NIMChatroomUpdateRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
updateInfo NSDictionary 修改信息字段,修改传入的数据键值对是 {@(NIMChatroomUpdateTag) : NSString},无效数据将被过滤
needNotify BOOL 是否需要产生聊天室通知
notifyExt NSString 放到事件通知里的扩展字段

聊天室成员管理

聊天室成员概述

关于聊天室成员:

聊天室成员原型:

@interface NIMChatroomMember : NSObject

/**
 *  用户ID
 */
@property (nullable,nonatomic,copy)   NSString *userId;

/**
 *  聊天室内的昵称字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomNickname;

/**
 *  聊天室内的头像字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomAvatar;

/**
 *  用户在聊天室内的头像缩略图
 *  @discussion 仅适用于使用云信上传服务进行上传的资源,否则无效。
 */

@property (nullable,nonatomic,copy,readonly)  NSString    *roomAvatarThumbnail;

/**
 *  聊天室内预留给开发者的扩展字段,由用户进聊天室时提交。
 */
@property (nullable,nonatomic,copy)   NSString *roomExt;

/**
 *  用户类型
 */
@property (nonatomic,assign) NIMChatroomMemberType type;

/**
 *  是否被禁言
 */
@property (nonatomic,assign) BOOL isMuted;

/**
 *  是否被临时禁言
 *  @discussion 临时禁言和禁言属性无相关性
 */
@property (nonatomic,assign) BOOL isTempMuted;

/**
 *  临时禁言剩余时长
 */
@property (nonatomic,assign) unsigned long long tempMuteDuration;

/**
 *  是否被拉黑
 */
@property (nonatomic,assign) BOOL isInBlackList;

/**
 *  是否在线, 仅特殊成员才可能离线, 对游客用户而言只能是在线
 */
@property (nonatomic,assign) BOOL isOnline;

/**
 *  进入聊天室的时间点
 */
@property (nonatomic,assign) NSTimeInterval enterTimeInterval;
@end

获取聊天室成员

此接口可以远程获取聊天室成员列表,NIM SDK 不会缓存聊天室成员列表,开发者需要根据业务自己做好缓存。

分页获取聊天室成员

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室成员
 *
 *  @param request    获取成员请求
 *  @param completion 请求完成回调
 */
- (void)fetchChatroomMembers:(NIMChatroomMemberRequest *)request
                  completion:(NIMChatroomMembersHandler)completion;
@end                  

NIMChatroomMemberRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
type NIMChatroomFetchMemberType 聊天室成员类型.
lastMember NIMChatroomMember 最后一位成员锚点,不包括此成员。填nil会使用当前服务器最新时间开始查询,即第一页。
limit NSUInteger 获取聊天室成员个数

NIMChatroomFetchMemberType 类型

参数 说明
NIMChatroomFetchMemberTypeRegular 聊天室固定成员
NIMChatroomFetchMemberTypeTemp 聊天室临时成员
NIMChatroomFetchMemberTypeRegularOnline 聊天室在线的固定成员
NIMChatroomFetchMemberTypeUnRegularReversedOrder 聊天室非固定成员(反向查询)

获取指定聊天室成员

@protocol NIMChatroomManager <NSObject>
/**
 *  根据用户ID获取聊天室成员信息
 *
 *  @param request    获取成员请求
 *  @param completion 请求完成回调
 */
- (void)fetchChatroomMembersByIds:(NIMChatroomMembersByIdsRequest *)request
                    completion:(NIMChatroomMembersHandler)completion;
@end                    

NIMChatroomMembersByIdsRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
userIds NSArray 用户ID列表,最多20个

修改自身信息

@protocol NIMChatroomManager <NSObject>
/**
* 修改自身聊天室内信息
*/
- (void)updateMyChatroomMemberInfo:(NIMChatroomMemberInfoUpdateRequest *)request
                        completion:(nullable NIMChatroomHandler)completion;
@end

示例:

NIMChatroomMemberInfoUpdateRequest *request = [[NIMChatroomMemberInfoUpdateRequest alloc] init];
request.roomId = @"123";
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"zhangsan" forKey:@(NIMChatroomMemberInfoUpdateTagNick)];
request.updateInfo = dic;
[[NIMSDK sharedSDK].chatroomManager updateMyChatroomMemberInfo:request 
                                                    completion:^(NSError * _Nullable error) { }];

调用完这个接口后,开发者应该自己修改内存缓存的 聊天室成员 对象。

添加/移除管理员

@protocol NIMChatroomManager <NSObject>
/**
 *  添加/移除聊天室管理员
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)markMemberManager:(NIMChatroomMemberUpdateRequest *)request
              completion:(NIMChatroomHandler)completion;
@end              

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除普通成员

@protocol NIMChatroomManager <NSObject>
/**
 *  添加/移除聊天室普通成员
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)markNormalMember:(NIMChatroomMemberUpdateRequest *)request
            completion:(NIMChatroomHandler)completion;
@end            

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除黑名单用户

@protocol NIMChatroomManager <NSObject>
/**
 *  更新用户聊天室黑名单状态
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)updateMemberBlack:(NIMChatroomMemberUpdateRequest *)request
              completion:(NIMChatroomHandler)completion;
@end              

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

添加/移除禁言用户

@protocol NIMChatroomManager <NSObject>
/**
 *  更新用户聊天室静言状态
 *
 *  @param request    更新请求
 *  @param completion 请求回调
 */
- (void)updateMemberMute:(NIMChatroomMemberUpdateRequest *)request
            completion:(NIMChatroomHandler)completion;
@end            

通过NIMChatroomMemberUpdateRequest - enable来设置是添加还是移除。

踢出成员

创建者或管理员可以将权限比自己低的用户踢出聊天室。

@protocol NIMChatroomManager <NSObject>
/**
 *  将特定成员踢出聊天室
 *
 *  @param request    踢出请求
 *  @param completion 请求回调
 */
- (void)kickMember:(NIMChatroomMemberKickRequest *)request
        completion:(NIMChatroomHandler)completion;
@end        

NIMChatroomMemberKickRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
userId NSString 用户 ID ,仅管理员可以踢人;如userId是管理员仅创建者可以踢
notifyExt NSString 被踢通知扩展字段

临时禁言成员

@protocol NIMChatroomManager <NSObject>

/**
 *  更新用户聊天室临时禁言状态
 *
 *  @param request    更新请求
 *  @param duration   临时禁言时长,单位为秒
 *  @param completion 请求回调
 */
- (void)updateMemberTempMute:(NIMChatroomMemberUpdateRequest *)request
                    duration:(unsigned long long)duration
                  completion:(nullable NIMChatroomHandler)completion;

@end

聊天室队列

聊天室提供队列服务,可结合互动直播连麦场景中的麦位管理使用。权限由 NIMChatroom - queueModificationLevel 决定,可以通过updateChatroomInfo进行修改。默认情况下,所有用户都可以调用接口修改队列内容。

获取聊天室队列

@protocol NIMChatroomManager <NSObject>
/**
 *  获取聊天室队列
 *
 *  @param roomId     聊天室ID
 *  @param completion 请求回调
 */
- (void)fetchChatroomQueue:(NSString *)roomId
                completion:(nullable NIMChatroomQueueInfoHandler)completion;
@end                      

示例

NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager fetchChatroomQueue:roomId 
                                            completion:^(NSError * _Nullable error, NSArray<NSDictionary<NSString *,NSString *> *> * _Nullable info) {
    if (!error)
    {
        //deal with info
    }
    else
    {
        //deal with error
    }
}];

加入或者更新队列元素

若该元素由用户A添加,之后再由用户B更新,则该元素的所有者为用户B。

@protocol NIMChatroomManager <NSObject>
/**
 *  加入或者更新聊天室通用队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定。
 *  
 *  @param request    聊天室队列请求
 *  @param completion 请求回调
 */
- (void)updateChatroomQueueObject:(NIMChatroomQueueUpdateRequest *)request
                       completion:(nullable NIMChatroomHandler)completion;
@end                      

NIMChatroomQueueUpdateRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
key NSString 更新元素的 Key 值,如果 key 在队列中存在则更新,不存在则放到队列尾部 ,长度限制为 32 字节
value NSString 更新元素的 Value 值,长度限制为 4096 字节
transient BOOL 当提交这个新元素到聊天室队列的用户从聊天室掉线或退出的时候,是否需要删除这个元素,默认为 false 不删除。当设置为 YES 时,掉线或退出后,聊天室会发出队列批量元素变更通知 NIMChatroomEventTypeQueueBatchChange

示例

NIMChatroomQueueUpdateRequest *request = [[NIMChatroomQueueUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.key    = @"key";
request.value  = @"value";
request.transient = YES;
[[NIMSDK sharedSDK].chatroomManager updateChatroomQueueObject:request 
                                                   completion:^(NSError * _Nullable error) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];

批量更新队列元素

若该元素由用户A添加,之后再由用户B更新,则该元素的所有者为用户B。

@protocol NIMChatroomManager <NSObject>
/**
 *  批量更新聊天室通用队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param request    聊天室队列批量请求
 *  @param completion 请求回调
 */
- (void)batchUpdateChatroomQueueObject:(NIMChatroomQueueBatchUpdateRequest *)request
                       completion:(nullable NIMChatroomQueueBatchUpdateHandler)completion;
@end                      

NIMChatroomQueueBatchUpdateRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
elements NSDictionary 批量更新元素的key-value对,key/value分别是elementKey和elementValue(elementKey限制128字节,elementValue限制4096字节),一次最多更新100个
needNotify BOOL 是否需要发送广播通知
notifyExt NSString 通知中的自定义字段,长度限制 2048 字节

示例

NIMChatroomQueueBatchUpdateRequest *request = [[NIMChatroomQueueBatchUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.needNotify = YES;
request.notifyExt = @"你收到一个通知";
request.elements = dict;
[[NIMSDK sharedSDK].chatroomManager batchUpdateChatroomQueueObject:request completion:^(NSError * _Nullable error, NSArray<NSString *> * _Nullable elements) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];

移除指定队列元素

@protocol NIMChatroomManager <NSObject>
/**
 *  移除聊天室队列元素,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param request    拉取请求
 *  @param completion 请求回调
 */
- (void)removeChatroomQueueObject:(NIMChatroomQueueRemoveRequest *)request
                       completion:(nullable NIMChatroomQueueRemoveHandler)completion;
@end                      

NIMChatroomQueueRemoveRequest 参数列表

参数 类型 说明
roomId NSString 聊天室 ID
key NSString 指定的元素的Key值,如果是第一个元素,则传空

示例

NIMChatroomQueueRemoveRequest *request = [[NIMChatroomQueueRemoveRequest alloc] init];
request.roomId = @"your_room_id";
request.key    = @"key";
[[NIMSDK sharedSDK].chatroomManager removeChatroomQueueObject:request completion:^(NSError * _Nullable error, NSDictionary<NSString *,NSString *> * _Nullable element) {
    if (!error)
    {
        //deal with removed element
    }
    else
    {
        //deal with error
    }
}];

清空队列

@protocol NIMChatroomManager <NSObject>
/**
 *  删除聊天室队列,权限由 NIMChatroom 的 queueModificationLevel 决定
 *
 *  @param roomId     聊天室ID
 *  @param completion 请求回调
 */
- (void)dropChatroomQueue:(NSString *)roomId
               completion:(nullable NIMChatroomHandler)completion;
@end                      

示例

NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chatroomManager dropChatroomQueue:roomId completion:^(NSError * _Nullable error) {
    if (!error)
    {
        //deal with success
    }
    else
    {
        //deal with error
    }
}];