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

跨端迁移开发

场景介绍

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

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

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

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

HarmonyOS学习路之开发篇—流转(跨端迁移 一)_第1张图片

  • 设备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. 应用自行退出。

接口说明

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

表1 IContinuationRegisterManager接口功能介绍

接口名

描述

void register(String bundleName, ExtraParams parameter, IContinuationDeviceCallback deviceCallback, RequestCallback requestCallback)

注册并连接到流转任务管理服务,并获取对应的注册token。

参数说明:

  • 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()

在应用退出时,主动调用断开和流转任务管理服务的连接。

表2 IContinuationDeviceCallback接口功能介绍

接口名

描述

void onConnected(ContinuationDeviceInfo deviceInfo)

当用户从选择设备列表选择设备时调用,返回设备ID、设备类型和设备名称供开发者使用。

void onDisconnected(String deviceId)

当流转任务管理服务断开连接设备时调用。

表3 RequestCallback接口功能介绍

接口名

描述

void onResult(int result)

与流转任务管理服务交互成功时调用。当作为注册流转任务管理服务的回调对象时,注册成功后给用户程序返回对应的token。

表4 Ability/AbilitySlice接口功能介绍

接口名

描述

IContinuationRegisterManager getContinuationRegisterManager()

获取流转任务管理服务注册服务管理类,可以与流转任务管理服务进行交互,包括注册/解注册,更新设备连接状态,显示可选择设备列表等。

void continueAbility(String deviceId)

把当前FA流转到同一个分布式网络中另外一个设备上,仅支持单向流转。

表5 IAbilityContinuation接口功能介绍

接口名

描述

boolean onStartContinuation()

FA请求迁移后,系统首先回调此方法,开发者可以在此回调中决策当前是否可以执行迁移,比如,弹框让用户确认是否开始迁移。

boolean onSaveData(IntentParams saveData)

如果onStartContinuation()返回true,则系统回调此方法,开发者在此回调中保存必须传递到目标端设备上,用于恢复FA状态的数据。

boolean onRestoreData(IntentParams restoreData)

发起端设备上FA完成保存数据后,系统在目标端设备上回调此方法,开发者在此回调中接受用于恢复FA状态的数据。

说明

在目标端设备上的FA会重新启动其生命周期,无论其启动模式如何配置,且系统回调此方法的时机在onStart()之前。

void onCompleteContinuation(int result)

目标端设备上恢复数据一旦完成,系统就会在发起端设备上回调FA的此方法,以便通知应用迁移流程已结束。

开发者可以在此检查迁移结果是否成功,并在此处理迁移结束的动作,例如,应用可以在迁移完成后终止自身生命周期。

void onFailedContinuation(int errorCode)

迁移过程中发生异常,系统会在发起端回调FA的此方法,以便通知应用迁移流程发生的异常。

并不是所有异常都会回调此方法,仅局限于该接口枚举的异常。

开发者可以在此检查异常信息,并在此处理迁移异常发生后的动作。例如:应用可以提醒用户此时发生的异常信息并给出处理建议。

约束与限制

  • 每个应用注册流转任务管理服务的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"}过滤条件。

你可能感兴趣的:(HarmonyOS,学习(java开发篇),harmonyos,学习,华为,跨端迁移,java)