1# Distributed Data Object 2 3Provides 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. 4 5> **NOTE**<br/> 6> 7> 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. 8 9 10## Modules to Import 11 12```js 13import distributedObject from '@ohos.data.distributedDataObject'; 14``` 15 16## distributedDataObject.createDistributedObject 17 18createDistributedObject(source: object): DistributedObject 19 20 21Creates a distributed data object. 22 23**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 24 25**Parameters** 26 | Name| Type| Mandatory| Description| 27 | -------- | -------- | -------- | -------- | 28 | source | object | Yes| Attribute of the distributed data object to create.| 29 30**Return value** 31| Type| Description| 32| -------- | -------- | 33| [DistributedObject](#distributedobject) | Distributed data object created.| 34 35**Example** 36 ```js 37 import distributedObject from '@ohos.data.distributedDataObject'; 38 // Create a distributed data object, which contains attributes of four types, namely, string, number, boolean, and object. 39 var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, 40 parent:{mother:"jack mom",father:"jack Dad"}}); 41 ``` 42 43 44## distributedObject.genSessionId 45 46genSessionId(): string 47 48Creates a random session ID. 49 50**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 51 52**Return value** 53 | Type| Description| 54 | -------- | -------- | 55 | string | Session ID created.| 56 57**Example** 58 ```js 59 import distributedObject from '@ohos.data.distributedDataObject'; 60 var sessionId = distributedObject.genSessionId(); 61 ``` 62 63 64## DistributedObject 65 66Represents a distributed data object. 67 68### setSessionId 69 70setSessionId(sessionId?: string): boolean 71 72Sets a session ID for synchronization. Automatic synchronization is performed for multiple devices with the same session ID on a trusted network. 73 74**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 75 76**Parameters** 77 78 | Name| Type| Mandatory| Description| 79 | -------- | -------- | -------- | -------- | 80 | 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.| 81 82**Return value** 83 84 | Type| Description| 85 | -------- | -------- | 86 | boolean | Returns **true** if the session ID is set successfully;<br>returns **false** otherwise. | 87 88**Example** 89 90 ```js 91 import distributedObject from '@ohos.data.distributedDataObject'; 92 var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false, 93 parent:{mother:"jack mom",father:"jack Dad"}}); 94 // Add g_object to the distributed network. 95 g_object.setSessionId(distributedObject.genSessionId()); 96 // Remove g_object from the distributed network. 97 g_object.setSessionId(""); 98 ``` 99 100 101### on('change') 102 103on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void 104 105Subscribes to the changes of this distributed data object. 106 107**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 108 109**Parameters** 110 | Name| Type| Mandatory| Description| 111 | -------- | -------- | -------- | -------- | 112 | type | string | Yes| Event type to subscribe to. The value is **change**, which indicates data changes.| 113 | callback | Callback<{ sessionId: string, fields: Array<string> }> | Yes| Callback used to return the changes of the distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed attributes of the distributed data object.| 114 115**Example** 116```js 117import distributedObject from '@ohos.data.distributedDataObject'; 118var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 119globalThis.changeCallback = (sessionId, changeData) => { 120 console.info("change" + sessionId); 121 if (changeData != null && changeData != undefined) { 122 changeData.forEach(element => { 123 console.info("changed !" + element + " " + g_object[element]); 124 }); 125 } 126} 127g_object.on("change", globalThis.changeCallback); 128``` 129 130### off('change') 131 132off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void 133 134Unsubscribes from the changes of this distributed data object. 135 136**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 137 138**Parameters** 139 | Name| Type| Mandatory| Description| 140 | -------- | -------- | -------- | -------- | 141 | type | string | Yes| Event type to unsubscribe from. The value is **change**, which indicates data changes.| 142 | callback | Callback<{ sessionId: string, fields: Array<string> }> | No| Callback to be unregistered. If this parameter is not specified, all data change callbacks of the object will be unregistered.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed attributes of the distributed data object.| 143 144 145**Example** 146```js 147import distributedObject from '@ohos.data.distributedDataObject'; 148var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 149// Unregister the specified data change callback. 150g_object.off("change", globalThis.changeCallback); 151// Unregister all data change callbacks. 152g_object.off("change"); 153``` 154 155### on('status') 156 157on(type: 'status', callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void 158 159Subscribes to the status change (online or offline) of this distributed data object. 160 161**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 162 163**Parameters** 164 | Name| Type| Mandatory| Description| 165 | -------- | -------- | -------- | -------- | 166 | type | string | Yes| Event type to subscribe to. The value is **status**, which indicates the change in the status (online or offline) of the distributed data object.| 167 | callback | Callback<{ sessionId: string, networkId: string, status: 'online' \| 'offline' }> | Yes| Callback used to return the status change.<br>**sessionId** indicates the session ID of the distributed data object.<br>**networkId** indicates the network ID of the device.<br>**status** indicates the status, which can be online or offline.| 168 169**Example** 170```js 171import distributedObject from '@ohos.data.distributedDataObject'; 172globalThis.statusCallback = (sessionId, networkId, status) => { 173 globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; 174} 175var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 176g_object.on("status", globalThis.statusCallback); 177``` 178 179### off('status') 180 181off(type: 'status', callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void 182 183 184Unsubscribes from the status change (online or offline) of this distributed data object. 185 186**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 187 188**Parameters** 189 | Name| Type| Mandatory| Description| 190 | -------- | -------- | -------- | -------- | 191 | type | string | Yes| Event type to unsubscribe from. The value is **status**, which indicates the change in the status (online or offline) of the distributed data object.| 192 | 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.<br>**sessionId** indicates the session ID of the distributed data object.<br>**deviceId** indicates the device ID of the distributed data object.<br>**status** indicates the status, which can be online or offline.| 193 194 195**Example** 196```js 197import distributedObject from '@ohos.data.distributedDataObject'; 198var g_object = distributedObject.createDistributedObject({name:"Amy", age:18, isVis:false,parent:{mother:"jack mom",father:"jack Dad"}}); 199globalThis.statusCallback = (sessionId, networkId, status) => { 200 globalThis.response += "status changed " + sessionId + " " + status + " " + networkId; 201} 202// Unsubscribe from the specified status change callback for the distributed data object. 203g_object.off("status",globalThis.statusCallback); 204// Unsubscribe from all status change callbacks for the distributed data object. 205g_object.off("status"); 206``` 207