SignallingService.java

浏览该文件的文档.

package com.netease.nimlib.sdk.avsignalling;

import com.netease.nimlib.apt.annotation.NIMService;
import com.netease.nimlib.sdk.InvocationFuture;
import com.netease.nimlib.sdk.RequestCallback;
import com.netease.nimlib.sdk.RequestCallbackWrapper;
import com.netease.nimlib.sdk.ResponseCode;
import com.netease.nimlib.sdk.avsignalling.builder.CallParamBuilder;
import com.netease.nimlib.sdk.avsignalling.builder.InviteParamBuilder;
import com.netease.nimlib.sdk.avsignalling.constant.ChannelType;
import com.netease.nimlib.sdk.avsignalling.model.CallExParam;
import com.netease.nimlib.sdk.avsignalling.model.CallExResult;
import com.netease.nimlib.sdk.avsignalling.model.ChannelBaseInfo;
import com.netease.nimlib.sdk.avsignalling.model.ChannelFullInfo;
import com.netease.nimlib.sdk.avsignalling.model.JoinAndAcceptParam;
import com.netease.nimlib.sdk.avsignalling.model.JoinAndAcceptResult;
import com.netease.nimlib.sdk.avsignalling.model.MemberInfo;

import java.util.List;


@NIMService("信令服务")
public interface SignallingService {

    /**
     * 创建频道<br/>
     * 同一时刻频道名互斥，不能重复创建，但如果频道名缺省，服务器会自动分配频道id。<br/><br/>
     * 错误码如下：<br/>
     * 10405：频道已存在 {@link ResponseCode#RES_CHANNEL_HAS_EXISTS}
     *
     * @param type        频道类型
     * @param channelName 频道名，可缺省
     * @param channelExt  频道的自定义扩展信息，可缺省
     * @return InvocationFuture
     */
    InvocationFuture<ChannelBaseInfo> create(ChannelType type, String channelName, String channelExt);


    /**
     * 关闭频道<br/><br/>
     * 错误码如下：<br/>
     * 10406：不在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_NOT_EXISTS}
     *
     * @param channelId      对应频道id
     * @param offlineEnabled 通知事件是否存离线
     * @param customInfo     操作者附加的自定义信息，透传给其他人，可缺省
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> close(String channelId, boolean offlineEnabled, String customInfo);


    /**
     * 加入频道<br/><br/>
     * 错误码如下：<br/>
     * 10407：已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS}  <br/>
     * 10417：uid冲突 {@link ResponseCode#RES_JOIN_CHANNEL_UID_CONFLICT}<br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * 10420：自己的其他端已经在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS_OTHER_CLIENT}<br/>
     *
     * @param channelId     对应频道id
     * @param selfUid       自己在频道中对应的uid，可选，大于零有效，无效时服务器会分配随机唯一的uid， 也可以自己生成，但要保证唯一性
     * @param customInfo    操作者附加的自定义信息，透传给其他人，可缺省
     * @param offlineEnable 通知事件是否存离线
     * @return InvocationFuture<ChannelFullInfo>
     */
    InvocationFuture<ChannelFullInfo> join(String channelId, long selfUid, String customInfo, boolean offlineEnable);

    /**
     * 加入频道<br/><br/>
     * 错误码如下：<br/>
     * 10407：已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS}  <br/>
     * 10417：uid冲突 {@link ResponseCode#RES_JOIN_CHANNEL_UID_CONFLICT}<br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * 10420：自己的其他端已经在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS_OTHER_CLIENT}<br/>
     *
     * @param channelId     对应频道id
     * @param selfUid       自己在频道中对应的uid，可选，大于零有效，无效时服务器会分配随机唯一的uid， 也可以自己生成，但要保证唯一性
     * @param customInfo    操作者附加的自定义信息，透传给其他人，可缺省
     * @param offlineEnable 通知事件是否存离线
     * @param nertcChannelName      云信G2-RTC的房间名,如果填了该字段，则会返回token
     * @param nertcTokenTtl      云信G2-RTC的token的有效期，单位秒，选填
     * @return InvocationFuture<ChannelFullInfo>
     */
    InvocationFuture<ChannelFullInfo> join(String channelId, long selfUid, String customInfo, boolean offlineEnable,String nertcChannelName,
            Long nertcTokenTtl);

