diff --git a/en/application-dev/reference/apis/js-apis-data-distributedobject.md b/en/application-dev/reference/apis/js-apis-data-distributedobject.md index dc8bf8258b987e9e4ad2799516ee6aafeb487896..d3285fa80427790ba723737e20bc5559f0cc85ab 100644 --- a/en/application-dev/reference/apis/js-apis-data-distributedobject.md +++ b/en/application-dev/reference/apis/js-apis-data-distributedobject.md @@ -2,7 +2,7 @@ The **distributedDataObject** module provides basic data object management, including creating, querying, deleting, modifying, and subscribing to data objects, and distributed data object collaboration for the same application among multiple devices. -> **NOTE**
+> **NOTE** > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -13,32 +13,58 @@ The **distributedDataObject** module provides basic data object management, incl import distributedObject from '@ohos.data.distributedDataObject'; ``` -## distributedDataObject.createDistributedObject - -createDistributedObject(source: object): DistributedObject +## distributedObject.create9+ +create(context: Context, source: object): DistributedObjectV9 Creates a distributed data object. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| source | object | Yes| Attribute of the distributed data object to create.| +| context | Context | Yes| Application context.
For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).
For details about the application context of the stage model, see [Context](js-apis-ability-context.md).| +| source | object | Yes| Attributes of the distributed data object.| **Return value** + | Type| Description| | -------- | -------- | -| [DistributedObject](#distributedobject) | Distributed data object created.| +| [DistributedObjectV9](#distributedobjectv9) | Distributed data object created.| **Example** + +FA model: + ```js +// Import the module. import distributedObject from '@ohos.data.distributedDataObject'; -// Create a distributed data object, which contains attributes of four types, namely, string, number, boolean, and object. -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +// Create a distributed data object, which contains attributes of the string, number, boolean, and object types. +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); ``` +Stage model: + +```ts +// Import the module. +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +// Create a distributed data object, which contains attributes of the string, number, boolean, and object types. +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +``` ## distributedObject.genSessionId @@ -49,14 +75,16 @@ Creates a random session ID. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Return value** + | Type| Description| | -------- | -------- | | string | Session ID created.| **Example** + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var sessionId = distributedObject.genSessionId(); +let sessionId = distributedObject.genSessionId(); ``` ## SaveSuccessResponse9+ @@ -65,11 +93,11 @@ Called when the **Save()** API is successfully called. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject -| Name| Type| Description| -| -------- | -------- | -------- | -| sessionId | string | Unique ID for multi-device collaboration.| -| version | number |Version of the distributed data object saved.| -| deviceId | string | ID of the device where the distributed data object is stored. The default value is **local**, which identifies a local device. You can set it as required.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| sessionId | string | Yes| Unique ID for multi-device collaboration.| +| version | number | Yes| Version of the distributed data object saved.| +| deviceId | string | Yes| ID of the device where the distributed data object is stored. The default value is **local**, which identifies a local device. You can set it as required.| ## RevokeSaveSuccessResponse9+ @@ -77,17 +105,144 @@ Called when the **revokeSave()** API is successfully called. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject -| Name| Type| Description| -| -------- | -------- | -------- | -| sessionId | string | Unique ID for multi-device collaboration.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| sessionId | string | Yes| Unique ID for multi-device collaboration.| -## DistributedObject +## DistributedObjectV9 -Represents a distributed data object. +Provides APIs for managing a distributed data object. -### setSessionId +### setSessionId9+ -setSessionId(sessionId?: string): boolean +setSessionId(sessionId: string, callback: AsyncCallback<void>): void + +Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network. + +**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| sessionId | string | Yes| ID of a distributed data object on a trusted network.| +| callback | AsyncCallback<void> | Yes| Asynchronous callback invoked when the session ID is successfully set.| + +**Error codes** + + For details about the error codes, see [Distributed Data Object Error Codes] (../errorcodes/errorcode-distributed-dataObject.md). + +| ID| Error Message| +| -------- | -------- | +| 15400001 | Failed to create the in-memory database.| + +**Example** + +FA model: + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +``` +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +``` + +### setSessionId9+ + +setSessionId(callback: AsyncCallback<void>): void + +Exits all joined sessions. + +**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Asynchronous callback invoked when the distributed data object exits all joined sessions.| + +**Error codes** + + For details about the error codes, see [Distributed Data Object Error Codes] (../errorcodes/errorcode-distributed-dataObject.md). + +| ID| Error Message| +| -------- | -------- | +| 15400001 | Failed to create the in-memory database.| + +**Example** + +FA model: + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +// Exit the distributed network. +g_object.setSessionId(() => { + console.log("leave all lession."); +}); +``` +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId(), ()=>{ + console.log("join session"); +}); +// Exit the distributed network. +g_object.setSessionId(() => { + console.log("leave all lession."); +}); +``` + +### setSessionId9+ + +setSessionId(sessionId?: string): Promise<void> Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network. @@ -105,38 +260,117 @@ Sets a session ID for synchronization. Automatic synchronization is performed fo | Type| Description| | -------- | -------- | -| boolean | Returns **true** if the session ID is set successfully;
returns **false** otherwise. | +| Promise<void> | Promise that returns no value.| + +**Error codes** + + For details about the error codes, see [Distributed Data Object Error Codes] (../errorcodes/errorcode-distributed-dataObject.md). + +| ID| Error Message| +| -------- | -------- | +| 15400001 | Failed to create the in-memory database.| **Example** +FA model: + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); // Add g_object to the distributed network. -g_object.setSessionId(distributedObject.genSessionId()); -// Remove g_object from the distributed network. -g_object.setSessionId(""); +g_object.setSessionId(distributedObject.genSessionId()).then (()=>{ + console.log("join session."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); +// Exit the distributed network. +g_object.setSessionId().then (()=>{ + console.log("leave all lession."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); ``` +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId()).then (()=>{ + console.info("join session."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); +// Exit the distributed network. +g_object.setSessionId().then (()=>{ + console.log("leave all lession."); + }).catch((error)=>{ + console.info("error:" + error.code + error.message); +}); +``` -### on('change') +### on('change')9+ on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void -Subscribes to the changes of this distributed data object. +Subscribes to data changes of this distributed data object. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type to subscribe to. The value is **change**, which indicates data changes.| -| callback | Callback<{ sessionId: string, fields: Array<string> }> | Yes| Callback used to return the changes of the distributed data object.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| +| callback | Callback<{ sessionId: string, fields: Array<string> }> | Yes| Callback invoked to return the changes of the distributed data object.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| **Example** + +FA model: + ```js -import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +globalThis.changeCallback = (sessionId, changeData) => { + console.info("change" + sessionId); + if (changeData != null && changeData != undefined) { + changeData.forEach(element => { + console.info("changed !" + element + " " + g_object[element]); + }); + } +} +g_object.on("change", globalThis.changeCallback); +``` + +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); globalThis.changeCallback = (sessionId, changeData) => { console.info("change" + sessionId); if (changeData != null && changeData != undefined) { @@ -148,81 +382,164 @@ globalThis.changeCallback = (sessionId, changeData) => { g_object.on("change", globalThis.changeCallback); ``` -### off('change') +### off('change')9+ off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void -Unsubscribes from the changes of this distributed data object. +Unsubscribes from the data changes of this distributed data object. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data changes.| -| callback | Callback<{ sessionId: string, fields: Array<string> }> | No| Callback to be unregistered. If this parameter is not set, all data change callbacks of the object will be unregistered.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| +| type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data changes. | +| callback | Callback<{ sessionId: string, fields: Array<string> }> | No| Callback for data changes. If this parameter is not specified, all data change callbacks of this distributed data object will be unregistered.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| **Example** + +FA model: + ```js -import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Unregister the specified data change callback. +g_object.off("change", globalThis.changeCallback); +// Unregister all data change callbacks. +g_object.off("change"); +``` + +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); // Unregister the specified data change callback. g_object.off("change", globalThis.changeCallback); // Unregister all data change callbacks. g_object.off("change"); ``` -### on('status') +### on('status')9+ on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void -Subscribes to the status change (online or offline) of this distributed data object. +Subscribes to statue changes of this distributed data object. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type to subscribe to. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| -| callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | Yes| Callback used to return the status change.
**sessionId**: session ID of the distributed data object.
**networkId**: object device ID, that is, **deviceId**.
**status** indicates the object status, which can be online or offline.| +| callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | Yes| Callback invoked to return the status change.
**sessionId** indicates the session ID of the distributed data object.
**networkId** indicates the object device ID, that is, **deviceId**.
**status** indicates the object status, which can be online or offline.| **Example** + +FA model: + ```js import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); globalThis.statusCallback = (sessionId, networkId, status) => { globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; } -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); g_object.on("status", globalThis.statusCallback); ``` -### off('status') +Stage model: -off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +g_object.on("status", globalThis.statusCallback); +``` + +### off('status')9+ +off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void -Unsubscribes from the status change (online or offline) of this distributed data object. +Unsubscribes from the status change of this distributed data object. **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | type | string | Yes| Event type to unsubscribe from. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| -| callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | No| Callback used to return the status change. If this parameter is not specified, this API unsubscribes from all callbacks of this distributed data object.
**sessionId**: session ID of the distributed data object.
**deviceId** indicates the device ID of the distributed data object.
**status** indicates the status, which can be online or offline.| +| callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | No| Callback for status changes. If this parameter is not specified, all status change callbacks of this distributed data object will be unsubscribed from.
**sessionId** indicates the session ID of the distributed data object.
**deviceId** indicates the device ID of the distributed data object.
**status** indicates the object status, which can be online or offline.| **Example** + +FA model: + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +// Unregister the specified status change callback. +g_object.off("status",globalThis.statusCallback); +// Unregister all status change callbacks. +g_object.off("status"); +``` + +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); globalThis.statusCallback = (sessionId, networkId, status) => { globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; } -// Unsubscribe from the specified status change callback for the distributed data object. +// Unregister the specified status change callback. g_object.off("status",globalThis.statusCallback); -// Unsubscribe from all status change callbacks for the distributed data object. +// Unregister all status change callbacks. g_object.off("status"); ``` @@ -243,18 +560,45 @@ The saved data will be released in the following cases: **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | deviceId | string | Yes| ID of the device where data is stored. The value **local** indicates the local device.| -| callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse9)> | Yes| Callback used to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.| +| callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse9)> | Yes| Callback invoked to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.| **Example** -```js + +FA model: +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local", (result) => { + console.log("save callback"); + console.info("save sessionId: " + result.sessionId); + console.info("save version: " + result.version); + console.info("save deviceId: " + result.deviceId); +}); +``` + +Stage model: +```ts import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); -g_object.save("local", (status, result)=>{ - console.log("save status = " + status); +g_object.save("local", (result) => { console.log("save callback"); console.info("save sessionId: " + result.sessionId); console.info("save version: " + result.version); @@ -279,6 +623,7 @@ The saved data will be released in the following cases: **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | deviceId | string | Yes| ID of the device where the data is saved. The default value is **local**, which indicates the local device. | @@ -293,14 +638,40 @@ The saved data will be released in the following cases: ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context,{name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); +``` + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage){ + context = this.context + } +} +let g_object = distributedObject.create(context,{name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); -g_object.save("local").then((result)=>{ +g_object.save("local").then((result) => { console.log("save callback"); console.info("save sessionId " + result.sessionId); console.info("save version " + result.version); console.info("save deviceId " + result.deviceId); -}, ()=>{ +}, () => { console.error("save failed"); }); ``` @@ -317,18 +688,62 @@ If the object is stored on another device, the data on the local device will be **System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject **Parameters** + | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | No| Callback used to return **RevokeSaveSuccessResponse**, which contains the session ID.| +| callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | Yes| Callback invoked to return **RevokeSaveSuccessResponse**, which contains the session ID.| **Example** +FA model: + ```js import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +// Save data for persistence. +g_object.save("local", (result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}); +// Delete the persistence data. +g_object.revokeSave((result) => { + console.log("revokeSave callback"); + console.log("revokeSave sessionId " + result.sessionId); +}); +``` + +Stage model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage) { + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); -g_object.revokeSave((result, data) =>{ +// Save data for persistence. +g_object.save("local", (result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}); +// Delete the persistence data. +g_object.revokeSave((result) => { console.log("revokeSave callback"); + console.log("revokeSave sessionId " + result.sessionId); }); ``` @@ -351,14 +766,266 @@ If the object is stored on another device, the data on the local device will be **Example** -```js +FA model: + +```ts +import distributedObject from '@ohos.data.distributedDataObject'; +import featureAbility from '@ohos.ability.featureAbility'; +// Obtain the context. +let context = featureAbility.getContext(); +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); +g_object.setSessionId("123456"); +// Save data for persistence. +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); +// Delete the persistence data. +g_object.revokeSave().then((result) => { + console.log("revokeSave callback"); + console.log("sessionId" + result.sessionId); +}, () => { + console.error("revokeSave failed"); +}); +``` + +Stage model: + +```ts import distributedObject from '@ohos.data.distributedDataObject'; -var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false}); +import UIAbility from '@ohos.app.ability.UIAbility'; + +// Obtain the context. +let context; +class EntryAbility extends UIAbility { + onWindowStageCreate(windowStage) { + context = this.context + } +} +let g_object = distributedObject.create(context, {name:"Amy", age:18, isVis:false}); g_object.setSessionId("123456"); -g_object.revokeSave().then((result)=>{ +g_object.save("local").then((result) => { + console.log("save callback"); + console.info("save sessionId " + result.sessionId); + console.info("save version " + result.version); + console.info("save deviceId " + result.deviceId); +}, () => { + console.error("save failed"); +}); + +// Delete the persistence data. +g_object.revokeSave().then((result) => { console.log("revokeSave callback"); console.log("sessionId" + result.sessionId); -}, ()=>{ +}, () => { console.error("revokeSave failed"); }); ``` + +## distributedObject.createDistributedObject(deprecated) + +createDistributedObject(source: object): DistributedObject + + +Creates a distributed data object. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use **distributedObject.create**. + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| source | object | Yes| Attributes of the distributed data object.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| [DistributedObject](#distributedobjectdeprecated) | Distributed data object created.| + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +// Create a distributed data object, which contains attributes of the string, number, boolean, and object types. +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +``` + +## DistributedObject(deprecated) + +Provides APIs for managing a distributed data object. + +### setSessionId(deprecated) + +setSessionId(sessionId?: string): boolean + +Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setSessionId](#setsessionid9). + +**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| sessionId | string | No| ID of a distributed data object on a trusted network. To remove a distributed data object from the network, set this parameter to "" or leave it empty.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the session ID is set successfully;
returns **false** otherwise. | + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}});; +// Add g_object to the distributed network. +g_object.setSessionId(distributedObject.genSessionId()); +// Remove g_object from the distributed network. +g_object.setSessionId(""); +``` + +### on('change')(deprecated) + +on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void + +Subscribes to data changes of this distributed data object. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('change')](#onchange9). + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type to subscribe to. The value is **change**, which indicates data changes.| +| callback | Callback<{ sessionId: string, fields: Array<string> }> | Yes| Callback invoked to return the changes of the distributed data object.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +globalThis.changeCallback = (sessionId, changeData) => { + console.info("change" + sessionId); + if (changeData != null && changeData != undefined) { + changeData.forEach(element => { + console.info("changed !" + element + " " + g_object[element]); + }); + } +} +g_object.on("change", globalThis.changeCallback); +``` + +### off('change')(deprecated) + +off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void + +Unsubscribes from the data changes of this distributed data object. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [off('change')](#offchange9). + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data changes. | +| callback | Callback<{ sessionId: string, fields: Array<string> }> | No| Callback for data changes. If this parameter is not specified, all data change callbacks of this distributed data object will be unregistered.
**sessionId** indicates the session ID of the distributed data object.
**fields** indicates the changed attributes of the distributed data object.| + + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +// Unregister the specified data change callback. +g_object.off("change", globalThis.changeCallback); +// Unregister all data change callbacks. +g_object.off("change"); +``` + +### on('status')(deprecated) + +on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void + +Subscribes to status changes of this distributed data object. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('status')](#onstatus9). + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type to subscribe to. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| +| callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | Yes| Callback invoked to return the status change.
**sessionId** indicates the session ID of the distributed data object.
**networkId** indicates the object device ID, that is, **deviceId**.
**status** indicates the object status, which can be online or offline.| + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +g_object.on("status", globalThis.statusCallback); +``` + +### off('status')(deprecated) + +off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void + +Unsubscribes from the status change of this distributed data object. + +> **NOTE** +> +> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [off('status')](#offstatus9) instead. + +**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Event type to unsubscribe from. The value is **status**, which indicates the status change (online or offline) of the distributed data object. | +| callback | Callback<{ sessionId: string, deviceId: string, status: 'online' \| 'offline' }> | No| Callback for status changes. If this parameter is not specified, all status change callbacks of this distributed data object will be unregistered.
**sessionId** indicates the session ID of the distributed data object.
**deviceId** indicates the device ID of the distributed data object.
**status** indicates the object status, which can be online or offline.| + + +**Example** + +```js +import distributedObject from '@ohos.data.distributedDataObject'; +let g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, parent:{mother:"jack mom",father:"jack Dad"}}); +globalThis.statusCallback = (sessionId, networkId, status) => { + globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; +} +// Unregister the specified status change callback. +g_object.off("status",globalThis.statusCallback); +// Unregister all status change callbacks. +g_object.off("status"); +```