一、框架设计

二、Handoff API入口

public class Handoff {

    /**
     * 创建一个接力会话的构建器实例。如果当前设备不支持接力功能，则会创建一个模拟（Mock）的接力会话，
     * 调用该构建器产生的会话不会有任何实际效果。
     *
     * @param activity 需要接力的页面Activity实例。确保传入的Activity已经启动并且处于活跃状态。
     * @return HandoffSession.Builder 返回一个用于构建接力会话的Builder对象。
     */
    static HandoffSession.Builder from(@NonNull Activity activity) {
        // 实现代码...
        return new MockHandoffSession.Builder();
    }

    /**
     * 检测当前设备是否支持接力服务。
     *
     * @param context 应用程序上下文，用于访问系统服务。
     * @return boolean 如果当前设备支持接力服务则返回true，否则返回false。
     */
    static boolean isSupport(Context context) {
        // 实现代码...
        return false;
    }
}

三、HandoffSession 接力会话

public class HandoffSession {

    /**
     * 发布一个接力会话。
     *
     * @param cb 接力回调接口。
     */
    void publish(HandoffCallback cb) {
        // 实现代码...
    }

    /**
     * 在 Activity 的 onNewIntent 回调中调用此方法。
     *
     * @param intent 从 onNewIntent 回调中获得的 Intent 对象。
     */
    void onNewIntent(Intent intent) {
        // 实现代码...
    }

    /**
     * 主动撤销接力需求。当 Activity 被销毁或进程被杀死时，Handoff内部会自动撤销当前接力会话。
     */
    void cancel() {
        // 实现代码...
    }

    /**
     * 构建接力会话所需配置的类。
     */
    static class Builder {

        /**
         * 设置用于接力的 Deep Link。
         *
         * @param deepLink 提供 Uri 的 Supplier，该 Uri 应包含 scheme、host、path 和 query 组件。
         * @return Builder 返回当前构建器对象，以支持链式调用。
         */
        Builder setDeepLink(Supplier<Uri> deepLink) {
            // 实现代码...
            return this;
        }

        /**
         * 设置用于接力的 Deep Link，并提供一个回调接口以处理无法通过 Uri 的 query 参数传递的数据。
         *
         * @param deepLink 提供 Uri 的 Supplier。
         * @param callback 当数据无法通过 Uri 传递时使用的回调接口。
         * @return Builder 返回当前构建器对象，以支持链式调用。
         */
        Builder setDeepLink(Supplier<Uri> deepLink, DeepLinkCallback callback) {
            // 实现代码...
            return this;
        }

        /**
         * 设置用于接力的 App Link。
         * uri的scheme必须是https，且是一个可访问的web链接。
         * 如果在接力设备中，没有安装你的应用，会打开浏览器，跳转到链接对应的web页面。
         * 如果安装了你的应用，你的应用里面配置了匹配的intent-filter，那么打开匹配的Activity。
         * 若接力页面的数据可以通过url中的query进行传递，且有与原生页面匹配的网页，那么推荐使用这种。
         *
         * @param appLink 提供 Uri 的 Supplier，该 Uri 必须是一个有效的 HTTPS 链接。
         * @return Builder 返回当前构建器对象，以支持链式调用。
         */
        Builder setAppLink(Supplier<Uri> appLink) {
            // 实现代码...
            return this;
        }

        /**
         * 构建并返回接力需求对象。
         *
         * @return HandoffRequirement 包含所有设置的接力需求配置的对象。
         */
        HandoffRequirement build() {
            // 实现代码...
            return new HandoffRequirement();
        }
    }
}

四、接力回调

1、DeepLinkCallback 数据回调

/**
 * 用于处理接力过程中状态数据保存和恢复的回调接口。
 */
public interface DeepLinkCallback {

    /**
     * 在接力开始之前调用，用于保存当前页面的状态数据。
     *
     * @return 序列化后的状态数据，推荐使用跨平台的序列化方案如 ProtoBuff、TLV、LV 或 JSON 等。
     */
    byte[] onSaveState();

    /**
     * 在接力完成之后调用，用于恢复接力过程中保存的状态数据。
     *
     * @param stateData 从 onSaveState 方法返回的序列化状态数据。
     */
    void onRestoreState(byte[] stateData);
}

2、HandoffCallback 结果回调

/**
 * 设备接力操作的回调接口。
 */
public interface HandoffCallback {

    /**
     * 当接力成功完成时调用此方法。
     * 
     * 可以在此方法中执行一些清理操作或者通知用户接力已经顺利完成。
     */
    void onHandoffDone();

    /**
     * 当尝试访问接力服务或者在接力过程中发生错误时调用此方法。
     * 
     * @param code 错误码，用于快速定位问题类别。
     * @param msg 错误信息，提供具体的错误描述帮助调试。
     */
    void onError(int code, String msg);
}