HarmonyOS学习路之开发篇—流转（跨端迁移 一）

跨端迁移开发

场景介绍

开发者在应用FA中通过调用流转任务管理服务、分布式任务调度的接口，实现跨端迁移。

1. 设备A上的应用FA向流转任务管理服务注册一个流转回调：

• Alt1-系统推荐流转：系统感知周边有可用设备后，主动为用户提供可选择流转的设备信息，并在用户完成设备选择后回调onConnected通知应用FA开始流转，将用户选择的设备B的设备信息提供给应用FA。
• Alt2-用户手动流转：系统在用户手动点击流转图标后，通过showDeviceList通知流转任务管理服务，被动为用户提供可选择交互的设备信息，并在用户完成设备选择后回调onConnected通知应用FA开始流转，将用户选择的设备B的设备信息提供给应用FA。

2. 设备A上的应用FA通过调用分布式任务调度的能力，向设备B的应用发起跨端迁移。应用FA需要自己管理流转状态，将流转状态从IDLE迁移到CONNECTING，并上报到流转任务管理服务。

• 设备A上的FA请求迁移。
• 系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onStartContinuation()方法，以确认当前是否可以开始迁移，onStartContinuation方法返回true，表示当前FA可以开始迁移。
• 如果可以开始迁移，则系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onSaveData()方法，以便保存迁移后恢复状态必须的数据。
• 如果保存数据成功，则系统在设备B上启动同一个FA，并恢复AbilitySlice栈，然后回调IAbilityContinuation.onRestoreData()方法，传递设备A上FA保存的数据，应用可在此方法恢复业务状态；此后设备B上此FA从onStart()开始其生命周期回调。
• 系统回调设备A上FA，及其AbilitySlice栈中所有AbilitySlice实例的IAbilityContinuation.onCompleteContinuation()方法，通知应用迁移成功。
• 应用将流转状态从CONNECTING迁移到CONNECTED，并上报到流转任务管理服务。
• 流转任务管理服务将流转状态重新置为IDLE，流转完成。
• 应用向流转任务管理服务注销流转回调。

3. 应用自行退出。

接口说明

流转任务管理服务提供的注册、解注册、显示设备列表、上报业务状态是实现跨端迁移的前提。开发者通过跨端迁移能力，可实现如文档跨设备编辑、视频跨设备接续播放等场景。

• bundleName，必填，String类型，本应用包名。
• params，可选，ExtraParams类型，系统推荐流转时所需的过滤条件。如系统推荐流转无特殊要求，可与showDeviceList接口的过滤条件保持一致。若需关闭系统推荐流转，ExtraParams中jsonParams传入{"isTurnOffRecommend":true}即可。
• deviceCallback，可选，设备选择列表中选择设备后的回调，返回选择设备ID。
• requestCallback，可选，注册请求回调，返回应用注册后的token。

ExtraParams说明：

