ChatRoomService.java

浏览该文件的文档.

package com.netease.nimlib.sdk.chatroom;

import com.netease.nimlib.apt.annotation.NIMService;
import com.netease.nimlib.sdk.AbortableFuture;
import com.netease.nimlib.sdk.InvocationFuture;
import com.netease.nimlib.sdk.antispam.model.AntiSpamConfig;
import com.netease.nimlib.sdk.chatroom.constant.ChatRoomModeEnum;
import com.netease.nimlib.sdk.chatroom.constant.MemberQueryType;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomInfo;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomMember;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomMemberUpdate;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomMessage;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomSpatialLocation;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomTagsInfo;
import com.netease.nimlib.sdk.chatroom.model.ChatRoomUpdateInfo;
import com.netease.nimlib.sdk.chatroom.model.ChatroomMessageSendOption;
import com.netease.nimlib.sdk.chatroom.model.EnterChatRoomData;
import com.netease.nimlib.sdk.chatroom.model.EnterChatRoomResultData;
import com.netease.nimlib.sdk.chatroom.model.GetMessagesByTagsParam;
import com.netease.nimlib.sdk.chatroom.model.MemberOption;
import com.netease.nimlib.sdk.msg.constant.MsgTypeEnum;
import com.netease.nimlib.sdk.msg.model.QueryDirectionEnum;
import com.netease.nimlib.sdk.robot.model.NimRobotInfo;
import com.netease.nimlib.sdk.util.Entry;
import java.util.List;
import java.util.Map;

/**
 * 聊天室接口
 */
@NIMService("聊天室服务")
public interface ChatRoomService {
    /**
     * 进入聊天室
     *
     * @param roomData 聊天室基本数据（聊天室ID必填）
     * @return InvocationFuture 可取消的回调函数。回调中返回聊天室基本信息
     */
    AbortableFuture<EnterChatRoomResultData> enterChatRoom(EnterChatRoomData roomData);

    /**
     * 进入聊天室
     *
     * @param roomData   聊天室基本数据（聊天室ID必填）
     * @param retryCount 如果进入失败，重试次数
     * @return InvocationFuture 可取消的回调函数。回调中返回聊天室基本信息
     */
    AbortableFuture<EnterChatRoomResultData> enterChatRoomEx(EnterChatRoomData roomData, int retryCount);

    /**
     * 获取进入聊天室失败的错误码
     * 如果是手动登录，在enterChatRoom的回调函数中已有错误码。
     * 如果是断网重连，在自动登录失败时，即监听到在线状态变更为UNLOGIN时，可以采用此接口查看具体自动登录失败的原因。
     *
     * @param roomId 聊天室ID
     * @return 聊天室断网重连、自动登录失败的错误码
     */
    int getEnterErrorCode(String roomId);

    /**
     * 离开聊天室
     *
     * @param roomId 聊天室ID
     */
    void exitChatRoom(String roomId);

    /**
     * 离开聊天室
     *
     * @param mode 聊天室类型
     */
    void exitChatRooms(ChatRoomModeEnum mode);

    /**
     * 发送消息
     *
     * @param msg    带发送的消息体，由{@link ChatRoomMessageBuilder}构造。
     * @param resend 如果是发送失败后重发，标记为true，否则填false。
     * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> sendMessage(ChatRoomMessage msg, boolean resend);

    /**
     * 发送消息
     *
     * @param msg    待发送的消息体，由{@link ChatRoomMessageBuilder}构造。
     * @param resend 如果是发送失败后重发，标记为true，否则填false。
     * @param option 发送聊天室消息Option，可配置路由抄送等参数，可传null。
     * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> sendMessage(ChatRoomMessage msg, boolean resend, ChatroomMessageSendOption option);


    /**
     * 正常情况收到消息后附件会自动下载。如果下载失败，可调用该接口重新下载。
     *
     * @param msg   附件所在的消息体
     * @param thumb 下载缩略图还是原文件。为true时，仅下载缩略图。<br>
     *              该参数仅对图片和视频类消息有效
     * @return AbortableFuture 调用跟踪。可设置回调函数，可中止下载操作
     */
    AbortableFuture<Void> downloadAttachment(ChatRoomMessage msg, boolean thumb);