    /**
     * 加入频道<br/><br/>
     * 错误码如下：<br/>
     * 10407：已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS}  <br/>
     * 10417：uid冲突 {@link ResponseCode#RES_JOIN_CHANNEL_UID_CONFLICT}<br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * 10420：自己的其他端已经在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS_OTHER_CLIENT}<br/>
     *
     * @param channelId     对应频道id
     * @param selfUid       自己在频道中对应的uid，可选，大于零有效，无效时服务器会分配随机唯一的uid， 也可以自己生成，但要保证唯一性
     * @param customInfo    操作者附加的自定义信息，透传给其他人，可缺省
     * @param offlineEnable 通知事件是否存离线
     * @param nertcChannelName                  云信G2-RTC的房间名,如果填了该字段，则会返回token
     * @param nertcTokenTtl                     云信G2-RTC的token的有效期，单位秒，选填
     * @param nertcJoinRoomQueryParamMap        云信G2-RTC加入房间的响应，可以转成json，选填
     * @return InvocationFuture<ChannelFullInfo>
     */
    InvocationFuture<ChannelFullInfo> join(String channelId, long selfUid, String customInfo, boolean offlineEnable,
                                           String nertcChannelName, Long nertcTokenTtl, String nertcJoinRoomQueryParamMap);
    /**
     * 离开频道<br/><br/>
     * 错误码如下：<br/>
     * 10406：不在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_NOT_EXISTS}
     *
     * @param channelId     对应频道id
     * @param offlineEnable 通知事件是否存离线
     * @param customInfo    操作者附加的自定义信息，透传给其他人，可缺省
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> leave(String channelId, boolean offlineEnable, String customInfo);


    /**
     * 邀请他人加入频道<br/>
     * 该接口用于邀请对方加入频道，邀请者必须是创建者或者是频道中成员。如果需要对离线成员邀请，可以打开离线邀请开关并填写推送信息，被邀请者上线后通过离线通知接收到该邀请。
     * 错误码如下： <br/>
     * 10201：已经成功发出邀请但是对方不在线（推送可达，但是离线）{@link ResponseCode#RES_PEER_NIM_OFFLINE} <br/>
     * 10202：已经成功发出邀请但是对方推送不可达 {@link ResponseCode#RES_PEER_PUSH_OFFLINE}<br/>
     * 10404：频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}  <br/>
     * 10406：自己不在频道内（仅对于普通用户，频道创建者不在频道内也可以邀请别人）{@link ResponseCode#RES_CHANNEL_MEMBER_NOT_EXISTS}<br/>
     * 10407：对方已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS} <br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> invite(InviteParamBuilder paramBuilder);

    /**
     * 取消邀请<br/> <br/>
     * 错误码如下： <br/>
     * 10404：频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * 10408：邀请不存在或已过期 {@link ResponseCode#RES_INVITE_NOT_EXISTS}  <br/>
     * 10409：邀请已经拒绝  {@link ResponseCode#RES_INVITE_HAS_REJECT} <br/>
     * 10410：邀请已经接受 {@link ResponseCode#RES_INVITE_HAS_ACCEPT}
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> cancelInvite(InviteParamBuilder paramBuilder);

    /**
     * 拒绝对方邀请<br/><br/>
     * 错误码如下： <br/>
     * 10201：已经成功拒绝邀请但是对方不在线（推送可达，但是离线） {@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10404：频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * 10408：邀请不存在或已过期 {@link ResponseCode#RES_INVITE_NOT_EXISTS} <br/>
     * 10409：邀请已经拒绝 {@link ResponseCode#RES_INVITE_HAS_REJECT}  <br/>
     * 10410：邀请已经接受 {@link ResponseCode#RES_INVITE_HAS_ACCEPT}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> rejectInvite(InviteParamBuilder paramBuilder);


    /**
     * 接受对方邀请，但并不代表加入了频道，如果想在接受邀请时自动加入频道，参考{@link SignallingService#acceptInviteAndJoin(InviteParamBuilder, long)}<br/> <br/>
     * 错误码如下： <br/>
     * 10201：已经成功接受邀请但是对方不在线（推送可达，但是离线） {@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10404：频道不存在  {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}   <br/>
     * 10408：邀请不存在或已过期 {@link ResponseCode#RES_INVITE_NOT_EXISTS}  <br/>
     * 10409：邀请已经拒绝  {@link ResponseCode#RES_INVITE_HAS_REJECT}  <br/>
     * 10410：邀请已经接受  {@link ResponseCode#RES_INVITE_HAS_ACCEPT}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> acceptInvite(InviteParamBuilder paramBuilder);


    /**
     * 接受对方邀请并自动加入频道<br/> <br/>
     * 错误码如下： <br/>
     * 10420：自己的其他端已经在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS_OTHER_CLIENT} <br/>
     * 10201：已经成功接受邀请但是对方不在线（推送可达，但是离线）{@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10404：频道不存在 {@link ResponseCode#RES_CHANNEL_HAS_EXISTS} <br/>
     * 10407：已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS}  <br/>
     * 10408：邀请不存在或已过期 {@link ResponseCode#RES_INVITE_NOT_EXISTS}<br/>
     * 10409：邀请已经拒绝 {@link ResponseCode#RES_INVITE_HAS_REJECT} <br/>
     * 10410：邀请已经接受 {@link ResponseCode#RES_INVITE_HAS_ACCEPT} <br/>
     * 10417：uid冲突 {@link ResponseCode#RES_JOIN_CHANNEL_UID_CONFLICT}  <br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @param selfUid      自己在频道中对应的uid，大于零有效，无效时服务器会分配随机唯一的uid， 也可以自己生成，但要保证唯一性
     * @return InvocationFuture<ChannelFullInfo>
     * @deprecated 用 {@link #joinAndAccept(JoinAndAcceptParam)} 代替
     */
    @Deprecated
    InvocationFuture<ChannelFullInfo> acceptInviteAndJoin(InviteParamBuilder paramBuilder, long selfUid);


