SuperTeamService.java

浏览该文件的文档.

package com.netease.nimlib.sdk.superteam;

import com.netease.nimlib.apt.annotation.NIMService;
import com.netease.nimlib.sdk.InvocationFuture;
import com.netease.nimlib.sdk.NIMClient;
import com.netease.nimlib.sdk.Observer;
import com.netease.nimlib.sdk.antispam.model.AntiSpamConfig;
import com.netease.nimlib.sdk.msg.MessageBuilder;
import com.netease.nimlib.sdk.msg.MsgServiceObserve;
import com.netease.nimlib.sdk.msg.model.IMMessage;
import com.netease.nimlib.sdk.msg.model.MsgSendOption;
import com.netease.nimlib.sdk.msg.model.SessionAckInfo;
import com.netease.nimlib.sdk.superteam.model.NIMSuperTeamMemberSearchResult;
import com.netease.nimlib.sdk.team.constant.TeamFieldEnum;
import com.netease.nimlib.sdk.team.constant.TeamMessageNotifyTypeEnum;
import com.netease.nimlib.sdk.team.model.NIMTeamMemberKeywordSearchOption;
import com.netease.nimlib.sdk.team.model.NIMTeamMemberRoleTypeSearchOption;
import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

/**
 * Created by hzsunyj on 2019-05-16.
 */
@NIMService("超大群服务")
public interface SuperTeamService {

    /**
     * 发送消息。<br>
     * 如果需要更新发送进度，请调用{@link MsgServiceObserve#observeMsgStatus(com.netease.nimlib.sdk.Observer, boolean)}
     *
     * @param msg    带发送的消息体，由{@link MessageBuilder}构造
     * @param resend 如果是发送失败后重发，标记为true，否则填false
     * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> sendMessage(IMMessage msg, boolean resend);
    /**
     * 发送消息。
     *
     * 该方法为异步。如需更新发送进度，请调用 {@link MsgServiceObserve#observeMsgStatus}。
     *
     * @par 使用前提：
     * 已调用 MessageBuilder#createXXMessage 创建一条消息。
     *
     * @param msg    待发送的 IMMessage 消息体，由 {@link MessageBuilder} 构造。
     * @param resend true 表示消息发送失败后重发；false 表示消息发送失败后不重发。
     * @param option 消息发送选项
     * @return InvocationFuture<Void> 可设置回调函数：消息发送成功后返回通知；消息发送失败后返回具体错误码。
     */
    InvocationFuture<Void> sendMessage(IMMessage msg, boolean resend, MsgSendOption option);

    /**
     * 回复消息。<br>
     * 如果需要更新发送进度，请调用{@link MsgServiceObserve#observeMsgStatus(com.netease.nimlib.sdk.Observer, boolean)}
     *
     * @param msg    带发送的消息体，由{@link MessageBuilder}构造
     * @param replyMsg 被回复的消息
     * @param resend 如果是发送失败后重发，标记为true，否则填false
     * @return InvocationFuture 可以设置回调函数。消息发送完成后才会调用，如果出错，会有具体的错误代码。
     */
    InvocationFuture<Void> replyMessage(IMMessage msg, IMMessage replyMsg, boolean resend);

    /**
     * 回复消息。
     *
     * 该方法为异步。如需更新发送进度，请调用 {@link MsgServiceObserve#observeMsgStatus}。
     *
     * @par 使用前提：
     * - 已收到一条消息。
     * - 已调用 MessageBuilder#createXXMessage 构建一条消息。
     *
     * @param msg    待发送的 IMMessage 消息体，由 {@link MessageBuilder} 构造。
     * @param replyMsg 被回复的 IMMessage 消息体，由 {@link MessageBuilder} 构造。
     * @param resend true 表示消息回复失败后重发；false 表示消息回复失败后不重发。
     * @param option 消息发送选项
     * @return InvocationFuture<Void> 可设置回调函数：消息回复成功后返回通知；消息回复失败后返回具体错误码。
     */
    InvocationFuture<Void> replyMessage(IMMessage msg, IMMessage replyMsg, boolean resend,MsgSendOption option);

