房间管理
更新时间:
本文主要介绍 云上曲率即时通讯IM SDK的房间管理功能。
功能描述
云上曲率IM SDK为开发者提供如下房间管理内容:
- 加入房间
- 邀请加入房间
- 获取已加入的房间列表
- 退出房间
- 解散房间
注意:目前客户端默认不提供创建房间的接口,由服务端创建。如果开发者需要使用客户端创建房间,请联系云上曲率。
接口说明
房间事件变更通知
房间管理功能中,当出现房间成员变更、房间解散时,会接收到服务端的通知PUSH。
加入房间
用户可以使用enterRoom
接口实现加入已存在的房间。
接口参数说明:
参数
含义
说明
roomId
房间ID
用户待加入的房间ID
extra
附加信息
根据加入房间方式进行处理,如果是输入密码加入,此处为密码内容
attrs
自定义内容
开发者可自行增加业务内容
其中,extra
参数会根据房间信息设置的 “加入房间方式” 来设置。
注意:如果当前房间成员(房主、管理员、普通成员)掉线后重新登录,此时需要重新调用enterRoom
加入房间。
自由加入房间
当 加入房间方式 为 “自由加入” 时:
- 用户调用
enterRoom
直接加入房间。
- 加入后,房间其他成员收到由服务端推送的 房间成员加入 通知。
输入密码加入房间
当 加入房间方式 为 “输入密码加入” 时:
- 用户调用
enterRoom
加入房间,并在extra
中填写房间密码。
- 密码正确,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
- 密码不正确,用户无法加入房间。
注意:加入房间请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个房间的加入请求。请求失效时间默认为 24 小时。
如果房间为密码房间,则密码输入错误后,可以尝试继续输入密码。默认尝试次数不限。
如果需要设定房间加入需要由房主或管理员审核,请联系云上曲率技术人员。
示例代码
public void enterRoom(long roomId, String extra, String attrs, IEmptyCallback callback)
邀请加入房间
用户可以使用inviteIntoRoom
接口实现邀请其他非房间用户加入该用户已加入的房间。
注意:邀请加入房间的用户需要根据房间信息 邀请加入房间方式
中设置的方式来进行调用。
接口参数说明:
参数
含义
说明
roomId
房间ID
邀请用户加入的房间ID
userIds
用户ID
邀请加入房间的用户ID
extra
附加信息
邀请用户加入房间时,可以添加的附加内容
attrs
自定义内容
开发者可配置房间信息等业务内容
房间内所有用户可以邀请加入房间
当 邀请加入房间方式 为 “房间内所有成员均可以邀请” 时:
-
房间成员调用 inviteIntoRoom
接口,邀请房间外用户加入房间。
-
房间外用户发起 ackInviteIntoRoom
回调,进行处理。
ackInviteIntoRoom
接口参数说明:
参数
含义
说明
roomId
房间ID
邀请加入的房间ID
from
用户ID
发起邀请的用户ID
agree
是否同意
被邀请的用户处理是否同意加入房间
attrs
自定义属性
开发者可配置房间信息等业务内容
timeout
超时时间
请求的超时时间,单位为秒
-
邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
-
邀请请求拒绝/请求超时,用户未加入点击。
房主或管理员可以邀请加入房间
当 邀请加入房间方式 为 “只有房主或管理员可以邀请” 时:
- 房主或管理员调用
inviteIntoRoom
接口,邀请房间外用户加入房间。
- 房间外用户发起
ackInviteIntoRoom
回调,进行处理。
- 邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
- 邀请请求拒绝/请求超时,用户未加入房间。
示例代码
public void inviteIntoRoom(long roomId, List<Long> userIds, String extra, String attrs, IEmptyCallback callback)
public void ackInvitedIntoRoom(long roomId, long from, boolean agree, String attrs, IEmptyCallback callback)
获取自己被邀请加入房间的请求列表
用户可以通过getRoomInviteList
接口获取到被哪些房间邀请的请求列表。如果用户已经处理过请求,包括同意邀请或拒绝邀请,那么这些处理过的请求不会通过此接口获取。
注意:如果某请求超时,此接口不会获取到该请求。如果用户此时在房间中,那么当他处理某条房间邀请加入请求为同意时,他会退出当前房间进入到请求同意的房间中。
代码示例
public void getRoomInviteList(ICallback<List<IMInviteInfo>> callback)
获取已加入的房间
用户可以通过getUserRooms
接口获取用户已经加入的所有房间,以列表形式返回。
注意:则此接口不会返回已解散的房间。
代码示例
public void getUserRooms( final ICallback<List<Long>> callback)
移除成员出房间
只有房主或管理员可以通过removeRoomMembers
接口将房间成员移除出房间。
当房间成员被移除出房间后,房间内其他成员会收到由服务端推送的 房间成员被移出房间 通知。
注意:房主可以将管理员和普通成员移除出房间,管理员只可以将普通成员移除出房间。
口参数说明:
参数
含义
说明
roomId
房间ID
要移除成员的房间ID
userIds
用户ID
要被移除出房间的用户ID
代码示例
public void removeRoomMembers(long roomId, List<Long> userIds, IEmptyCallback callback)
退出房间
用户可以通过leaveRoom
接口退出已加入的房间。
退出房间后,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。
当房间成员成功退出房间后,房间内其他成员会收到由服务端推送的 房间成员退出 通知。
接口参数说明:
参数
含义
说明
roomId
房间ID
要退出的房间ID
代码示例
public void leaveRoom(long roomId, IEmptyCallback callback)
解散房间
只有房主可以通过dismissRoom
接口解散所在的房间。
房间解散后,房间内其他成员会收到由服务端推送的 房间已解散 通知,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。
接口参数说明:
参数
含义
说明
roomId
房间ID
要解散的房间ID
代码示例
public void dismissRoom(final long roomId, final IEmptyCallback callback)
本文主要介绍 云上曲率即时通讯IM SDK的房间管理功能。
功能描述
云上曲率IM SDK为开发者提供如下房间管理内容:
- 加入房间
- 邀请加入房间
- 获取已加入的房间列表
- 退出房间
- 解散房间
注意:目前客户端默认不提供创建房间的接口,由服务端创建。如果开发者需要使用客户端创建房间,请联系云上曲率。
接口说明
房间事件变更通知
房间管理功能中,当出现房间成员变更、房间解散时,会接收到服务端的通知PUSH。
加入房间
用户可以使用enterRoom
接口实现加入已存在的房间。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
roomId | 房间ID | 用户待加入的房间ID |
extra | 附加信息 | 根据加入房间方式进行处理,如果是输入密码加入,此处为密码内容 |
attrs | 自定义内容 | 开发者可自行增加业务内容 |
其中,extra
参数会根据房间信息设置的 “加入房间方式” 来设置。
注意:如果当前房间成员(房主、管理员、普通成员)掉线后重新登录,此时需要重新调用
enterRoom
加入房间。
自由加入房间
当 加入房间方式 为 “自由加入” 时:
- 用户调用
enterRoom
直接加入房间。 - 加入后,房间其他成员收到由服务端推送的 房间成员加入 通知。
输入密码加入房间
当 加入房间方式 为 “输入密码加入” 时:
- 用户调用
enterRoom
加入房间,并在extra
中填写房间密码。
- 密码正确,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
- 密码不正确,用户无法加入房间。
注意:加入房间请求只有在一个请求被拒绝或者失效后,才可以发起另一次同一个房间的加入请求。请求失效时间默认为 24 小时。 如果房间为密码房间,则密码输入错误后,可以尝试继续输入密码。默认尝试次数不限。 如果需要设定房间加入需要由房主或管理员审核,请联系云上曲率技术人员。
示例代码
public void enterRoom(long roomId, String extra, String attrs, IEmptyCallback callback)
邀请加入房间
用户可以使用inviteIntoRoom
接口实现邀请其他非房间用户加入该用户已加入的房间。
注意:邀请加入房间的用户需要根据房间信息
邀请加入房间方式
中设置的方式来进行调用。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
roomId | 房间ID | 邀请用户加入的房间ID |
userIds | 用户ID | 邀请加入房间的用户ID |
extra | 附加信息 | 邀请用户加入房间时,可以添加的附加内容 |
attrs | 自定义内容 | 开发者可配置房间信息等业务内容 |
房间内所有用户可以邀请加入房间
当 邀请加入房间方式 为 “房间内所有成员均可以邀请” 时:
-
房间成员调用
inviteIntoRoom
接口,邀请房间外用户加入房间。 -
房间外用户发起
ackInviteIntoRoom
回调,进行处理。ackInviteIntoRoom
接口参数说明:
参数 含义 说明 roomId 房间ID 邀请加入的房间ID from 用户ID 发起邀请的用户ID agree 是否同意 被邀请的用户处理是否同意加入房间 attrs 自定义属性 开发者可配置房间信息等业务内容 timeout 超时时间 请求的超时时间,单位为秒 -
邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
-
邀请请求拒绝/请求超时,用户未加入点击。
房主或管理员可以邀请加入房间
当 邀请加入房间方式 为 “只有房主或管理员可以邀请” 时:
- 房主或管理员调用
inviteIntoRoom
接口,邀请房间外用户加入房间。 - 房间外用户发起
ackInviteIntoRoom
回调,进行处理。 - 邀请请求同意,用户加入房间,房间其他成员收到由服务端推送的 房间成员加入 通知。
- 邀请请求拒绝/请求超时,用户未加入房间。
示例代码
public void inviteIntoRoom(long roomId, List<Long> userIds, String extra, String attrs, IEmptyCallback callback)
public void ackInvitedIntoRoom(long roomId, long from, boolean agree, String attrs, IEmptyCallback callback)
获取自己被邀请加入房间的请求列表
用户可以通过getRoomInviteList
接口获取到被哪些房间邀请的请求列表。如果用户已经处理过请求,包括同意邀请或拒绝邀请,那么这些处理过的请求不会通过此接口获取。
注意:如果某请求超时,此接口不会获取到该请求。如果用户此时在房间中,那么当他处理某条房间邀请加入请求为同意时,他会退出当前房间进入到请求同意的房间中。
代码示例
public void getRoomInviteList(ICallback<List<IMInviteInfo>> callback)
获取已加入的房间
用户可以通过getUserRooms
接口获取用户已经加入的所有房间,以列表形式返回。
注意:则此接口不会返回已解散的房间。
代码示例
public void getUserRooms( final ICallback<List<Long>> callback)
移除成员出房间
只有房主或管理员可以通过removeRoomMembers
接口将房间成员移除出房间。
当房间成员被移除出房间后,房间内其他成员会收到由服务端推送的 房间成员被移出房间 通知。
注意:房主可以将管理员和普通成员移除出房间,管理员只可以将普通成员移除出房间。
口参数说明:
参数 | 含义 | 说明 |
---|---|---|
roomId | 房间ID | 要移除成员的房间ID |
userIds | 用户ID | 要被移除出房间的用户ID |
代码示例
public void removeRoomMembers(long roomId, List<Long> userIds, IEmptyCallback callback)
退出房间
用户可以通过leaveRoom
接口退出已加入的房间。
退出房间后,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。 当房间成员成功退出房间后,房间内其他成员会收到由服务端推送的 房间成员退出 通知。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
roomId | 房间ID | 要退出的房间ID |
代码示例
public void leaveRoom(long roomId, IEmptyCallback callback)
解散房间
只有房主可以通过dismissRoom
接口解散所在的房间。
房间解散后,房间内其他成员会收到由服务端推送的 房间已解散 通知,用户不会再接收该房间的消息推送,并且无法从服务端获取该房间会话和历史消息。
接口参数说明:
参数 | 含义 | 说明 |
---|---|---|
roomId | 房间ID | 要解散的房间ID |
代码示例
public void dismissRoom(final long roomId, final IEmptyCallback callback)