提交 f3828be9 编写于 作者: G Gloria

update docs against 7770

Signed-off-by: wusongqing<wusongqing@huawei.com>
上级 a3104368
......@@ -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)
# 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\<number>): 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\<number>): void | Registers the continuation management service and obtains a token. This API uses an asynchronous callback to return the result.|
| register(options?: ContinuationExtraParams): Promise\<number> | 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\<Array\<ContinuationResult>>): void | Subscribes to device connection events. This API uses an asynchronous callback to return the result.|
| on(type: "deviceDisconnect", token: number, callback: Callback\<Array\<string>>): 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>): 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>): 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\<void> | 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>): 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\<void> | 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>): void | Deregisters the continuation management service. This API uses an asynchronous callback to return the result.|
| unregister(token: number): Promise\<void> | 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<string> = [
"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<string> = [
"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));
});
```
......@@ -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
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册