    /**
     * 邀请成员
     *
     * @param teamId   群组ID
     * @param accounts 待加入的群成员帐号列表
     * @param postscript 附言，长度不得超过5000
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<List<String>> addMembers(String teamId, List<String> accounts, String postscript);

    /**
     * 移出群成员，只有群主有权限
     *
     * @param teamId 群ID
     * @param member 被踢出的成员帐号
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> removeMember(String teamId, String member);

    /**
     * 批量移出群成员，只有群主有权限
     *
     * @param teamId  群ID
     * @param members 被踢出的成员帐号列表
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> removeMembers(String teamId, List<String> members);

    /**
     * 退出群
     *
     * @param teamId 群ID
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> quitTeam(String teamId);

    /**
     * 将指定最近联系人的未读数清零(标记已读)。<br>
     * 调用该接口后，会触发{@link MsgServiceObserve#observeRecentContact(Observer, boolean)}
     */
    InvocationFuture<List<SessionAckInfo>> clearUnreadCount(List<String> teamIdList);


    /**
     * 更新群组资料
     *
     * @param teamId 群ID
     * @param field  待更新的域
     * @param value  待更新的域的新值
     *               该值类型必须和field中定义的fieldType一致
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateTeam(String teamId, TeamFieldEnum field, Serializable value);

    /**
     * 批量更新群组资料，可一次性更新多个字段的值。
     *
     * @param teamId 群ID
     * @param fields 待更新的所有字段的新的资料，其中值类型必须和field中定义的fieldType一致
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateTeamFields(String teamId, Map<TeamFieldEnum, Serializable> fields);

    /**
     * 批量更新群组资料，可一次性更新多个字段的值。
     *
     * @param teamId         群ID
     * @param fields         待更新的所有字段的新的资料，其中值类型必须和field中定义的fieldType一致
     * @param antiSpamConfig 反垃圾相关配置参数
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateTeamFields(String teamId, Map<TeamFieldEnum, Serializable> fields,
        AntiSpamConfig antiSpamConfig);

    /**
     * 获取自己加入的群的列表
     *
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为自己加入的群的列表
     */
    InvocationFuture<List<SuperTeam>> queryTeamList();

    /**
     * 获取自己加入的群的列表(同步版本)
     *
     * @return 自己加入的群的列表
     */
    List<SuperTeam> queryTeamListBlock();

    /**
     * 根据群id列表批量查询群信息
     *
     * @param tidList 群id列表
     * @return 可以设置回调函数，如果成功，参数为查询的群信息列表
     */
    InvocationFuture<List<SuperTeam>> queryTeamListById(List<String> tidList);

    /**
     * 根据群id列表批量查询群信息（同步版本）
     *
     * @param tidList 群id列表
     * @return 查询的群信息列表
     */
    List<SuperTeam> queryTeamListByIdBlock(List<String> tidList);

    /**
     * 查询群资料，如果本地没有群组资料，则去服务器查询。<br>
     * 如果自己不在这个群中，该接口返回的可能是过期资料，如需最新的，请调用{@link #searchTeam(String teamId)}接口
     *
     * @param teamId 群ID
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为群资料
     */
    InvocationFuture<SuperTeam> queryTeam(String teamId);

    /**
     * 查询群资料（仅查询本地，不会去服务器请求)
     * 如果自己不在这个群中，该接口返回的可能是过期资料，如需最新的，请调用{@link #searchTeam(String teamId)}接口
     *
     * @param teamId 群ID
     * @return 群资料
     */
    SuperTeam queryTeamBlock(String teamId);

    /**
     * 从服务器上查询群资料信息
     *
     * @param teamId
     * @return
     */
    InvocationFuture<SuperTeam> searchTeam(String teamId);

    /**
     * 获取指定群的成员信息列表. <br>
     * 该操作有可能只是从本地数据库读取缓存数据，也有可能会从服务器同步新的数据, 因此耗时可能会比较长。
     *
     * @param teamId 群ID
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为群的成员信息列表
     */
    InvocationFuture<List<SuperTeamMember>> queryMemberList(String teamId);


    /**
     * 分页获取指定群的成员信息列表. <br>
     * 该操作有可能只是从本地数据库读取缓存数据，也有可能会从服务器同步新的数据, 因此耗时可能会比较长。
     *
     * @param teamId 群ID
     * @param offset 偏移位置
     * @param limit  获取条数，每次最多200
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为群的成员信息列表
     */
    InvocationFuture<List<SuperTeamMember>> queryMemberListByPage(String teamId, int offset, int limit);

    /**
     * 查询群成员资料。如果本地群成员资料已过期会去服务器获取最新的。
     *
     * @param teamId  群ID
     * @param account 群成员帐号
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为该群成员信息
     */
    InvocationFuture<SuperTeamMember> queryTeamMember(String teamId, String account);

