房间管理

本文主要介绍 云上曲率即时通讯IM SDK的房间管理功能。

功能描述

云上曲率IM SDK为开发者提供如下房间管理内容:

  • 加入房间
  • 邀请加入房间
  • 获取已加入的房间列表
  • 退出房间
  • 解散房间

注意:目前客户端默认不提供创建房间的接口,由服务端创建。如果开发者需要使用客户端创建房间,请联系云上曲率。

接口说明

房间事件变更通知

房间管理功能中,当出现房间成员变更、房间解散时,会接收到服务端的通知PUSH。

加入房间

用户可以使用joinRoom接口实现加入已存在的房间。

接口参数说明:

参数 含义 说明
roomId 房间ID 用户待加入的房间ID
extra 附加信息 根据加入房间方式进行处理,如果是输入密码加入,此处为密码内容
attrs 自定义内容 开发者可自行增加业务内容
timeout 超时时间 加入房间请求的超时时间,单位为秒

其中,extra参数会根据房间信息设置的 “加入房间方式” 来设置。

注意:如果当前房间成员(房主、管理员、普通成员)掉线后重新登录,此时需要重新调用joinRoom加入房间。

自由加入房间

加入房间方式“自由加入” 时:

  1. 用户调用 joinRoom 直接加入房间。
  2. 加入后,房间其他成员收到由服务端推送的 房间成员加入 通知。
输入密码加入房间

加入房间方式“输入密码加入” 时:

  1. 用户调用 joinRoom 加入房间,并在extra中填写房间密码。
  1. 密码正确,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
  2. 密码不正确,用户无法加入房间。

注意:加入房间请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个房间的加入请求。请求失效时间默认为 24 小时。 如果房间为密码房间,则密码输入错误后,可以尝试继续输入密码。默认尝试次数不限。 如果需要设定房间加入需要由房主或管理员审核,请联系云上曲率技术人员。

示例代码
-(void)joinRoom:(NSNumber * _Nonnull)roomId
          extra:(NSString * _Nullable)extra
          attrs:(NSString * _Nullable)attrs
        timeout:(int)timeout
        success:(void(^)(void))successCallback
           fail:(IMAnswerFailCallBack)failCallback;

邀请加入房间

用户可以使用inviteIntoRoom接口实现邀请其他非房间用户加入该用户已加入的房间。

注意:邀请加入房间的用户需要根据房间信息 邀请加入房间方式 中设置的方式来进行调用。

接口参数说明:

参数 含义 说明
roomId 房间ID 邀请用户加入的房间ID
uids 用户ID 邀请加入房间的用户ID
extra 附加信息 邀请用户加入房间时,可以添加的附加内容
attrs 自定义内容 开发者可配置房间信息等业务内容
timeout 超时时间 邀请请求超时时间,单位为秒
房间内所有用户可以邀请加入房间

邀请加入房间方式“房间内所有成员均可以邀请” 时:

  1. 房间成员调用 inviteIntoRoom接口,邀请房间外用户加入房间。

  2. 房间外用户发起 ackInviteIntoRoom回调,进行处理。

    • ackInviteIntoRoom接口参数说明:
    参数 含义 说明
    roomId 房间ID 邀请加入的房间ID
    fromId 用户ID 发起邀请的用户ID
    agree 是否同意 被邀请的用户处理是否同意加入房间
    attrs 自定义属性 开发者可配置房间信息等业务内容
    timeout 超时时间 请求的超时时间,单位为秒
  3. 邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。

  4. 邀请请求拒绝/请求超时,用户未加入点击。

房主或管理员可以邀请加入房间

邀请加入房间方式“只有房主或管理员可以邀请” 时:

  1. 房主或管理员调用 inviteIntoRoom接口,邀请房间外用户加入房间。
  2. 房间外用户发起 ackInviteIntoRoom回调,进行处理。
  3. 邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
  4. 邀请请求拒绝/请求超时,用户未加入房间。
