IM 即时通讯
Android
开发指南

聊天室队列服务

更新时间: 2023/09/04 15:31:54

聊天室队列

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

获取聊天室队列

/**
 * 聊天室队列服务:排序列出所有队列元素
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回所有排列的队列元素键值对。
 */
InvocationFuture<List<Entry<String, String>>> fetchQueue(String roomId);
  • 示例
NIMClient.getService(ChatRoomService.class).fetchQueue(roomId).setCallback(new RequestCallback<List<Entry<String, String>>>() {
    @Override
    public void onSuccess(List<Entry<String, String>> param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});

加入或者更新队列元素

用户使用该接口加入或更新的元素,当 isTransient 参数为 true 时,表示当该用户掉线或退出聊天室时,服务器会自动删除该用户加入或更新的元素。

同时,服务器将发出聊天室通知消息,通知消息的类型为 NotificationType#ChatRoomQueueBatchChange,通知消息的附件类型为 ChatRoomPartClearAttachment,该通知消息属于队列变更通知,所以附件类型中包含了队列变更类型 ChatRoomQueueChangeType#PARTCLEAR

/**
 * 聊天室队列服务:加入或者更新队列元素,支持当用户掉线或退出聊天室后,是否删除这个元素
 *
 * @param roomId      聊天室id
 * @param key         新元素(或待更新元素)的唯一键
 * @param value       新元素(待待更新元素)的内容
 * @param isTransient true表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认false表示不删除
 * @param elementAccid 队列元素所属账号,默认不传表示队列元素属于当前操作人,管理员可以指定队列元素归属于其他合法账号
 * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> updateQueue(String roomId, String key, String value, boolean isTransient, String elementAccid);
  • 参数说明
参数 说明
roomId 聊天室 id
key 新元素(或待更新元素)的唯一键
value 新元素(待待更新元素)的内容
isTransient (可选参数)
true 表示当提交这个新元素的用户从聊天室掉线或退出的时候,需要删除这个元素;默认false表示不删除
elementAccid (可选参数)
队列元素所属账号,默认不传表示队列元素属于当前操作人,管理员可以指定队列元素归属于其他合法账号

ChatRoomPartClearAttachment 说明

返回值 ChatRoomPartClearAttachment 接口 说明
ChatRoomQueueChangeType getChatRoomQueueChangeType() 返回队列变更类型,值为 ChatRoomQueueChangeType.PARTCLEAR
Map getContentMap() 当用户掉线或退出聊天室时,返回用户使用 updateQueueEx 接口,并设置 isTransient 参数为true 时,加入或更新的元素
  • 示例
NIMClient.getService(ChatRoomService.class)
         .updateQueueEx(roomId, "this is key", "this is value", true)
         .setCallback(new RequestCallback<Void>() {
            @Override
            public void onSuccess(Void param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 失败
            }

            @Override
            public void onException(Throwable exception) {
				// 错误
            }
        });

批量更新队列元素

只会更新已经存在的key,不会加入新元素。

/**
 * 聊天室队列服务 : 批量更新元素
 *
 * @param roomId     聊天室id
 * @param queues     待更新的队列元素
 * @param needNotify 是否需要发送广播通知
 * @param notifyExt  通知中的自定义字段,最大长度2k
 * @return 不存在的元素elementKey列表
 */
InvocationFuture<List<String>> batchUpdateQueue(String roomId, List<Entry<String, String>> queues, boolean needNotify, Map<String, Object> notifyExt);
  • 示例
List<Entry<String, String>> queues = new ArrayList<>();
        queues.add(new Entry<String, String>("key", "value1"));
        queues.add(new Entry<String, String>("key1", "value2"));
        queues.add(new Entry<String, String>("key2", "value3" ));

        Map<String, Object> notifyExt = new HashMap<>();
        notifyExt.put("notes", "notes_vaules");
        NIMClient.getService(ChatRoomService.class).batchUpdateQueue(roomId, queues, true, notifyExt).setCallback(new RequestCallback<List<String>>() {
            @Override
            public void onSuccess(List<String> result) {
               // 成功
               //result :不存在的元素的key list
            }

            @Override
            public void onFailed(int code) {
               //失败
            }

            @Override
            public void onException(Throwable exception) {
             //异常
               
            }
        });

移除指定队列元素

key是唯一键。key 若为 null, 则表示取出头元素。若不为 null, 则表示取出指定元素。

/**
 * 聊天室队列服务:取出队列头部或者指定元素
 *
 * @return InvocationFuture 可以设置回调函数。如果元素存在或者队列不为空,那么回调中返回元素的键值对,否则返回失败错误码。
 */
InvocationFuture<Entry<String, String>> pollQueue(String roomId, String key);
  • 参数说明
参数 说明
roomId 聊天室 id
key 需要取出的元素的唯一键。若为 null,则表示取出队头元素
  • 示例
NIMClient.getService(ChatRoomService.class).pollQueue(roomId, "this is key"
        .setCallback(new RequestCallback<Entry<String, String>>() {
            @Override
            public void onSuccess(Entry<String, String> param) {
                // 成功
            }

            @Override
            public void onFailed(int code) {
                // 错误
            }

            @Override
            public void onException(Throwable exception) {
				// 失败
            }
        });

清空队列

/**
 * 聊天室队列服务:删除队列
 *
 * @param roomId 聊天室id
 * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
 */
InvocationFuture<Void> dropQueue(String roomId);
  • 示例
NIMClient.getService(ChatRoomService.class).dropQueue(roomId).setCallback(new RequestCallback<Void>() {
    @Override
    public void onSuccess(Void param) {
        // 成功
    }

    @Override
    public void onFailed(int code) {
        // 失败
    }

    @Override
    public void onException(Throwable exception) {
		// 错误
    }
});
此文档是否对你有帮助?
有帮助
去反馈
  • 聊天室队列
  • 获取聊天室队列
  • 加入或者更新队列元素
  • 批量更新队列元素
  • 移除指定队列元素
  • 清空队列