diff --git a/en/application-dev/ability/Readme-EN.md b/en/application-dev/ability/Readme-EN.md index bd494f0618f105521e83cf3b81deb8de44f9fe69..0589643e0f9426f76ac25d3616a41c3b54910e2a 100644 --- a/en/application-dev/ability/Readme-EN.md +++ b/en/application-dev/ability/Readme-EN.md @@ -17,5 +17,7 @@ - Other - [WantAgent Development](wantagent.md) - [Ability Assistant Usage](ability-assistant-guidelines.md) + - [ContinuationManager Development](continuationmanager.md) - [Test Framework Usage](ability-delegator.md) + diff --git a/en/application-dev/ability/continuationmanager.md b/en/application-dev/ability/continuationmanager.md new file mode 100644 index 0000000000000000000000000000000000000000..a1f5a66478cd53aeabe03ed9be21e08596cb2b6b --- /dev/null +++ b/en/application-dev/ability/continuationmanager.md @@ -0,0 +1,253 @@ +# ContinuationManager Development + +> **NOTE** +> +> Currently, the **ContinuationManager** module is not available for application development. Its APIs are mainly used to start the device selection module. + +## When to Use +Users are using two or more devices to experience an all-scenario, multi-device lifestyle. Each type of device has its unique advantages and disadvantages specific to scenarios. The ability continuation capability breaks boundaries of devices and enables multi-device collaboration, achieving precise control, universal coordination, and seamless hops of user applications. + +As the entry of the ability continuation capability, **continuationManager** is used to start the device selection module for the user to select the target device. After a device is selected, information about the selected device is returned to the user. The user can then initiate cross-device continuation or collaboration based on the device information. + +![continuationManager](figures/continuationManager.png) + +## Available APIs +| API | Description| +| ---------------------------------------------------------------------------------------------- | ----------- | +| register(callback: AsyncCallback\): void | Registers the continuation management service and obtains a token. This API does not involve any filter parameters and uses an asynchronous callback to return the result.| +| register(options: ContinuationExtraParams, callback: AsyncCallback\): void | Registers the continuation management service and obtains a token. This API uses an asynchronous callback to return the result.| +| register(options?: ContinuationExtraParams): Promise\ | Registers the continuation management service and obtains a token. This API uses a promise to return the result.| +| on(type: "deviceConnect", token: number, callback: Callback\>): void | Subscribes to device connection events. This API uses an asynchronous callback to return the result.| +| on(type: "deviceDisconnect", token: number, callback: Callback\>): void | Subscribes to device disconnection events. This API uses an asynchronous callback to return the result.| +| off(type: "deviceConnect", token: number): void | Unsubscribes from device connection events.| +| off(type: "deviceDisconnect", token: number): void | Unsubscribes from device disconnection events.| +| startDeviceManager(token: number, callback: AsyncCallback\): void | Starts the device selection module to show the list of available devices. This API does not involve any filter parameters and uses an asynchronous callback to return the result.| +| startDeviceManager(token: number, options: ContinuationExtraParams, callback: AsyncCallback\): void | Starts the device selection module to show the list of available devices. This API uses an asynchronous callback to return the result.| +| startDeviceManager(token: number, options?: ContinuationExtraParams): Promise\ | Starts the device selection module to show the list of available devices. This API uses a promise to return the result.| +| updateConnectStatus(token: number, deviceId: string, status: DeviceConnectState, callback: AsyncCallback\): void | Instructs the device selection module to update the device connection state. This API uses an asynchronous callback to return the result.| +| updateConnectStatus(token: number, deviceId: string, status: DeviceConnectState): Promise\ | Instructs the device selection module to update the device connection state. This API uses a promise to return the result.| +| unregister(token: number, callback: AsyncCallback\): void | Deregisters the continuation management service. This API uses an asynchronous callback to return the result.| +| unregister(token: number): Promise\ | Deregisters the continuation management service. This API uses a promise to return the result.| + +## How to Develop +1. Import the **continuationManager** module. + + ```ts + import continuationManager from '@ohos.continuation.continuationManager'; + ``` + +2. Apply for permissions required for cross-device continuation or collaboration operations. + + The permission application operation varies according to the ability model in use. In the FA mode, add the required permission in the `config.json` file, as follows: + + ```json + { + "module": { + "reqPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + + This permission must also be granted by the user through a dialog box when the application is started for the first time. The sample code is as follows: + + ```ts + import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; + import bundle from '@ohos.bundle'; + + async function requestPermission() { + let permissions: Array = [ + "ohos.permission.DISTRIBUTED_DATASYNC" + ]; + let needGrantPermission: boolean = false; + let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); + let applicationInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', 0, 100); + for (let i = 0; i < permissions.length; i++) { + let result = await atManager.verifyAccessToken(applicationInfo.accessTokenId, permissions[i]); + // Check whether the permission is granted. + if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { + needGrantPermission = true; + break; + } + } + // If the permission is not granted, call requestPermissionsFromUser to apply for the permission. + if (needGrantPermission) { + await featureAbility.getContext().requestPermissionsFromUser(permissions, 1); + } else { + console.info('app permission already granted'); + } + } + ``` + + In the stage model, add the required permission in the `module.json5` file. The sample code is as follows: + + ```json + { + "module": { + "requestPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + + ```ts + import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; + import bundle from '@ohos.bundle'; + + async function requestPermission() { + let permissions: Array = [ + "ohos.permission.DISTRIBUTED_DATASYNC" + ]; + let needGrantPermission: boolean = false; + let atManger: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); + let applicationInfo = await bundle.getApplicationInfo('ohos.samples.continuationmanager', 0, 100); + for (const permission of permissions) { + try { + let grantStatus = await atManger.verifyAccessToken(applicationInfo.accessTokenId, permission); + // Check whether the permission is granted. + if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_DENIED) { + needGrantPermission = true; + break; + } + } catch (err) { + console.error('app permission query grant status error' + JSON.stringify(err)); + needGrantPermission = true; + break; + } + } + // If the permission is not granted, call requestPermissionsFromUser to apply for the permission. + if (needGrantPermission) { + try { + await globalThis.abilityContext.requestPermissionsFromUser(permissions); + } catch (err) { + console.error('app permission request permissions error' + JSON.stringify(err)); + } + } else { + console.info('app permission already granted'); + } + } + ``` + +3. Register the continuation management service and obtain a token. + + The sample code is as follows: + + ```ts + let token: number = -1; // Used to save the token returned after the registration. The token will be used when listening for device connection/disconnection events, starting the device selection module, and updating the device connection state. + + continuationManager.register().then((data) => { + console.info('register finished, ' + JSON.stringify(data)); + token = data; // Obtain a token and assign a value to the token variable. + }).catch((err) => { + console.error('register failed, cause: ' + JSON.stringify(err)); + }); + ``` + +4. Listen for the device connection/disconnection state. + + The sample code is as follows: + + ```ts + let remoteDeviceId: string = ""; // Used to save the information about the remote device selected by the user, which will be used for cross-device continuation or collaboration. + + // The token parameter is the token obtained during the registration. + continuationManager.on("deviceConnect", token, (continuationResults) => { + console.info('registerDeviceConnectCallback len: ' + continuationResults.length); + if (continuationResults.length <= 0) { + console.info('no selected device'); + return; + } + remoteDeviceId = continuationResults[0].id; // Assign the deviceId of the first selected remote device to the remoteDeviceId variable. + + // Pass the remoteDeviceId parameter to want. + let want = { + deviceId: remoteDeviceId, + bundleName: 'ohos.samples.continuationmanager', + abilityName: 'MainAbility' + }; + // To initiate multi-device collaboration, you must obtain the ohos.permission.DISTRIBUTED_DATASYNC permission. + globalThis.abilityContext.startAbility(want).then((data) => { + console.info('StartRemoteAbility finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('StartRemoteAbility failed, cause: ' + JSON.stringify(err)); + }); + }); + ``` + + The preceding multi-device collaboration operation is performed across devices in the stage model. For details about this operation in the FA model, see [Page Ability Development](https://gitee.com/openharmony/docs/blob/master/en/application-dev/ability/fa-pageability.md). + + You can also instruct the device selection module to update the device connection state. The sample code is as follows: + + ```ts + // Set the device connection state. + let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.CONNECTED; + + // The token parameter is the token obtained during the registration, and the remoteDeviceId parameter is the remoteDeviceId obtained. + continuationManager.updateConnectStatus(token, remoteDeviceId, deviceConnectStatus).then((data) => { + console.info('updateConnectStatus finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('updateConnectStatus failed, cause: ' + JSON.stringify(err)); + }); + ``` + + Listen for the device disconnection state so that the user can stop cross-device continuation or collaboration in time. The sample code is as follows: + + ```ts + // The token parameter is the token obtained during the registration. + continuationManager.on("deviceDisconnect", token, (deviceIds) => { + console.info('onDeviceDisconnect len: ' + deviceIds.length); + if (deviceIds.length <= 0) { + console.info('no unselected device'); + return; + } + + // Update the device connection state. + let unselectedDeviceId: string = deviceIds[0]; // Assign the deviceId of the first deselected remote device to the unselectedDeviceId variable. + let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.DISCONNECTING; // Device disconnected. + + // The token parameter is the token obtained during the registration, and the unselectedDeviceId parameter is the unselectedDeviceId obtained. + continuationManager.updateConnectStatus(token, unselectedDeviceId, deviceConnectStatus).then((data) => { + console.info('updateConnectStatus finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('updateConnectStatus failed, cause: ' + JSON.stringify(err)); + }); + }); + ``` + +5. Start the device selection module to show the list of available devices on the network. + + The sample code is as follows: + + ```ts + // Filter parameters. + let continuationExtraParams = { + deviceType: ["00E"], // Device type. + continuationMode: continuationManager.ContinuationMode.COLLABORATION_SINGLE // Single-choice mode of the device selection module. + }; + + // The token parameter is the token obtained during the registration. + continuationManager.startDeviceManager(token, continuationExtraParams).then((data) => { + console.info('startDeviceManager finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('startDeviceManager failed, cause: ' + JSON.stringify(err)); + }); + ``` + +6. If you do not need to perform cross-device migration or collaboration operations, you can deregister the continuation management service, by passing the token obtained during the registration. + + The sample code is as follows: + + ```ts + // The token parameter is the token obtained during the registration. + continuationManager.unregister(token).then((data) => { + console.info('unregister finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('unregister failed, cause: ' + JSON.stringify(err)); + }); + ``` diff --git a/en/application-dev/ability/figures/continuationManager.png b/en/application-dev/ability/figures/continuationManager.png new file mode 100644 index 0000000000000000000000000000000000000000..8447f339a8fc2e911aaf7d3f86557c980eecac44 Binary files /dev/null and b/en/application-dev/ability/figures/continuationManager.png differ diff --git a/en/application-dev/website.md b/en/application-dev/website.md index 0726f2d6fc16127147536e0a1c260db5a7a1c06d..d4635b57a336ef5f019f5eba6855d841b4ae5560 100644 --- a/en/application-dev/website.md +++ b/en/application-dev/website.md @@ -4,10 +4,10 @@ - Quick Start - Getting Started - [Preparations](quick-start/start-overview.md) - - [Getting Started with eTS in the Traditional Coding Approach](quick-start/start-with-ets.md) - - [Getting Started with eTS in the Low-Code Approach](quick-start/start-with-ets-low-code.md) - - [Getting Started with JavaScript in the Traditional Coding Approach](quick-start/start-with-js.md) - - [Getting Started with JavaScript in the Low-Code Approach](quick-start/start-with-js-low-code.md) + - [Getting Started with eTS in Stage Model](quick-start/start-with-ets-stage.md) + - [Getting Started with eTS in FA Model](quick-start/start-with-ets-fa.md) + - [Getting Started with JavaScript in FA Model](quick-start/start-with-js-fa.md) + - Development Fundamentals - [Application Package Structure Configuration File (FA Model)](quick-start/package-structure.md) - [Application Package Structure Configuration File (Stage Model)](quick-start/stage-structure.md) @@ -33,6 +33,7 @@ - Other - [WantAgent Development](ability/wantagent.md) - [Ability Assistant Usage](ability/ability-assistant-guidelines.md) + - [ContinuationManager Development](ability/continuationmanager.md) - [Test Framework Usage](ability/ability-delegator.md) - UI Development - [ArkUI Overview](ui/arkui-overview.md) @@ -191,7 +192,9 @@ - Window Manager - Window - [Window Overview](windowmanager/window-overview.md) - - [Window Development](windowmanager/window-guidelines.md) + - [Application Window Development (Stage Mode)](windowmanager/application-window-stage.md) + - [Application Window Development (FA Model)](windowmanager/application-window-fa.md) + - [System Window Development (Stage Model Only)](windowmanager/system-window-stage.md) - Display - [Display Overview](windowmanager/display-overview.md) - [Display Development](windowmanager/display-guidelines.md) @@ -261,6 +264,9 @@ - Distributed Data Object - [Distributed Data Object Overview](database/database-distributedobject-overview.md) - [Distributed Data Object Development](database/database-distributedobject-guidelines.md) + - Data Share + - [DataShare Overview](database/database-datashare-overview.md) + - [DataShare Development](database/database-datashare-guidelines.md) - Task Management - Background Task Management - [Background Task Management Overview](task-management/background-task-overview.md) @@ -308,8 +314,8 @@ - Native APIs - [Using Native APIs in Application Projects](napi/napi-guidelines.md) - [Drawing Development](napi/drawing-guidelines.md) - - [Native Window Development](napi/native-window-guidelines.md) - [Raw File Development](napi/rawfile-guidelines.md) + - [Native Window Development](napi/native-window-guidelines.md) - Tools - [DevEco Studio (OpenHarmony) User Guide](quick-start/deveco-studio-user-guide-for-openharmony.md) - Hands-On Tutorials @@ -571,7 +577,7 @@ - [slot](reference/arkui-js/js-components-custom-slot.md) - [Lifecycle Definition](reference/arkui-js/js-components-custom-lifecycle.md) - [Data Type Attributes](reference/arkui-js/js-appendix-types.md) - - APIs + - JS and TS APIs - [API Reference Document Description](reference/apis/development-intro.md) - Ability Framework - FA Model @@ -589,6 +595,7 @@ - [@ohos.application.ServiceExtensionAbility](reference/apis/js-apis-service-extension-ability.md) - [@ohos.application.StartOptions](reference/apis/js-apis-application-StartOptions.md) - [@ohos.application.StaticSubscriberExtensionAbility](reference/apis/js-apis-application-staticSubscriberExtensionAbility.md) + - [@ohos.application.WindowExtensionAbility](reference/apis/js-apis-application-WindowExtensionAbility.md) - [AbilityContext](reference/apis/js-apis-ability-context.md) - [ApplicationContext](reference/apis/js-apis-application-applicationContext.md) - [AbilityStageContext](reference/apis/js-apis-abilitystagecontext.md) @@ -602,16 +609,23 @@ - [@ohos.ability.errorCode](reference/apis/js-apis-ability-errorCode.md) - [@ohos.ability.wantConstant](reference/apis/js-apis-ability-wantConstant.md) - [@ohos.application.abilityDelegatorRegistry](reference/apis/js-apis-abilityDelegatorRegistry.md) + - [@ohos.application.abilityManager](reference/apis/js-apis-application-abilityManager.md) + - [@ohos.application.AccessibilityExtensionAbility](reference/apis/js-apis-accessibility-extension-context.md) + - [@ohos.application.AccessibilityExtensionAbility](reference/apis/js-apis-application-AccessibilityExtensionAbility.md) - [@ohos.application.appManager](reference/apis/js-apis-appmanager.md) - [@ohos.application.Configuration](reference/apis/js-apis-configuration.md) - [@ohos.application.ConfigurationConstant](reference/apis/js-apis-configurationconstant.md) + - [@ohos.application.EnvironmentCallback](reference/apis/js-apis-application-EnvironmentCallback.md) + - [@ohos.application.errorManager](reference/apis/js-apis-errorManager.md) - [@ohos.application.formBindingData](reference/apis/js-apis-formbindingdata.md) - [@ohos.application.formError](reference/apis/js-apis-formerror.md) - [@ohos.application.formHost](reference/apis/js-apis-formhost.md) - [@ohos.application.formInfo](reference/apis/js-apis-formInfo.md) - - [@ohos.application.missionManager](reference/apis/js-apis-missionManager.md) - [@ohos.application.formProvider](reference/apis/js-apis-formprovider.md) + - [@ohos.application.missionManager](reference/apis/js-apis-missionManager.md) - [@ohos.application.Want](reference/apis/js-apis-application-Want.md) + - [@ohos.continuation.continuationManager](reference/apis/js-apis-continuation-continuationExtraParams.md) + - [@ohos.continuation.continuationManager](reference/apis/js-apis-continuation-continuationManager.md) - [@ohos.wantAgent](reference/apis/js-apis-wantAgent.md) - [abilityDelegator](reference/apis/js-apis-application-abilityDelegator.md) - [abilityDelegatorArgs](reference/apis/js-apis-application-abilityDelegatorArgs.md) @@ -621,6 +635,7 @@ - [MissionSnapshot](reference/apis/js-apis-application-MissionSnapshot.md) - [ProcessRunningInfo](reference/apis/js-apis-processrunninginfo.md) - [shellCmdResult](reference/apis/js-apis-application-shellCmdResult.md) + - [ContinuationResult](reference/apis/js-apis-continuation-continuationResult.md) - Common Event and Notification - [@ohos.commonEvent](reference/apis/js-apis-commonEvent.md) - [@ohos.events.emitter](reference/apis/js-apis-emitter.md) @@ -630,24 +645,36 @@ - Bundle Management - [@ohos.bundle](reference/apis/js-apis-Bundle.md) - [@ohos.bundle.defaultAppManager](reference/apis/js-apis-bundle-defaultAppManager.md) + - [@ohos.bundle.innerBundleManager)](reference/apis/js-apis-Bundle-InnerBundleManager.md) - [@ohos.bundleState](reference/apis/js-apis-deviceUsageStatistics.md) + - [@ohos.distributedBundle](reference/apis/js-apis-Bundle-distributedBundle.md) - [@ohos.zlib](reference/apis/js-apis-zlib.md) - [AbilityInfo](reference/apis/js-apis-bundle-AbilityInfo.md) - [ApplicationInfo](reference/apis/js-apis-bundle-ApplicationInfo.md) - [BundleInfo](reference/apis/js-apis-bundle-BundleInfo.md) + - [BundleInstaller](reference/apis/js-apis-bundle-BundleInstaller.md) - [CustomizeData](reference/apis/js-apis-bundle-CustomizeData.md) + - [DispatchInfo](reference/apis/js-apis-dispatchInfo.md) - [ElementName](reference/apis/js-apis-bundle-ElementName.md) - [ExtensionAbilityInfo](reference/apis/js-apis-bundle-ExtensionAbilityInfo.md) - [HapModuleInfo](reference/apis/js-apis-bundle-HapModuleInfo.md) + - [LauncherAbilityInfo](reference/apis/js-apis-bundle-LauncherAbilityInfo.md) - [Metadata](reference/apis/js-apis-bundle-Metadata.md) - [ModuleInfo](reference/apis/js-apis-bundle-ModuleInfo.md) + - [PermissionDef](reference/apis/js-apis-bundle-PermissionDef.md) + - [RemoteAbilityInfo](reference/apis/js-apis-bundle-remoteAbilityInfo.md) + - [ShortcutInfo](reference/apis/js-apis-bundle-ShortcutInfo.md) - UI Page - [@ohos.animator](reference/apis/js-apis-animator.md) - [@ohos.mediaquery](reference/apis/js-apis-mediaquery.md) - [@ohos.prompt](reference/apis/js-apis-prompt.md) - [@ohos.router](reference/apis/js-apis-router.md) + - [@ohos.uiAppearance](reference/apis/js-apis-uiappearance.md) - Graphics + - [@ohos.animation.windowAnimationManager](reference/apis/js-apis-windowAnimationManager.md) - [@ohos.display](reference/apis/js-apis-display.md) + - [@ohos.effectKit](reference/apis/js-apis-effectKit.md) + - [@ohos.screen](reference/apis/js-apis-screen.md) - [@ohos.screenshot](reference/apis/js-apis-screenshot.md) - [@ohos.window](reference/apis/js-apis-window.md) - [webgl](reference/apis/js-apis-webgl.md) @@ -664,6 +691,7 @@ - [@ohos.resourceManager](reference/apis/js-apis-resource-manager.md) - Resource Scheduling - [@ohos.backgroundTaskManager](reference/apis/js-apis-backgroundTaskManager.md) + - [@ohos.distributedMissionManager](reference/apis/js-apis-distributedMissionManager.md) - [@ohos.workScheduler](reference/apis/js-apis-workScheduler.md) - [@ohos.WorkSchedulerExtensionAbility](reference/apis/js-apis-WorkSchedulerExtensionAbility.md) - Custom Management @@ -735,6 +763,7 @@ - [@ohos.screenLock](reference/apis/js-apis-screen-lock.md) - [@ohos.systemTime](reference/apis/js-apis-system-time.md) - [@ohos.wallpaper](reference/apis/js-apis-wallpaper.md) + - [@ohos.systemTimer](reference/apis/js-apis-system-timer.md) - [Timer](reference/apis/js-apis-timer.md) - Device Management - [@ohos.batteryInfo](reference/apis/js-apis-battery-info.md) @@ -811,4 +840,15 @@ - [@system.sensor](reference/apis/js-apis-system-sensor.md) - [@system.storage](reference/apis/js-apis-system-storage.md) - [@system.vibrator](reference/apis/js-apis-system-vibrate.md) - - [console](reference/apis/js-apis-logs.md) \ No newline at end of file + - [console](reference/apis/js-apis-logs.md) + - Native APIs + - Standard Libraries Supported by Native APIs + - [Node_API](reference/native-lib/third_party_napi/napi.md) + - [libuv](reference/native-lib/third_party_libuv/libuv.md) + - [Native Standard Libraries Supported by Openharmony](reference/native-lib/third_party_libc/musl.md) + - Appendix + - [Native API Symbols Not Exported](reference/native-lib/third_party_libc/musl-peculiar-symbol.md) + - [EGL Symbols Exported from Native APIs](reference/native-lib/third_party_opengl/egl-symbol.md) + - [OpenGL ES 3.0 Symbols Exported from Native APIs](reference/native-lib/third_party_opengl/openglesv3-symbol.md) +- FAQs + - [Guide to Switching to Full SDK](quick-start/full-sdk-switch-guide.md) \ No newline at end of file