    /**
     * 接受对方邀请并自动加入频道<br/> <br/>
     * 错误码如下： <br/>
     * 10420：自己的其他端已经在频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS_OTHER_CLIENT} <br/>
     * 10201：已经成功接受邀请但是对方不在线（推送可达，但是离线）{@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10404：频道不存在 {@link ResponseCode#RES_CHANNEL_HAS_EXISTS} <br/>
     * 10407：已经频道内 {@link ResponseCode#RES_CHANNEL_MEMBER_HAS_EXISTS}  <br/>
     * 10408：邀请不存在或已过期 {@link ResponseCode#RES_INVITE_NOT_EXISTS}<br/>
     * 10409：邀请已经拒绝 {@link ResponseCode#RES_INVITE_HAS_REJECT} <br/>
     * 10410：邀请已经接受 {@link ResponseCode#RES_INVITE_HAS_ACCEPT} <br/>
     * 10417：uid冲突 {@link ResponseCode#RES_JOIN_CHANNEL_UID_CONFLICT}  <br/>
     * 10419：频道人数超限 {@link ResponseCode#RES_CHANNEL_MEMBER_EXCEED}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param paramBuilder InviteParamBuilder {@link InviteParamBuilder}
     * @param selfUid      自己在频道中对应的uid，大于零有效，无效时服务器会分配随机唯一的uid， 也可以自己生成，但要保证唯一性
     * @param nertcChannelName      云信G2-RTC的房间名,如果填了该字段，则会返回token
     * @param nertcTokenTtl      云信G2-RTC的token的有效期，单位秒，选填
     * @return InvocationFuture<ChannelFullInfo>
     * @deprecated 用 {@link #joinAndAccept(JoinAndAcceptParam)} 代替
     */
    @Deprecated
    InvocationFuture<ChannelFullInfo> acceptInviteAndJoin(InviteParamBuilder paramBuilder, long selfUid,String nertcChannelName,
            Long nertcTokenTtl);


    /**
     * 加入频道并接受对方邀请，该接口功能等同于用户先加入频道，然后接受对方邀请。该接口只需要一次网络请求，{@link #acceptInviteAndJoin(InviteParamBuilder, long)}
     * 和{@link #acceptInviteAndJoin(InviteParamBuilder, long, String, Long)}需要两次网络请求，推荐使用{@link #joinAndAccept(JoinAndAcceptParam)} <br/><br/>
     * 提示：以上接口返回200，代表加入频道成功，接受邀请的结果通过返回值{@link JoinAndAcceptResult}中的callStatus字段来体现。callStatus字段有一个特殊错误码：
     * 10201：已经成功接受邀请但是对方不在线（推送可达，但是离线） {@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     *
     * @param joinAndAcceptParam JoinAndAcceptParam {@link JoinAndAcceptParam}
     * @return InvocationFuture<JoinAndAcceptResult>
     */
    InvocationFuture<JoinAndAcceptResult> joinAndAccept(JoinAndAcceptParam joinAndAcceptParam);