示例代码
-(void)inviteRoom:(NSNumber * _Nonnull)roomId
             uids:(NSArray <NSNumber*> * _Nullable)uids
            extra:(NSString * _Nullable)extra
            attrs:(NSString * _Nullable)attrs
          timeout:(int)timeout
          success:(void(^)(void))successCallback
             fail:(IMAnswerFailCallBack)failCallback;
-(void)ackinviteRoom:(NSNumber * _Nonnull)roomId
                 from:(NSNumber * _Nullable)fromId
                agree:(BOOL)agree
                attrs:(NSString * _Nullable)attrs
              timeout:(int)timeout
              success:(void(^)(void))successCallback
                 fail:(IMAnswerFailCallBack)failCallback;

获取自己被邀请加入房间的请求列表

用户可以通过getRoomInviteList接口获取到被哪些房间邀请的请求列表。如果用户已经处理过请求,包括同意邀请或拒绝邀请,那么这些处理过的请求不会通过此接口获取。

注意:如果某请求超时,此接口不会获取到该请求。如果用户此时在房间中,那么当他处理某条房间邀请加入请求为同意时,他会退出当前房间进入到请求同意的房间中。

接口参数说明:

参数 含义 说明
timeout 超时时间 请求的超时时间,单位为秒
代码示例
-(void)getRoomInviteList:(int)timeout
                 success:(void(^)(NSArray <IMGetRoomInviteList * > * array))successCallback
                    fail:(IMAnswerFailCallBack)failCallback;

获取已加入的房间

用户可以通过getRoomList接口获取用户已经加入的所有房间,以列表形式返回。

注意:则此接口不会返回已解散的房间。

接口参数说明:

参数 含义 说明
timeout 超时时间 请求的超时时间,单位为秒
代码示例
-(void)getRoomList:(int)timeout
           success:(void(^)(NSArray * _Nullable roomArray))successCallback
              fail:(IMAnswerFailCallBack)failCallback;

移除成员出房间

只有房主或管理员可以通过removeRoomMembers接口将房间成员移除出房间。

当房间成员被移除出房间后,房间内其他成员会收到由服务端推送的 房间成员被移出房间 通知。

注意:房主可以将管理员和普通成员移除出房间,管理员只可以将普通成员移除出房间。

口参数说明:

参数 含义 说明
roomId 房间ID 要移除成员的房间ID
uids 用户ID 要被移除出房间的用户ID
timeout 超时时间 请求的超时时间,单位为秒
代码示例
-(void)removeRoomMembers:(NSNumber * _Nonnull)roomId
                    uids:(NSArray <NSNumber*>*)uids
                 timeout:(int)timeout
                 success:(void(^)(void))successCallback
                    fail:(IMAnswerFailCallBack)failCallback;

退出房间

用户可以通过leaveRoom接口退出已加入的房间。

退出房间后,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。 当房间成员成功退出房间后,房间内其他成员会收到由服务端推送的 房间成员退出 通知。

接口参数说明:

参数 含义 说明
roomId 房间ID 要退出的房间ID
timeout 超时时间 请求的超时时间,单位为秒
代码示例
-(void)leaveRoom:(NSNumber * _Nonnull)roomId
         timeout:(int)timeout
         success:(void(^)(void))successCallback
            fail:(IMAnswerFailCallBack)failCallback;

解散房间

只有房主可以通过dismissRoom接口解散所在的房间。

房间解散后,房间内其他成员会收到由服务端推送的 房间已解散 通知,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。

接口参数说明:

参数 含义 说明
roomId 房间ID 要解散的房间ID
timeout 超时时间 请求的超时时间,单位为秒
代码示例
-(void)dismissRoom:(NSNumber * _Nonnull)roomId
            timeout:(int)timeout
            success:(void(^)(void))successCallback
               fail:(IMAnswerFailCallBack)failCallback;