The distributed data objects allow data across devices to be processed like local variables by shielding complex data interaction between devices. For the devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other devices. The devices can listen for the data changes and online and offline status of other devices. The distributed data objects support basic data types, such as number, string, and Boolean, as well as complex data types, such as array and nested basic types.
Distributed data objects allow data traversing across devices to be processed like local variables by shielding complex data interaction between devices. For the devices that form a Super Device, when data in the distributed data object of an application is added, deleted, or modified on a device, the data for the same application is also updated on the other devices. The devices can listen for data changes and online and offline status changes of other devices.
The distributed data objects support basic data types, such as number, string, and Boolean, as well as complex data types, such as array and nested basic types.
## Available APIs
## Available APIs
...
@@ -13,16 +15,16 @@ Call **createDistributedObject()** to create a distributed data object instance.
...
@@ -13,16 +15,16 @@ Call **createDistributedObject()** to create a distributed data object instance.
**Table 1** API for creating a distributed data object instance
**Table 1** API for creating a distributed data object instance
| Package| API| Description|
| Package | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>- **source**: attributes of the **distributedObject** set.<br>- **DistributedObject**: returns the distributed object created.|
| ohos.data.distributedDataObject| createDistributedObject(source: object): DistributedObject | Creates a distributed data object instance for data operations.<br>-**source**: attributes of the **distributedObject** set.<br>- **DistributedObject**: returns the distributed object created.|
### Generating a Session ID
### Generating a Session ID
Call **genSessionId()** to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object.
Call **genSessionId()** to generate a session ID randomly. The generated session ID can be used to set the session ID of a distributed data object.
**Table 2** API for generating a session ID randomly
**Table 2** API for generating a session ID randomly
| Package| API| Description|
| Package | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.|
| ohos.data.distributedDataObject| genSessionId(): string | Generates a session ID, which can be used as the session ID of a distributed data object.|
...
@@ -33,24 +35,24 @@ Call **setSessionId()** to set a session ID for a distributed data object. The s
...
@@ -33,24 +35,24 @@ Call **setSessionId()** to set a session ID for a distributed data object. The s
**Table 3** API for setting a session ID
**Table 3** API for setting a session ID
| Class| API| Description|
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.<br> **sessionId**: session ID of a distributed object in a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.|
| DistributedDataObject | setSessionId(sessionId?: string): boolean | Sets a session ID for distributed data objects.<br>**sessionId**: session ID of a distributed object in a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.|
### Observing Data Changes
### Observing Data Changes
Call **on()** to subscribe to data changes of a distributed data object. When the data changes, a callback will be invoked to return the data changes. You can use **off()** to unsubscribe from the data changes.
Call **on()** to subscribe to data changes of a distributed data object. In the case of data change, a callback will be invoked to return the data changes. You can use **off()** to unsubscribe from the data changes.
**Table 4** APIs for observing data changes of a distributed data object
**Table 4** APIs for observing data changes of a distributed data object
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'change', callback: Callback<{sessionId:string,fields:Array<string>}>): void | Subscribes to data changes.|
| DistributedDataObject| on(type: 'change', callback: Callback<{sessionId:string,fields:Array<string>}>): void | Subscribes to data changes.|
| DistributedDataObject| off(type: 'change', callback?: Callback<{sessionId:string,fields:Array<string>}>): void | Unsubscribes from data changes.**Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
| DistributedDataObject| off(type: 'change', callback?: Callback<{sessionId:string,fields:Array<string>}>): void | Unsubscribes from data changes.<br>**Callback**: specifies callback used to return changes of the distributed data object. If this parameter is not specified, all callbacks related to data changes will be unregistered.|
### Observing Online or Offline Status
### Observing Online or Offline Status
Call **on()** to subscribe to status changes of a distributed data object. The status can be online or offline. When the status changes, a callback will be invoked to return the status. You can use **off()** to unsubscribe from the status changes.
Call **on()** to subscribe to status changes of a distributed data object. The status can be online or offline. When the status changes, a callback will be invoked to return the status. You can use **off()** to unsubscribe from the status changes.
**Table 5** APIs for observing status changes of a distributed data object
**Table 5** APIs for observing status changes of a distributed data object
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject| on(type: 'status', callback: Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}>): void | Subscribes to the status changes of a distributed data object.|
| DistributedDataObject| on(type: 'status', callback: Callback<{sessionId:string,networkId:string,status:'online'\|'offline'}>): void | Subscribes to the status changes of a distributed data object.|
| DistributedDataObject| off(type: 'status', callback?: Callback<{sessionId:string,deviceId:string,status:'online'\|'offline'}>): void | Unsubscribes from status changes of a distributed data object.|
| DistributedDataObject| off(type: 'status', callback?: Callback<{sessionId:string,deviceId:string,status:'online'\|'offline'}>): void | Unsubscribes from status changes of a distributed data object.|
...
@@ -68,22 +70,26 @@ The saved data will be released in the following cases:
...
@@ -68,22 +70,26 @@ The saved data will be released in the following cases:
- Data is successfully restored.
- Data is successfully restored.
**Table 6** APIs for saving a distributed data object and revoking the saving
**Table 6** APIs for saving a distributed data object and revoking the saving
| Class| API| Description|
| Class | API | Description |
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| DistributedDataObject | save(deviceId: string): Promise<SaveSuccessResponse> | Saves a distributed data object. This API uses a promise to return the result.|
| DistributedDataObject | save(deviceId: string): Promise<SaveSuccessResponse> | Saves a distributed data object. This API uses a promise to return the result.|
| DistributedDataObject| save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void | Saves a distributed data object. This API uses an asynchronous callback to return the result.|
| DistributedDataObject | save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void | Saves a distributed data object. This API uses an asynchronous callback to return the result. |
| DistributedDataObject | revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void | Revokes the data saving operation. This API uses an asynchronous callback to return the result. |
| DistributedDataObject | revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void | Revokes the data saving operation. This API uses an asynchronous callback to return the result. |
| DistributedDataObject| revokeSave(): Promise<RevokeSaveSuccessResponse> | Revokes the data saving operation. This API uses a promise to return the result. |
| DistributedDataObject| revokeSave(): Promise<RevokeSaveSuccessResponse> | Revokes the data saving operation. This API uses a promise to return the result. |
## How to Develop
## How to Develop
The following example shows how to implement a distributed data object synchronization.
The following example shows how to implement distributed data object synchronization.
1. Import the @ohos.data.distributedDataObject module to the development environment.
1. Import the @ohos.data.distributedDataObject module to the development environment.
2. Request the permission. <br>Add the required permission in the **config.json** file. The sample code is as follows:
2. Request the permission.
Add the required permission in the **config.json** file. The sample code is as follows:
```
```
{
{
"module": {
"module": {
...
@@ -95,7 +101,8 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -95,7 +101,8 @@ The following example shows how to implement a distributed data object synchroni
}
}
}
}
```
```
This permission must also be authorized by the user through a dialog box when the application is started for the first time. The sample code is as follows:
When a user starts the application for the first time, this permission must also be authorized by the user through a dialog box. The sample code is as follows:
```js
```js
import featureAbility from '@ohos.ability.featureAbility';
import featureAbility from '@ohos.ability.featureAbility';
...
@@ -114,6 +121,7 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -114,6 +121,7 @@ The following example shows how to implement a distributed data object synchroni
6. Modify object attributes. <br>The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types).
6. Modify object attributes. The object attributes support basic data types (such as number, Boolean, and string) and complex data types (array and nested basic types).
The sample code is as follows:
The sample code is as follows:
```js
```js
...
@@ -186,6 +194,7 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -186,6 +194,7 @@ The following example shows how to implement a distributed data object synchroni
8. Unsubscribe from data changes. <br>You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered.
8. Unsubscribe from data changes. <br>You can specify the callback to unregister. If you do not specify the callback, all data change callbacks of the distributed data object will be unregistered.
The sample code is as follows:
The sample code is as follows:
```js
```js
// Unregister the specified data change callback.
// Unregister the specified data change callback.
local_object.off("change",changeCallback);
local_object.off("change",changeCallback);
...
@@ -193,7 +202,9 @@ The following example shows how to implement a distributed data object synchroni
...
@@ -193,7 +202,9 @@ The following example shows how to implement a distributed data object synchroni
local_object.off("change");
local_object.off("change");
```
```
9. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.
9. Subscribe to the status (online/offline) changes of the distributed data object. A callback will be invoked to report the status change when the target distributed data object goes online or offline.
When an event of the Notepad app occurs on a device, such as a note is added, the tile or content of a note is changed, or the event list is cleared, the change will be synchronized to other devices in the trusted network.
When an event of the Notepad app occurs on a device, such as a note is added, the title or content of a note is changed, or the event list is cleared, the change will be synchronized to other devices in the trusted network.