AuthService.java

浏览该文件的文档.

package com.netease.nimlib.sdk.auth;

import com.netease.nimlib.apt.annotation.NIMService;
import com.netease.nimlib.sdk.AbortableFuture;
import com.netease.nimlib.sdk.InvocationFuture;
import com.netease.nimlib.sdk.Observer;

/**
 * 用户认证服务接口，提供用户登录登出等业务接口。
 */
@NIMService("用户认证服务")
public interface AuthService {

    /**
     * 登录 IM。调用该接口后，SDK 会自动连接服务器，传递用户信息，返回登录结果。<br>
     * 登录过程中可调用 {@link AbortableFuture#abort()} 接口主动取消登录。如果因为网络或其他原因导致云信服务端长时间未响应，用户也没有主动取消登录，NIM SDK 将在 45 秒后自动重新连接云信服务端，跟踪接口 {@link AbortableFuture} 的 onFailed 会被调用，返回错误码。
     * @par 使用场景：
     * <ul><li>在新设备上首次登录 IM</li><li>同时在线的其他设备踢下线后再次登录 IM</li><li>切换 IM 账号后再次登录 IM</li><li>注销登录后再次登录 IM</li></ul>
     * @par 使用建议：
     * 调用该接口成功后，建议将 accid 和 token 保存到本地，方便下次应用启动进行初始化时，在 SDKOptions#LoginInfo 中传入，实现自动登录。
     * @par 参数说明：
     * info 登录的用户信息
     * @par 返回：
     * 若通过 InvocationFuture 设置了回调函数，则返回监听结果（{@link com.netease.nimlib.sdk.RequestCallback}）
     * @par 相关错误码：
     * 302：App Key、accid和token三者不对应<br>
     * 408：连接超时<br>
     * 415：网络断开或者连接云信服务端失败<br>
     * 416：调用频次过高<br>
     * 1000：本地数据库未打开。请在手动登录成功后打开本地数据库
     *
     */
    public AbortableFuture<LoginInfo> login(LoginInfo info);

    /**
     * 注销 IM 登录。该方法没有回调。
     * @par 使用场景：
     * 一般情况下，如果您的应用生命周期跟 NIM SDK 生命周期一致，用户在退出应用前可以不注销，直接退出即可。<br>
     * 但是，如果用户仅在进入特定界面后才使用 NIM SDK 的能力，退出界面后不再使用，此时需要调用 NIM SDK 的登出接口注销 IM 登录。 登出后，用户将不再接收 IM 的消息。
     * @par 使用限制：
     * <ul><li>请不要在 Activity(Fragment) 的 onDestroy 调用 logout 方法。</li><li>建议不要频繁调用登录、登出方法，调用 logout 方法后，如需再调用 login 方法，其间隔至少要大于 3s。</li></ul>
     */
    public void logout();

    /**
     * 注销接口，完成后回调通知
     *
     * @par 参数说明：
     * timeout 登出允许最大等待时间，单位毫秒。如 3 * 1000L
     * @par 返回：
     * InvocationFuture 可设置回调函数，监听操作结果。
     */
    public InvocationFuture<Void> logout(long timeout);

    /**
     * 主动将同时在线的其他客户端踢下线。<br>
     * 被踢端若注册了 {@link AuthServiceObserver#observeOnlineStatus(Observer, boolean)} 观察者，在被踢下线后，会收到登录状态回调（KICK_BY_OTHER_CLIENT）。如需要重新登录，建议先注销登录（logout），再切换到登录界面进行登录。
     *
     * @par 参数说明：
     * client 被踢下线的客户端信息
     * @par 返回：
     * 若通过 InvocationFuture 设置了回调函数，则返回监听结果（{@link com.netease.nimlib.sdk.RequestCallback}）
     */
    public InvocationFuture<Void> kickOtherClient(OnlineClient client);

    /**
     * 获取踢掉“我”的客户端类型。
     * @par 使用场景：
     * 如果自己被其他同时在线的客户端踢掉, 通过该接口可以获取踢掉“我”的客户端类型。
     * @par 注意事项：
     * 如果“我”的当前登录状态（{@link com.netease.nimlib.sdk.StatusCode}）不是被其他端踢出（KICK_BY_OTHER_CLIENT），则该接口返回值无效。返回值无效的场景可能是：被服务端禁用并踢出 、自动登录监听返回 417 错误码等。
     * @par 返回：
     * 踢掉“我”的客户端类型
     */
    public int getKickedClientType();

    /**
     * 获取踢掉“我”的客户端自定义类型。
     * @par 使用场景：
     * 如果自己被其他同时在线的**自定义客户端**踢掉, 通过该接口可以获取踢掉“我”的客户端自定义类型。
     * @par 注意事项：
     * <ul><li>用户只有在 {@link AuthService#login(LoginInfo)} 时自定义了 ClientType，才能通过该接口查询到</li><li>如果“我”的当前登录状态（{@link com.netease.nimlib.sdk.StatusCode}）不是被其他端踢出（KICK_BY_OTHER_CLIENT），则该接口返回值无效。返回值无效的场景可能是：被服务端禁用并踢出 、自动登录监听返回 417 错误码等。</li></ul>
     * @par 返回：
     * 踢掉“我”的客户端自定义类型
     */
    public int getKickedCustomClientType();

    /**
     * 离线时打开本地数据。
     * @par 使用场景：
     * 在手动登录没有成功前（可能由于网络问题，登录时间较长），需要访问 SDK 本地数据（本地用户信息，本地历史消息等数据）。可以通过本接口实现上述场景。
     * @par 注意事项：
     * 采用自动登录方式登录 IM，实际也使用了该功能，也能达到同样的效果。即如果已使用自动登录方式登录 IM，不用单独调用 openLocalCache 接口，在离线时也能访问本地数据。
     * @par 返回：
     * 是否成功打开 SDK 本地数据
     */
    public boolean openLocalCache(String account);


    /**
     * 获取登录时传给服务端的设备 ID。用于标识当前的终端设备。
     * @par 注意事项：
     * 此处返回的设备 ID 并不是真正意义上的设备 ID ，而是生成的随机 uuid 。如果应用卸载重装，可能会重新生成设备 ID。
     * @par 返回：
     * deviceID：生成的随机 uuid
     *
     */
    public String getDeviceID();

    /**
     * 杀死当前 UI 页面。
     */
    public void killUI();

    /**
     * 杀死其他进程。
     */
    public void killCore();

    /**
     * 终止当前用户的认证服务，即结束当前进程。
     */
    public void exit();
}