    /**
     * 该接口用于在频道中透传一些自定义指令，协助频道管理。该接口允许非频道内成员调用，但接收者必须是频道内成员或创建者
     * <br/><br/>
     * 错误码如下：<br/>
     * 10201：已经成功发出命令但是对方不在线（推送可达，但是离线） {@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10404:频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * 10406:不在频道内（自己或者对方）{@link ResponseCode#RES_CHANNEL_MEMBER_NOT_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param channelId  频道id
     * @param accountId  对方accid，如果为空，则通知所有人
     * @param customInfo 操作者附加的自定义信息，透传给其他人，可缺省
     * @return InvocationFuture<Void>
     */
    InvocationFuture<Void> sendControl(String channelId, String accountId, String customInfo);


    /**
     * 直接呼叫 ， 用于用户新开一个频道并邀请对方加入频道。该接口为组合接口，等同于用户先创建频道，然后加入频道并邀请对方。<br/><br/>
     * 错误码如下：<br/>
     * 10201:已经成功发出邀请但是对方不在线（推送可达，但是离线）{@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10202:已经成功发出邀请但是对方推送不可达 {@link ResponseCode#RES_PEER_PUSH_OFFLINE}<br/>
     * 10405:频道已存在 {@link ResponseCode#RES_CHANNEL_HAS_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param callParamBuilder CallParamBuilder {@link CallParamBuilder}
     * @return InvocationFuture<ChannelFullInfo>
     * @deprecated 用 {@link #callEx(CallExParam)} 代替
     */
    @Deprecated
    InvocationFuture<ChannelFullInfo> call(CallParamBuilder callParamBuilder);

    /**
     * 直接呼叫，用于用户新开一个频道并邀请对方加入频道。该接口功能等同于用户先创建频道，然后加入频道并邀请对方。
     * 和{@link #call(CallParamBuilder)}的区别在于{@link #call(CallParamBuilder)}在客户端完成组合，客户端需要向服务器发起三次网络请求；
     * {@link #callEx(CallExParam)}在服务端完成组合，客户端只需要向服务器发起一次网络请求，推荐使用{@link #callEx(CallExParam)}<br/><br/>
     * 错误码如下：<br/>
     * 10405:频道已存在 {@link ResponseCode#RES_CHANNEL_HAS_EXISTS}<br/>
     * <p>
     * 提示：以上接口返回200，代表创建频道成功并且自己已经加入，邀请对方的结果通过返回值{@link CallExResult}中的callStatus字段来体现。callStatus字段有两个特殊错误码：<br/>
     * 10201:已经成功发出邀请但是对方不在线（推送可达，但是离线）{@link ResponseCode#RES_PEER_NIM_OFFLINE}<br/>
     * 10202:已经成功发出邀请但是对方推送不可达 {@link ResponseCode#RES_PEER_PUSH_OFFLINE}<br/>
     *
     * @param callExParam {@link CallExParam}，通过CallExParamBuilder创建
     * @return InvocationFuture<CallExResult>
     */
    InvocationFuture<CallExResult> callEx(CallExParam callExParam);

    /**
     * 根据channelName反查channelInfo
     *
     * 10404:频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param channelName
     * @return InvocationFuture<ChannelBaseInfo>
     */
    InvocationFuture<ChannelBaseInfo> queryChannelInfo(String channelName);

    /**
     * 根据channelName反查channelInfo， 聚合接口，可以替代queryChannelInfo， queryChannelMemberCount， queryChannelMemberList
     *
     * 10404:频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     *
     * @param channelName
     * @return InvocationFuture<ChannelFullInfo>
     */
    InvocationFuture<ChannelFullInfo> queryChannelFullInfo(String channelName);

    /**
     * 根据channelName查询房间内人数
     * 10404:频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     * @param channelName
     * @return InvocationFuture<Integer>
     */
    InvocationFuture<Integer> queryChannelMemberCount(String channelName);

    /**
     * 根据channelName查询房间内用户列表
     * 10404:频道不存在 {@link ResponseCode#RES_CHANNEL_NOT_EXISTS}<br/>
     * <p>
     * 提示：这里的回调建议设置成 {@link RequestCallbackWrapper}，并通过返回的code 去处理相关的逻辑 ，code = 200 为成功<br/>
     * 如果用{@link RequestCallback}，那么错误码将在{@link RequestCallback#onFailed(int code)}返回。
     * @param channelName
     * @return InvocationFuture<List<MemberInfo>>
     */
    InvocationFuture<List<MemberInfo>> queryChannelMemberList(String channelName);

}