TeamService.java

浏览该文件的文档.

package com.netease.nimlib.sdk.team;

import com.netease.nimlib.apt.annotation.NIMService;
import com.netease.nimlib.sdk.InvocationFuture;
import com.netease.nimlib.sdk.Observer;
import com.netease.nimlib.sdk.antispam.model.AntiSpamConfig;
import com.netease.nimlib.sdk.msg.model.IMMessage;
import com.netease.nimlib.sdk.msg.model.TeamMsgAckInfo;
import com.netease.nimlib.sdk.team.constant.TeamFieldEnum;
import com.netease.nimlib.sdk.team.constant.TeamMessageNotifyTypeEnum;
import com.netease.nimlib.sdk.team.constant.TeamTypeEnum;
import com.netease.nimlib.sdk.team.model.CreateTeamResult;
import com.netease.nimlib.sdk.team.model.NIMTeamMemberRoleTypeSearchOption;
import com.netease.nimlib.sdk.team.model.NIMTeamMemberSearchResult;
import com.netease.nimlib.sdk.team.model.Team;
import com.netease.nimlib.sdk.team.model.TeamInfoResult;
import com.netease.nimlib.sdk.team.model.TeamMember;
import java.io.Serializable;
import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * 群组操作相关接口<br>
 * 群更新的通知监测见 {@link TeamServiceObserver}
 */
@NIMService("群服务")
public interface TeamService {

    /**
     * 创建一个群组
     *
     * @param fields     群组预设资料, key为数据字段，value对对应的值，该值类型必须和field中定义的fieldType一致。
     * @param type       要创建的群组类型
     * @param postscript 邀请入群的附言。如果是创建临时群，该参数无效
     * @param members    邀请加入的成员帐号列表
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为创建的群组资料
     */
    InvocationFuture<CreateTeamResult> createTeam(Map<TeamFieldEnum, Serializable> fields, TeamTypeEnum type,
                                                  String postscript, List<String> members);

    /**
     * 创建一个群组
     *
     * @param fields         群组预设资料, key为数据字段，value对对应的值，该值类型必须和field中定义的fieldType一致。
     * @param type           要创建的群组类型
     * @param postscript     邀请入群的附言。如果是创建临时群，该参数无效
     * @param members        邀请加入的成员帐号列表
     * @param antiSpamConfig 反垃圾相关配置参数
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为创建的群组资料
     */
    InvocationFuture<CreateTeamResult> createTeam(Map<TeamFieldEnum, Serializable> fields, TeamTypeEnum type,
        String postscript, List<String> members, AntiSpamConfig antiSpamConfig);

    /**
     * 添加成员
     *
     * @param teamId   群组ID
     * @param accounts 待加入的群成员帐号列表
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<List<String>> addMembers(String teamId, List<String> accounts);


    /**
     * 添加成员
     *
     * @param teamId     群组ID
     * @param accounts   待加入的群成员帐号列表
     * @param msg        邀请附言 ，不需要的话设置为空
     * @param customInfo 自定义扩展字段，不需要的话设置为空 ，最长512字符
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<List<String>> addMembersEx(String teamId, List<String> accounts, String msg, String customInfo);

    /**
     * 移除成员，只有创建者有此权限
     *
     * @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
     * @param name   群的新名称
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     * @deprecated use {@link #updateTeam(String, TeamFieldEnum, Serializable)} instead
     */
    InvocationFuture<Void> updateName(String teamId, String name);

    /**
     * 更新群组资料
     *
     * @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);

    /**
     * 解散群，只有创建者有此权限
     *
     * @param teamId 群ID
     * @return InvocationFuture 可以设置回调函数，监听操作结果
     */
    InvocationFuture<Void> dismissTeam(String teamId);

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

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

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

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

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

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

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

    /**
     * 获取自己加入的指定类型群（讨论组/高级群）列表
     *
     * @param type 群类型
     * @return 可以设置回调函数，如果成功，参数为加入的指定类型群列表
     */
    InvocationFuture<List<Team>> queryTeamListByType(TeamTypeEnum type);

    /**
     * 获取自己加入的指定类型群（讨论组/高级群）列表（同步版本）
     *
     * @param type 群类型
     * @return 加入的指定类型群列表
     */
    public List<Team> queryTeamListByTypeBlock(TeamTypeEnum type);

    /**
     * 获取自己加入的群的数量
     *
     * @return 数量
     */
    public int queryTeamCountBlock();