    /**
     * 获取历史消息，默认从给定时间点往前查询，排序为时间逆序
     *
     * @param roomId    聊天室id
     * @param startTime 时间戳，单位毫秒
     * @param limit     可拉取的消息数量
     * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
     */
    InvocationFuture<List<ChatRoomMessage>> pullMessageHistory(String roomId, long startTime, int limit);

    /**
     * 获取历史消息,可选择给定时间往前或者往后查询，若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序。
     *
     * @param roomId    聊天室id
     * @param startTime 时间戳，单位毫秒
     * @param limit     可拉取的消息数量
     * @param direction 查询方向
     * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
     */
    InvocationFuture<List<ChatRoomMessage>> pullMessageHistoryEx(String roomId, long startTime, int limit, QueryDirectionEnum direction);


    /**
     * 获取历史消息,可选择给定时间往前或者往后查询，以及查询指定一种或多种类型的消息。
     * <p>
     * 若方向往前，则结果排序按时间逆序，反之则结果排序按时间顺序
     * <p>
     * 消息类型仅支持 0:文本，1:图片，2:语音，3:视频，4:地理位置，5:通知，6:文件，10:提示，11:Robot，100:自定义，其它为非法参数
     *
     * @param roomId    聊天室id
     * @param startTime 时间戳，单位毫秒
     * @param limit     可拉取的消息数量
     * @param direction 查询方向
     * @param typeEnums 消息类型，数组
     * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
     */
    InvocationFuture<List<ChatRoomMessage>> pullMessageHistoryExType(String roomId, long startTime, int limit, QueryDirectionEnum direction, MsgTypeEnum[] typeEnums);

    /**
     * 通过标签从云端拉取消息
     * @param param 参数
     * @return InvocationFuture 可以设置回调函数。回调中返回历史消息列表
     */
    InvocationFuture<List<ChatRoomMessage>> getMessagesByTags(GetMessagesByTagsParam param);

    /**
     * 获取当前聊天室信息
     *
     * @param roomId 聊天室id
     * @return InvocationFuture 可以设置回调函数。回调中返回聊天室的信息
     */
    InvocationFuture<ChatRoomInfo> fetchRoomInfo(String roomId);

    /**
     * 获取聊天室成员信息
     *
     * @param roomId          聊天室id
     * @param memberQueryType 成员查询类型。见{@link MemberQueryType}
     * @param time            固定成员列表用updateTime,
     *                        游客列表用进入enterTime，
     *                        填0会使用当前服务器最新时间开始查询，即第一页，单位毫秒
     * @param limit           条数限制
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
     */
    InvocationFuture<List<ChatRoomMember>> fetchRoomMembers(String roomId, MemberQueryType memberQueryType, long time, int limit);

    /**
     * 获取聊天室成员信息
     *
     * @param roomId          聊天室id
     * @param tag             标签
     * @param time            起始时间，逆序查询，若传0则表示从当前时间往前查
     * @param limit           条数
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
     */
    InvocationFuture<List<ChatRoomMember>> fetchRoomMembersByTag(String roomId, String tag, long time, int limit);

    /**
     * 根据用户id获取聊天室成员信息
     *
     * @param roomId   聊天室id
     * @param accounts 成员帐号列表
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
     */
    InvocationFuture<List<ChatRoomMember>> fetchRoomMembersByIds(String roomId, List<String> accounts);

    /**
     * 根据用户id获取聊天室成员信息
     *
     * @param roomId   聊天室id
     * @param tag      标签
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息列表
     */
    InvocationFuture<Long> queryTagMembersCount(String roomId, String tag);

