• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Distributed Extension Ability Development
2<!--Kit: Distributed Service Kit-->
3<!--Subsystem: DistributedSched-->
4<!--Owner: @hobbycao-->
5<!--Designer: @gsxiaowen-->
6<!--Tester: @hanjiawei-->
7<!--Adviser: @w_Machine_cc-->
8
9## Introduction
10
11The distributed service allows a device to extend its capabilities by cooperating with other devices in various complex scenarios.
12
13As it is inconvenient for users to use a single account on different devices, the cross-device collaboration capability is provided, enabling a message synchronization mechanism for collaboration between applications on mobile phones and other devices such as watches.
14
15### Available Capabilities
16
17Data interaction: implements cross-device transmission of data, including text messages, byte streams, images, and transport streams. (Only text interaction is supported for third-party applications.)
18
19### Typical Use Cases
20
21During cross-device collaboration, when device A is running in the background and device B is running in the foreground, Distributed Management Service (DMS) allows the system to activate **DistributedExtension** to implement synchronous data transmission across devices. For example, when an application runs in the background on the mobile phone and in the foreground on the watch, DMS starts **DistributedExtensionAbility** to synchronize uplink messages on the watch to the application on the mobile phone.
22
23### Basic concepts
24
25Before you get started, familiarize yourself with the following concepts:
26
27* **DMS**
28
29  A framework that provides distributed component management capabilities.
30* **UIAbility**
31
32  A component that implements tasks specific to application UIs, such as lifecycle management, user interaction, and UI rendering.
33* **ExtensionAbility**
34
35  A component that extends application functions or implements cross-device collaboration. It allows applications to run some tasks in the background or migrates some functions to other devices for execution, implementing distributed capabilities.
36* **Byte stream**
37
38  Data of the [ArrayBuffer](../arkts-utils/arraybuffer-object.md) type, which can be used to store binary data, for example, image or audio data.
39* **Transport stream**
40
41  Media streams that can be used to transmit images, audios, text information, and bytes.
42
43## Implementation Principles
44
45The application on device A integrates **DistributedExtensionAbility**. When DSoftBus on device A receives a message from the application, **DistributedExtensionAbility** starts the application background service on device A to send the application message from device B to the application service.
46
47![DistributedExtension](figures/distributedextension.png)
48
49## Constraints
50
51* You need to log in with the same HUAWEI ID on different devices.
52* Cross-device collaboration is supported only for UIAbility applications with the same bundle name on different devices.
53
54## Environment Preparation
55
56### Environment requirements
57
58You have logged in to devices A and B with the same HUAWEI ID and the two devices are successfully networked through Bluetooth.
59
60### Environment Setup
61
621. Install [DevEco Studio](https://gitee.com/link?target=https%3A%2F%2Fdeveloper.huawei.com%2Fconsumer%2Fcn%2Fdownload%2Fdeveco-studio) 4.1 or later on the PC.
632. Update the public-SDK to API version 20 or later.
643. Enable Bluetooth on devices A and B to implement networking.
65
66### Environment Verification
67
68Connect devices A and B to the PC and run the shell command on the PC:
69
70```shell
71hdc shell
72hidumper -s 4700 -a "buscenter -l remote_device_info"
73```
74
75If the networking is successful, the number of networking devices is displayed, for example, **remote device num = 1**.
76
77## How to Develop
78
79Cross-device connection management enables real-time processing of application background messages through the distributed OS, providing users with more efficient experience.
80
81### APIs
82
83For details about how to use the **DistributedExtensionAbility** APIs, see [DistributedExtensionAbility API Reference](../reference/apis-distributedservice-kit/js-apis-distributedExtensionAbility.md).
84
85| API                                                              | Description                      |
86| -------------------------------------------------------------------- | -------------------------- |
87| onCreate(want: Want): void;                                          | Creates a distributed collaboration task.      |
88| onDestroy(): void;                                                   | Destroys a distributed collaboration task.         |
89| onCollaborate(wantParam: Record): AbilityConstant.CollaborateResult; | Called when distributed collaboration is requested.|
90
91### How to Develop
92
931. Register the `Extension` component in the configuration file.
94
95   In the application configuration file `module.json5`, add the `"extensionAbilities"` field, set `"type"` to `"distributed"`, and add an entry whose `"name"` is `"ohos.extension.DistributedExtension"` to ["metadata"](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md).
96
97   Example:
98
99   ```json
100   "extensionAbilities": [
101     {
102       "name": "EntrydistributedAbility",
103       "srcEntry": "./ets/entrybackupability/EntryDistributedAbility.ets",
104       "type": "distributed",
105       "exported": false,
106       "metadata": [
107         {
108           "name": "ohos.extension.DistributedExtension",
109         }
110       ],
111       "srcEntry": "./ets/common/MDSExtension.ts",
112     }
113   ]
114   ```
1152. Import the required modules.
116
117   ```ts
118   import { AbilityConstant, Want } from '@kit.AbilityKit';
119   import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit';
120   ```
1213. Customize the `MDSExtension.ets` file. Specifically, inherit the `DistributedExtensionAbility` class and rewrite the `onCreate`, `onDestroy` and `onCollaborate` methods to create and destroy **DistributedExtension** and implement connection callback.
122
123   The following is an empty `MDSExtension.ets` file. You can observe its lifecycle based on the corresponding **Logger**.
124
125   ```ts
126   import { AbilityConstant, Want } from '@kit.AbilityKit';
127   import { abilityConnectionManager, DistributedExtensionAbility } from '@kit.DistributedServiceKit';
128
129   export default class DistributedExtension extends DistributedExtensionAbility {
130     onCreate(want: Want) {
131       console.info(`DistributedExtension Create ok`);
132       console.info(`DistributedExtension on Create want: ${JSON.stringify(want)}`);
133       console.info(`DistributedExtension on Create end`);
134     }
135
136     onCollaborate(wantParam: Record<string, Object>) {
137       console.info(`DistributedExtension onCollabRequest Accept to the result of Ability collaborate`);
138       let sessionId = -1;
139       const collaborationValues = wantParam["CollaborationValues"] as abilityConnectionManager.CollaborationValues;
140       if (collaborationValues == undefined) {
141         return sessionId;
142       }
143
144       console.info(`onCollab, collaborationValues: ${JSON.stringify(collaborationValues)}`);
145       return AbilityConstant.CollaborateResult.ACCEPT;
146     }
147
148     onDestroy() {
149       console.info(`DistributedExtension onDestroy ok`);
150     }
151   }
152   ```
153
154## Common Inquiry
155
156### What should I do if device B does not receive the response message from device A?
157
158**Possible Causes**
159
160Devices are not networking. As a result, the connection between device A and device B times out.
161
162**Solution**
163
164Enable USB debugging on device A and device B, and use a USB cable to connect the devices to the PC. Run the following shell command on the PC:
165
166```
167hdc shell
168hidumper -s 4700 -a "buscenter -l remote_device_info"
169```
170
171If **remote device num = 0** is displayed in the command output, the networking has failed. Ensure that you log in to devices using the same HUAWEI ID and connect them through Bluetooth. If the networking is successful, the number of networking devices is displayed, for example, **remote device num = 1**.
172
173### What should I do if ongoing collaboration services are interrupted because no operation is performed on the application for a long time?
174
175**Possible Causes**
176
177During service collaboration, DMS keeps listening for the collaboration lifecycle. After the operation lasts for 10 seconds, the collaboration is ended.
178
179**Solution**
180
181Resend the message to restart the collaboration.
182