    /**
     * 查询群成员资料。（同步版本）
     *
     * @param teamId  群ID
     * @param account 群成员帐号
     * @return 群成员信息
     */
    SuperTeamMember queryTeamMemberBlock(String teamId, String account);

    /**
     * 查询被禁言群成员列表
     * 该操作，只返回调用{@link SuperTeamService#muteTeamMembers(String, ArrayList, boolean)} 禁言的用户。
     *
     * @param teamId 群ID
     * @return 群成员信息列表
     */
    List<SuperTeamMember> queryMutedTeamMembers(String teamId);

    /**
     * 修改自己的群昵称
     *
     * @param teamId 所在群组ID
     * @param nick   新的群昵称
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateMyTeamNick(String teamId, String nick);


    /**
     * 修改自己的群成员扩展字段（自定义属性，最长32个字符）
     *
     * @param teamId    所在群组ID
     * @param extension 扩展字段（自定义属性）
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateMyMemberExtension(String teamId, String extension);

    /**
     * 设置指定群消息通知类型，查看{@link com.netease.nimlib.sdk.team.constant.TeamMessageNotifyTypeEnum}
     *
     * @param teamId     群组ID
     * @param notifyType 通知类型枚举
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> muteTeam(String teamId, TeamMessageNotifyTypeEnum notifyType);


    /**
     * 消息撤回 ，默认没有第三方推送（包括IOS平台的推送），参考{@link SuperTeamService#revokeMessage(IMMessage, String, Map)}
     *
     * @param message 待撤回的消息
     * @return InvocationFuture 可设置回调函数，监听发送结果。
     */
    InvocationFuture<Void> revokeMessage(IMMessage message);


    /**
     * 消息撤回 ， 并设置相应的第三方推送配置（包括IOS平台的推送），如果想要关闭App内的返回消息提醒，参考{@link NIMClient#toggleRevokeMessageNotification(boolean on)}
     *
     * @param message        待撤回的消息
     * @param customApnsText 第三方透传消息推送文本，不填则不推送
     * @param pushPayload    第三方自定义的推送属性，限制json，长度2048
     * @return InvocationFuture 可设置回调函数，监听发送结果。
     */
    InvocationFuture<Void> revokeMessage(IMMessage message, String customApnsText, Map<String, Object> pushPayload);


    /**
     * 消息撤回 ， 并设置相应的第三方推送配置（包括IOS平台的推送），如果想要关闭App内的返回消息提醒，参考{@link NIMClient#toggleRevokeMessageNotification(boolean on)}
     *
     * @param message        待撤回的消息
     * @param customApnsText 第三方透传消息推送文本，不填则不推送
     * @param pushPayload    第三方自定义的推送属性，限制json，长度2048
     * @param shouldNotifyBeCount 撤回通知是否更新未读数
     * @return InvocationFuture 可设置回调函数，监听发送结果。
     */
    InvocationFuture<Void> revokeMessage(IMMessage message, String customApnsText, Map<String, Object> pushPayload, boolean shouldNotifyBeCount);

    /**
     * 消息撤回 ， 并设置相应的第三方推送配置（包括IOS平台的推送），如果想要关闭App内的返回消息提醒，参考{@link NIMClient#toggleRevokeMessageNotification(boolean on)}
     *
     * @param message        待撤回的消息
     * @param customApnsText 第三方透传消息推送文本，不填则不推送
     * @param pushPayload    第三方自定义的推送属性，限制json，长度2048
     * @param shouldNotifyBeCount 撤回通知是否更新未读数
     * @param postscript 附言
     * @return InvocationFuture 可设置回调函数，监听发送结果。
     */
    InvocationFuture<Void> revokeMessage(IMMessage message, String customApnsText,
                                         Map<String, Object> pushPayload, boolean shouldNotifyBeCount,
                                         String postscript);

    /**
     * 搜索与关键字匹配的所有群
     *
     * @return 群集合
     */
    InvocationFuture<List<SuperTeam>> searchTeamsByKeyword(String keyword);

    /**
     * 用户申请加入群。
     *
     * @param tid        申请加入的群ID
     * @param postscript 附言，长度不得超过5000
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为群资料
     */
    InvocationFuture<SuperTeam> applyJoinTeam(String tid, String postscript);