    /**
     * 添加/移出聊天室黑名单
     *
     * @param isAdd        true:添加, false:移出
     * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
     */
    InvocationFuture<ChatRoomMember> markChatRoomBlackList(boolean isAdd, MemberOption memberOption);

    /**
     * 添加到禁言名单/取消禁言
     *
     * @param isAdd        true:添加, false:取消
     * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
     */
    InvocationFuture<ChatRoomMember> markChatRoomMutedList(boolean isAdd, MemberOption memberOption);

    /**
     * 设置聊天室成员临时禁言
     *
     * @param needNotify   是否需要发送广播通知，true：通知，false：不通知
     * @param duration     禁言时长,单位秒
     * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
     * @return InvocationFuture 可以设置回调函数。如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> markChatRoomTempMute(boolean needNotify, long duration, MemberOption memberOption);

    /**
     * 禁言某个标签的用户的发言，只有管理员或创建者能操作
     *
     * @param roomId       聊天室id
     * @param targetTag    禁言的tag
     * @param needNotify   是否需要发送广播通知，true：通知，false：不通知
     * @param duration     禁言时长,单位秒
     * @param notifyExtension 操作产生的通知事件中开发者自定义的扩展字段（可选）
     * @param notifyTargetTags 禁言通知广播的目标标签，默认是TARGET_TAG，这是一个标签表达式
     * @return InvocationFuture 可以设置回调函数。如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> markChatRoomTempMuteByTag(String roomId, String targetTag, boolean needNotify, long duration, Map<String, Object> notifyExtension, String notifyTargetTags);

    /**
     * 设为/取消聊天室管理员
     *
     * @param isAdd        true:设为, false:取消
     * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
     */
    InvocationFuture<ChatRoomMember> markChatRoomManager(boolean isAdd, MemberOption memberOption);

    /**
     * 设为/取消聊天室普通成员
     *
     * @param isAdd        true:设为, false:取消
     * @param memberOption 请求参数，包含聊天室id，帐号id以及可选的扩展字段
     * @return InvocationFuture 可以设置回调函数。回调中返回成员信息
     */
    InvocationFuture<ChatRoomMember> markNormalMember(boolean isAdd, MemberOption memberOption);

    /**
     * 踢掉特定成员
     *
     * @param roomId          聊天室id
     * @param account         踢出成员帐号。仅管理员可以踢；如目标是管理员仅创建者可以踢
     * @param notifyExtension 被踢通知扩展字段，这个字段会放到被踢通知的扩展字段中
     * @return InvocationFuture 可以设置回调函数。踢掉成员完成之后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> kickMember(String roomId, String account, Map<String, Object> notifyExtension);

    /**
     * 更新聊天室信息
     *
     * @param roomId             聊天室id
     * @param chatRoomUpdateInfo 可更新的聊天室信息
     * @param needNotify         是否通知
     * @param notifyExtension    更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
     * @return InvocationFuture 可以设置回调函数。更新聊天室信息完成之后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> updateRoomInfo(String roomId, ChatRoomUpdateInfo chatRoomUpdateInfo, boolean needNotify, Map<String, Object> notifyExtension);

    /**
     * 更新聊天室信息
     *
     * @param roomId             聊天室id
     * @param chatRoomUpdateInfo 可更新的聊天室信息
     * @param needNotify         是否通知
     * @param notifyExtension    更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中
     * @param antiSpamConfig     反垃圾配置参数
     * @return InvocationFuture 可以设置回调函数。更新聊天室信息完成之后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> updateRoomInfo(String roomId, ChatRoomUpdateInfo chatRoomUpdateInfo, boolean needNotify, Map<String, Object> notifyExtension,
        AntiSpamConfig antiSpamConfig);

    /**
     * 更新本人在聊天室内的信息
     *
     * @param roomId               聊天室id
     * @param chatRoomMemberUpdate 可更新的本人角色信息
     * @param needNotify           是否通知
     * @param notifyExtension      更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中,最大长度2k
     * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension);

    /**
     * 更新本人在聊天室内的信息
     *
     * @param roomId               聊天室id
     * @param chatRoomMemberUpdate 可更新的本人角色信息
     * @param needNotify           是否通知
     * @param notifyExtension      更新聊天室信息扩展字段，这个字段会放到更新聊天室信息通知的扩展字段中,最大长度2k
     * @param antiSpamConfig       反垃圾配置参数
     * @return InvocationFuture     可以设置回调函数。更新信息完成之后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> updateMyRoomRole(String roomId, ChatRoomMemberUpdate chatRoomMemberUpdate, boolean needNotify, Map<String, Object> notifyExtension,AntiSpamConfig antiSpamConfig);

    /**
     * 聊天室队列服务：加入或者更新队列元素
     *
     * @param roomId 聊天室id
     * @param key    新元素（或待更新元素）的唯一键
     * @param value  新元素（待待更新元素）的内容
     * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
     */
    InvocationFuture<Void> updateQueue(String roomId, String key, String value);