• devType，可选，待连接的设备类型。可取值（"00E"手机、"011"平板、"06D"手表、"09C"智慧屏），如"devType":["011"]。若为空，则支持则待连接的设备类型为手机、平板、手表和智慧屏。
• targetBundleName，可选，目标应用包名。若为空，则目标应用包名与方法入参bundleName本应用包名相同。
• description，可选，ability描述，用于在设备列表页面展示
• jsonParams，可选，拓展参数。用于设备过滤等。示例： {"filter":{"commonFilter": {"system":{"harmonyVersion":"2.0.0"},"groupType": "1","curComType": 0x00000004, "faFilter":{\"targetBundleName\":\"com.xxx.yyy\"}"}},"transferScene":1,"isTurnOffRecommend":false,"remoteAuthenticationDescription": "拉起HiVision扫描弹框描述","remoteAuthenticationPicture":""}

jsonParams说明：

• system：可选，String类型，待连接设备的HarmonyOS版本号，目标设备对应的harmonyVersion>=该值，如"system":{"harmonyVersion":"2.0.0"}。
• groupType：可选，String类型。为空时，不要求是否是同帐号。本设备和待连接设备的帐号是否要求一致，可取值（1要求同帐号、1|256不要求同帐号）,如"groupType":"1"。
• curComType：可选，int类型。为空时，不要求在同一局域网下。本设备和待连接设备是否需要在同一局域网下，可取值（0x00000004需要在同一局域网下，0x00030004不需要在同一局域网下），如"curComType":0x00000004。
• faFilter：可选，String类型。为空时，不做版本兼容性检查。要做版本兼容性检查时，需要传入目标应用包名。
• transferScene：可选，int类型，默认值为0。可取值为：0-单选协同场景，设备选择面板为单选面板，设备间互斥，流转成功设备面板自动消失，流转失败设备面板不消失，且系统会维护设备的流转状态，如流转成功设备面板消失后再打开设备面板，会显示之前设备流转成功的状态；1-单选迁移场景，设备选择面板为单选面板，设备间互斥，流转成功设备面板自动消失，流转失败设备面板不消失，且系统不会维护设备的流转状态，如流转成功设备面板消失后再打开设备面板，设备流转状态为未流转；2-多选协同场景，设备选择面板为多选面板，流转成功或失败设备面板不消失，设备间不互斥，系统会维护设备的流转状态。
• isTurnOffRecommend：可选，boolean类型，默认为false。true：关闭系统推荐流转；false：开启系统推荐流转。
• remoteAuthenticationDescription：可选，String类型，跨账号/无账号设备进行扫码认证时，拉起对端HiVision扫描弹框描述。register接口无需传该参数，showDeviceList可按需传参。
• remoteAuthenticationPicture：可选，String类型，跨账号/无账号设备进行扫码认证时，拉起对端HiVision扫描弹框显示的图片。需将图片对应的byte[]转String, Base64.encodeToString(mBuff,Base64.DEFAULT)。register接口无需传该参数，showDeviceList可按需传参。

注册后，通过RequestCallback的onResult回调知道执行是否成功，返回值为<0时为失败；其他情况，表示成功，并返回本次流转任务的唯一标识token。 当用户选择设备后，通过deviceCallback定义的onConnected回调获取设备的deviceID、类型、名称。 void unregister(int token, RequestCallback requestCallback) 从流转任务管理服务解注册，传入注册时获取的token进行解注册。 执行后，通过RequestCallback的onResult回调知道执行是否成功。 void updateConnectStatus(int token, String deviceId, int status, RequestCallback requestCallback) 通知流转任务管理服务更新当前用户程序的连接状态，并在流转任务管理服务界面展示给用户。token、deviceId参数来自于注册流转任务管理服务的回调。status参数可以为IDLE、CONNECTING、CONNECTED、DIS_CONNECTING。如果有错误，需要上报errorCode。 执行后，通过RequestCallback的onResult回调知道执行是否成功。 void showDeviceList(int token, ExtraParams parameter, RequestCallback requestCallback) 显示组网内可选择设备列表信息。该接口提供手动显示设备列表的能力，parameter参数可以指定设备过滤的条件，用于手动多端协同，支持的过滤条件与register接口相同。token参数来自于注册流转任务管理服务的回调。 执行后，通过RequestCallback的onResult回调知道执行是否成功。 void disconnect() 在应用退出时，主动调用断开和流转任务管理服务的连接。

约束与限制

• 每个应用注册流转任务管理服务的Ability数量上限为5个，后续新增注册的Ability会将最开始注册的覆盖。
• 一个应用可能包含多个FA，仅需要在支持跨端迁移的FA及其所包含的AbilitySlice中，调用或实现相关接口。
• 跨端迁移不支持两个设备之间分别登录不同的帐号，也就是要求多个设备是同帐号。
• 跨端迁移不支持对PA的迁移，只支持对FA的迁移。
• 跨端迁移完成时，系统不会主动关闭发起迁移的FA，开发者可以根据业务需要，主动调用terminateAbility或stopAbility关闭FA，并调用updateConnectStatus()更新设备的连接状态。
• 通过continueAbility进行跨端迁移过程中，远端FA首先接收到发起端FA传输的数据，再执行启动，即onRestoreData()发生在onStart()之前。
• 跨端迁移的数据大小限制200KB以内，即onSaveData只能传递200KB以内的数据。
• 迁移传输的数据，当前仅支持基础类型数据传递和系统Sequenceable对象，不支持自定义对象及文件数据传递。
• FA流转过程中，在流转未完成时再次调用continueAbility发起流转，接口将会抛出状态异常，应用需要加以限制处理。
• 跨端迁移要求HarmonyOS 2.0以上版本才能支持，注册到流转任务管理服务时jsonParams中需要增加{"harmonyVersion":"2.0.0"}过滤条件。