    /**
     * 通过用户的入群申请<br>
     * 仅群主和管理员拥有者有此权限
     *
     * @param teamId  群ID
     * @param account 申请入群的用户ID
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> passApply(String teamId, String account);

    /**
     * 拒绝用户的入群申请 <br>
     * 仅管理员和拥有者有此权限
     *
     * @param teamId  群ID
     * @param account 申请入群的用户ID
     * @param reason  拒绝理由，长度不得超过5000
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> rejectApply(String teamId, String account, String reason);

    /**
     * 接受别人的入群邀请
     *
     * @param teamId  群ID
     * @param inviter 邀请我的用户帐号
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> acceptInvite(String teamId, String inviter);

    /**
     * 拒绝别人的入群邀请通知
     *
     * @param teamId  群ID
     * @param inviter 邀请我的用户帐号
     * @param reason  拒绝理由，长度不得超过5000
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> declineInvite(String teamId, String inviter, String reason);

    /**
     * 标记会话ACK
     *
     * @param teamId    群ID
     * @param timestamp 会话最后一条ACK消息的时间戳，单位毫秒
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> sendAckSession(String teamId, long timestamp);

    /**
     * 拥有者添加管理员 <br>
     * 仅拥有者有此权限
     *
     * @param teamId   群ID
     * @param accounts 待提升为管理员的用户帐号列表
     * @return InvocationFuture 可以设置回调函数,如果成功，参数为新增的群管理员列表
     */
    InvocationFuture<List<SuperTeamMember>> addManagers(String teamId, List<String> accounts);

    /**
     * 拥有者撤销管理员权限 <br>
     * 仅拥有者有此权限
     *
     * @param teamId   群ID
     * @param managers 待撤销的管理员的帐号列表
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为被撤销的群成员列表(权限已被降为Normal)。
     */
    InvocationFuture<List<SuperTeamMember>> removeManagers(String teamId, List<String> managers);

    /**
     * 对整个群禁言、解除禁言，对普通成员生效，只有群组、管理员有权限
     *
     * @param teamId 群组 ID
     * @param mute   true表示禁言，false表示解除禁言
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> muteAllTeamMember(String teamId, boolean mute);

    /**
     * 禁言、解除禁言
     *
     * @param teamId      群组ID
     * @param accountList 被禁言、被解除禁言的账号列表
     * @param mute        true表示禁言，false表示解除禁言
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> muteTeamMembers(String teamId, ArrayList<String> accountList, boolean mute);

    /**
     * 群组管理员修改群内其他成员的群昵称。<br>
     * 仅群管理员和拥有者有此权限
     *
     * @param teamId  所在群组ID
     * @param account 要修改的群成员帐号
     * @param nick    新的群昵称
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> updateMemberNick(String teamId, String account, String nick);

    /**
     * 拥有者将群的拥有者权限转给另外一个人，转移后，另外一个人成为拥有者。<br>
     * 原拥有者变成普通成员。若参数quit为true，原拥有者直接退出该群。
     *
     * @param tid     群ID
     * @param account 新任拥有者的用户帐号
     * @param quit    转移时是否要同时退出该群
     * @return InvocationFuture 可以设置回调函数，如果成功，视参数quit值：<br>
     * quit为false：参数仅包含原拥有者和当前拥有者的(即操作者和account)，权限已被更新。<br>
     * quit为true: 参数为空。
     */
    InvocationFuture<List<SuperTeamMember>> transferTeam(String tid, String account, boolean quit);


    /**
     * 通过群名称反查群组ID
     *
     * @param name 群组名称
     * @return 群ID列表
     */
    InvocationFuture<List<String>> searchTeamIdByName(String name);

    /**
     * 搜索群成员
     * @param option 搜索参数
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<NIMSuperTeamMemberSearchResult> searchTeamMembers(NIMTeamMemberKeywordSearchOption option);

    /**
     * 查询群成员列表
     * @param teamId 群组ID
     * @param option 查询选项
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<NIMSuperTeamMemberSearchResult> getTeamMemberList(String teamId, NIMTeamMemberRoleTypeSearchOption option);

    /**
     * 添加特别关注群成员列表
     * @param teamId 群组ID
     * @param accountIds 账号列表
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> addTeamMembersFollow(String teamId,List<String> accountIds);

    /**
     * 移除特别关注群成员列表
     * @param teamId 群组ID
     * @param accountIds 账号列表
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> removeTeamMembersFollow(String teamId,List<String> accountIds);
}