    /**
     * 聊天室队列服务：加入或者更新队列元素，支持当用户掉线或退出聊天室后，是否删除这个元素
     *
     * @param roomId      聊天室id
     * @param key         新元素（或待更新元素）的唯一键
     * @param value       新元素（待待更新元素）的内容
     * @param isTransient true表示当提交这个新元素的用户从聊天室掉线或退出的时候，需要删除这个元素；默认false表示不删除
     * @return InvocationFuture 可以设置回调函数。回调中返回操作成功或者失败具体的错误码。
     */
    InvocationFuture<Void> updateQueueEx(String roomId, String key, String value, boolean isTransient);

    /**
     * 聊天室队列服务：加入或者更新队列元素，支持当用户掉线或退出聊天室后，是否删除这个元素
     *
     * @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);


    /**
     * 聊天室队列服务 ： 批量更新元素
     *
     * @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);

    /**
     * 聊天室队列服务：取出队列头部或者指定元素
     *
     * @param roomId 聊天室id
     * @param key    需要取出的元素的唯一键。若为 null，则表示取出队头元素
     * @return InvocationFuture 可以设置回调函数。如果元素存在或者队列不为空，那么回调中返回元素的键值对，否则返回失败错误码。
     */
    InvocationFuture<Entry<String, String>> pollQueue(String roomId, String key);

    /**
     * 聊天室队列服务：排序列出所有队列元素
     *
     * @param roomId 聊天室id
     * @return InvocationFuture 可设置回调函数。回调中返回所有排列的队列元素键值对。
     */
    InvocationFuture<List<Entry<String, String>>> fetchQueue(String roomId);

    /**
     * 聊天室队列服务：删除队列
     *
     * @param roomId 聊天室id
     * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
     */
    InvocationFuture<Void> dropQueue(String roomId);

    /**
     * 独立聊天室场景下，获取当前全部聊天室机器人
     *
     * @param roomId 当前聊天室id
     * @return InvocationFuture 可设置回调函数。回调中返回操作成功或者失败具体的错误码。
     */
    InvocationFuture<List<NimRobotInfo>> pullAllRobots(String roomId);

    /**
     * 更新聊天室标签
     * @param roomId 当前聊天室id
     * @param tagsInfo 标签信息
     * @return
     */
    InvocationFuture<Void> updateChatRoomTags(String roomId, ChatRoomTagsInfo tagsInfo);

    /**
     * 更新位置信息
     * 注意：每300ms只能上报一次位置信息给服务器，300ms 内多次调用返回 416
     * @param roomId 当前聊天室id
     * @param location 空间位置信息
     * @return
     */
    InvocationFuture<Void> updateLocation(String roomId, ChatRoomSpatialLocation location);
}