    /**
     * 获取自己加入的指定类型群的数量
     *
     * @param type 群类型
     * @return 数量
     */
    public int queryTeamCountByTypeBlock(TeamTypeEnum type);

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

    /**
     * 从服务器上查询群资料信息
     *
     * @param teamIdList 群ID列表，如果大小超过10，取前10个
     * @return
     */
    InvocationFuture<TeamInfoResult> searchTeam(List<Long> teamIdList);

    /**
     * 用户申请加入群。
     *
     * @param tid        申请加入的群ID
     * @param postscript 申请附言
     * @return InvocationFuture 可以设置回调函数，如果成功，参数为群资料
     */
    InvocationFuture<Team> 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  拒绝理由，选填
     * @return InvocationFuture 可以设置回调函数
     */
    InvocationFuture<Void> rejectApply(String teamId, String account, String reason);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    /**
     * (群消息接收方)标记群组消息已读
     *
     * @param message 群组消息
     * @return InvocationFuture 可设置回调函数，监听发送结果。
     */
    InvocationFuture<Void> sendTeamMessageReceipt(IMMessage message);

    /**
     * (群消息发送方)批量刷新群组消息已读、未读的数量信息，没有异步回调
     * 如果已读、未读数有变更，会通过 {@link com.netease.nimlib.sdk.msg.MsgServiceObserve#observeTeamMessageReceipt(Observer, boolean)}来批量通知，没有变更则不会通知
     *
     * @param messages 请求刷新的群组消息集合
     */
    void refreshTeamMessageReceipt(List<IMMessage> messages);

    /**
     * (群消息发送方)查询单条群组消息已读、未读账号列表
     *
     * @param message 待查询的消息
     * @return 该消息的已读、未读账号列表
     */
    InvocationFuture<TeamMsgAckInfo> fetchTeamMessageReceiptDetail(IMMessage message);

    /**
     * (群消息发送方)查询单条群组消息在指定用户中的已读、未读账号列表
     *
     * @param message 待查询的消息
     * @param accountSet 指定的用户的账号组成的{@link Set<String>}。
     *                   如果传空，则返回的列表也是空
     * @return 该消息的已读、未读账号列表
     */
    InvocationFuture<TeamMsgAckInfo> fetchTeamMessageReceiptDetail(IMMessage message, Set<String> accountSet);

    /**
     * 从本地数据库查询单条群组消息已读、未读账号列表（同步接口）
     * 注意！！！：这里获取的数据通常比离线前的列表信息更陈旧
     *
     * @param message 待查询的消息
     * @return 该消息的已读、未读账号列表
     */
    TeamMsgAckInfo queryTeamMessageReceiptDetailBlock(IMMessage message);

    /**
     * 从本地数据库查询单条群组消息在指定用户中的已读、未读账号列表（同步接口）
     * 注意！！！：这里获取的数据通常比离线前的列表信息更陈旧
     *
     * @param message 待查询的消息
     * @param accountSet 指定的用户的账号组成的{@link Set<String>}。
     *                   如果传空，则返回的列表也是空
     * @return 该消息的已读、未读账号列表
     */
    TeamMsgAckInfo queryTeamMessageReceiptDetailBlock(IMMessage message, Set<String> accountSet);

    /**
     * 获取群成员入群邀请人（为空表示主动入群，没有邀请人）
     *
     * @param tid
     * @param accids 查询用户accid列表，最多两百
     * @return 返回用户的对应关系，key为accid value是inviteAccid
     */
    InvocationFuture<Map<String, String>> getMemberInvitor(String tid, List<String> accids);

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

    /**
     * 群组会话云端历史消息关键词查询
     *
     * @param tid 群组id
     * @param fromTime 起始时间点单位毫秒
     * @param endTime 结束时间点单位毫秒
     * @param keyword 查询关键词
     * @param limit 本次查询的消息条数上限(最多100条)
     * @param reverse (可选参数，不传默认false)，true是表示反向查询(按时间正序起查，正序排列)，默认false表示按时间逆序起查，逆序排列
     * @return
     */
    InvocationFuture<List<IMMessage>> searchTeamMsgByKeyword(long tid, long fromTime, long endTime, String keyword, int limit, boolean reverse);

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

    /**
     * 查询群成员列表
     * @param teamId 群组ID
     * @param option 查询选项
     * @return
     */
    InvocationFuture<NIMTeamMemberSearchResult> 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);
}