1# @ohos.data.distributedDataObject (Distributed Data Object) 2 3The **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. 4 5> **NOTE** 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```ts 13import { distributedDataObject } from '@kit.ArkData'; 14``` 15 16## distributedDataObject.create<sup>9+</sup> 17 18create(context: Context, source: object): DataObject 19 20Creates a distributed data object. 21 22**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 23 24**Parameters** 25 26 | Name| Type| Mandatory| Description| 27 | -------- | -------- | -------- | -------- | 28 | context | Context | Yes| Application context.<br>For details about the application context of the FA model, see [Context](../apis-ability-kit/js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md).| 29 | source | object | Yes | Properties of the distributed data object. | 30 31**Return value** 32 33| Type| Description| 34| -------- | -------- | 35| [DataObject](#dataobject) | Distributed data object created.| 36 37**Error codes** 38 39 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 40 41 | ID| Error Message| 42 | -------- | -------- | 43 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 44 45**Example** 46 47FA model: 48<!--code_no_check_fa--> 49```ts 50// Import the module. 51import { featureAbility } from '@kit.AbilityKit'; 52import { BusinessError } from '@kit.BasicServicesKit'; 53// Obtain the context. 54let context = featureAbility.getContext(); 55class SourceObject { 56 name: string 57 age: number 58 isVis: boolean 59 60 constructor(name: string, age: number, isVis: boolean) { 61 this.name = name 62 this.age = age 63 this.isVis = isVis 64 } 65} 66 67let source: SourceObject = new SourceObject("jack", 18, false); 68let g_object: distributedDataObject.DataObject = distributedDataObject.create(context, source); 69``` 70 71Stage model: 72 73```ts 74// Import the module. 75import { UIAbility } from '@kit.AbilityKit'; 76import { BusinessError } from '@kit.BasicServicesKit'; 77import { window } from '@kit.ArkUI'; 78 79let g_object: distributedDataObject.DataObject|null = null; 80class SourceObject { 81 name: string 82 age: number 83 isVis: boolean 84 85 constructor(name: string, age: number, isVis: boolean) { 86 this.name = name 87 this.age = age 88 this.isVis = isVis 89 } 90} 91 92class EntryAbility extends UIAbility { 93 onWindowStageCreate(windowStage: window.WindowStage) { 94 let source: SourceObject = new SourceObject("jack", 18, false); 95 g_object = distributedDataObject.create(this.context, source); 96 } 97} 98``` 99 100## distributedDataObject.genSessionId 101 102genSessionId(): string 103 104Creates a random session ID. 105 106**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 107 108**Return value** 109 110 | Type| Description| 111 | -------- | -------- | 112 | string | Session ID created.| 113 114**Example** 115 116```ts 117let sessionId: string = distributedDataObject.genSessionId(); 118``` 119 120## SaveSuccessResponse<sup>9+</sup> 121 122Represents the information returned by the callback of [save](#save9). 123 124**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 125 126| Name| Type| Mandatory| Description| 127| -------- | -------- | -------- | -------- | 128| sessionId | string | Yes| Unique ID for multi-device collaboration.| 129| version | number | Yes| Version of the distributed data object saved.| 130| deviceId | string | Yes| ID of the device where the distributed data object is stored. The value **local** indicates the local device.| 131 132## RevokeSaveSuccessResponse<sup>9+</sup> 133 134Represents the information returned by the callback of [revokeSave](#revokesave9). 135 136**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 137 138| Name| Type| Mandatory| Description| 139| -------- | -------- | -------- | -------- | 140| sessionId | string | Yes| Unique ID for multi-device collaboration.| 141 142## BindInfo<sup>11+</sup> 143 144Represents the information about the joint asset in the RDB store to bind. Currently, only the RDB stores are supported. 145 146**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 147 148**Parameters** 149 | Name | Type | Read-Only| Optional| Description | 150 | ---------- | ------------------------------------------------------------------ | ---- | ---- | ------------------------------------ | 151 | storeName | string | No | No | RDB store to which the target asset (asset to bind) belongs. | 152 | tableName | string | No | No | Table to which the target asset is located in the RDB store. | 153 | primaryKey | [commonType.ValuesBucket](js-apis-data-commonType.md#valuesbucket) | No | No | Primary key of the target asset in the RDB store. | 154 | field | string | No | No | Column in which the target asset is located in the RDB store. | 155 | assetName | string | No | No | Name of the target asset in the RDB store.| 156 157## DataObject 158 159Provides APIs for managing a distributed data object. Before using any API of this class, use [create()](#distributeddataobjectcreate9) to create a **DataObject** object. 160 161### setSessionId<sup>9+</sup> 162 163setSessionId(sessionId: string, callback: AsyncCallback<void>): void 164 165Sets a session ID. This API uses an asynchronous callback to return the result. For the devices in the collaboration state in a trusted network, data of the distributed objects with the same session ID can be automatically synced across devices. 166 167**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 168 169**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 170 171**Parameters** 172 173 | Name | Type | Mandatory| Description | 174 | --------- | ------------------------- | ---- | -------------------------------------------------------------------------------------------------------------- | 175 | sessionId | string | Yes | ID of a distributed data object on a trusted network. The value can contain only letters, digits, and underscores (_), and cannot exceed 128 characters. If this parameter is set to "", the distributed data object exits the network.| 176 | callback | AsyncCallback<void> | Yes | Asynchronous callback invoked when the session ID is successfully set. | 177 178**Error codes** 179 180 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Distributed Data Object Error Codes](errorcode-distributed-dataObject.md). 181 182 | ID| Error Message | 183 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 184 | 201 | Permission verification failed. | 185 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 186 | 15400001 | Failed to create the in-memory database. | 187 188**Example** 189 190```ts 191// Add g_object to the distributed network. 192g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 193 console.info("join session"); 194}); 195// g_object exits the distributed network. 196g_object.setSessionId("", ()=>{ 197 console.info("leave all session"); 198}); 199``` 200 201### setSessionId<sup>9+</sup> 202 203setSessionId(callback: AsyncCallback<void>): void 204 205Exits all sessions. This API uses an asynchronous callback to return the result. 206 207**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 208 209**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 210 211**Parameters** 212 213 | Name| Type| Mandatory| Description| 214 | -------- | -------- | -------- | -------- | 215 | callback | AsyncCallback<void> | Yes| Callback invoked when the distributed data object exits all sessions.| 216 217**Error codes** 218 219 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Distributed Data Object Error Codes](errorcode-distributed-dataObject.md). 220 221 | ID| Error Message| 222 | -------- | -------- | 223 | 201 | Permission verification failed. | 224 | 401 | Parameter error. Incorrect parameter types. | 225 | 15400001 | Failed to create the in-memory database. | 226 227**Example** 228 229```ts 230// Add g_object to the distributed network. 231g_object.setSessionId(distributedDataObject.genSessionId(), ()=>{ 232 console.info("join session"); 233}); 234// Exit the distributed network. 235g_object.setSessionId(() => { 236 console.info("leave all session."); 237}); 238``` 239 240### setSessionId<sup>9+</sup> 241 242setSessionId(sessionId?: string): Promise<void> 243 244Sets a session ID. This API uses a promise to return the result. For the devices in the collaboration state in a trusted network, data of the distributed objects with the same session ID can be automatically synced across devices. 245 246**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 247 248**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 249 250**Parameters** 251 252 | Name | Type | Mandatory| Description | 253 | --------- | ------ | ---- | ---------------------------------------------------------------------------------------------------------------------------- | 254 | sessionId | string | No | ID of a distributed data object on a trusted network. The value can contain only letters, digits, and underscores (_), and cannot exceed 128 characters. To remove a distributed data object from the network, set this parameter to "" or leave it empty.| 255 256**Return value** 257 258| Type| Description| 259| -------- | -------- | 260| Promise<void> | Promise that returns no value.| 261 262**Error codes** 263 264 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Distributed Data Object Error Codes](errorcode-distributed-dataObject.md). 265 266 | ID| Error Message | 267 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 268 | 201 | Permission verification failed. | 269 | 401 | Parameter error. Possible causes: 1. Incorrect parameter types; 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. | 270 | 15400001 | Failed to create the in-memory database. | 271 272**Example** 273 274```ts 275// Add g_object to the distributed network. 276g_object.setSessionId(distributedDataObject.genSessionId()).then (()=>{ 277 console.info("join session."); 278 }).catch((error: BusinessError)=>{ 279 console.info("error:" + error.code + error.message); 280}); 281// Exit the distributed network. 282g_object.setSessionId().then (()=>{ 283 console.info("leave all session."); 284 }).catch((error: BusinessError)=>{ 285 console.info("error:" + error.code + error.message); 286}); 287``` 288 289### on('change')<sup>9+</sup> 290 291on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 292 293Subscribes to data changes of this distributed data object. 294 295**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 296 297**Parameters** 298 299| Name| Type| Mandatory| Description| 300| -------- | -------- | -------- | -------- | 301| type | string | Yes| Event type. The value is **change**, which indicates data changes.| 302| callback | Function | 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 properties of the distributed data object. | 303 304**Error codes** 305 306 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 307 308 | ID| Error Message| 309 | -------- | -------- | 310 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 311 312**Example** 313 314```ts 315g_object.on("change", (sessionId: string, fields: Array<string>) => { 316 console.info("change" + sessionId); 317 if (g_object != null && fields != null && fields != undefined) { 318 for (let index: number = 0; index < fields.length; index++) { 319 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 320 } 321 } 322}); 323``` 324 325### off('change')<sup>9+</sup> 326 327off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 328 329Unsubscribes from the data changes of this distributed data object. 330 331**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 332 333**Parameters** 334 335| Name| Type| Mandatory| Description| 336| -------- | -------- | -------- | -------- | 337| type | string | Yes| Event type. The value is **change**, which indicates data changes.| 338| callback | Function | No | Callback to unregister. If this parameter is not specified, this API unregisters all data change callbacks of this distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed properties of the distributed data object. | 339 340**Error codes** 341 342 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 343 344 | ID| Error Message| 345 | -------- | -------- | 346 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 347 348**Example** 349 350```ts 351// Unregister the specified data change callback. 352g_object.off("change", (sessionId: string, fields: Array<string>) => { 353 console.info("change" + sessionId); 354 if (g_object != null && fields != null && fields != undefined) { 355 for (let index: number = 0; index < fields.length; index++) { 356 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 357 } 358 } 359}); 360// Unregister all data change callbacks. 361g_object.off("change"); 362``` 363 364### on('status')<sup>9+</sup> 365 366on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' \| 'offline' ) => void): void 367 368Subscribes to status changes of this distributed data object. 369 370**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 371 372**Parameters** 373 374| Name| Type| Mandatory| Description| 375| -------- | -------- | -------- | -------- | 376| type | string | Yes| Event type. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| 377| callback | Function | Yes| Callback used to return the status change.<br>**sessionId** indicates the session ID of the distributed data object.<br>**networkId** identifies the device.<br>**status** indicates the object status, which can be online or offline.| 378 379**Error codes** 380 381 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 382 383 | ID| Error Message| 384 | -------- | -------- | 385 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 386 387**Example** 388 389```ts 390g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 391 console.info("status changed " + sessionId + " " + status + " " + networkId); 392}); 393``` 394 395### off('status')<sup>9+</sup> 396 397off(type: 'status', callback?:(sessionId: string, networkId: string, status: 'online' \| 'offline') => void): void 398 399Unsubscribes from the status change of this distributed data object. 400 401**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 402 403**Parameters** 404 405| Name| Type| Mandatory| Description| 406| -------- | -------- | -------- | -------- | 407| type | string | Yes| Event type. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| 408| callback | Function | No| Callback to unregister. If this parameter is not specified, this API unregisters all status change callbacks of this distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**networkId** identifies the distributed data object.<br>**status** indicates the object status, which can be online or offline.| 409 410**Error codes** 411 412 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 413 414 | ID| Error Message| 415 | -------- | -------- | 416 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 417 418**Example** 419 420```ts 421// Unregister the specified status change callback. 422g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 423 console.info("status changed " + sessionId + " " + status + " " + networkId); 424}); 425// Unregister all status change callbacks. 426g_object.off("status"); 427``` 428 429### save<sup>9+</sup> 430 431save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void 432 433Saves a distributed data object. This API uses an asynchronous callback to return the result. 434 435If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored. 436 437The saved data will be released in the following cases: 438 439- The data is stored for more than 24 hours. 440- The application has been uninstalled. 441- Data is successfully restored. 442 443**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 444 445**Parameters** 446 447 | Name| Type| Mandatory| Description| 448 | -------- | -------- | -------- | -------- | 449 | deviceId | string | Yes| ID of the device where data is stored. The value **local** indicates a local device.| 450 | callback | AsyncCallback<[SaveSuccessResponse](#savesuccessresponse9)> | Yes| Callback used to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.| 451 452**Error codes** 453 454 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 455 456 | ID| Error Message| 457 | -------- | -------- | 458 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 459 | 801 | Capability not supported. | 460 461**Example** 462 463```ts 464g_object.setSessionId("123456"); 465g_object.save("local", (err: BusinessError, result:distributedDataObject.SaveSuccessResponse) => { 466 if (err) { 467 console.info("save failed, error code = " + err.code); 468 console.info("save failed, error message: " + err.message); 469 return; 470 } 471 console.info("save callback"); 472 console.info("save sessionId: " + result.sessionId); 473 console.info("save version: " + result.version); 474 console.info("save deviceId: " + result.deviceId); 475}); 476``` 477 478### save<sup>9+</sup> 479 480save(deviceId: string): Promise<SaveSuccessResponse> 481 482Saves a distributed data object. This API uses a promise to return the result. 483 484If the application is active, the saved data will not be released. When the application exits and restarts, the data saved on the device will be restored. 485 486The saved data will be released in the following cases: 487 488- The data is stored for more than 24 hours. 489- The application has been uninstalled. 490- Data is successfully restored. 491 492**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 493 494**Parameters** 495 496 | Name| Type| Mandatory| Description| 497 | -------- | -------- | -------- | -------- | 498 | deviceId | string | Yes| ID of the device where the data is saved. The default value is **local**, which indicates a local device. | 499 500**Return value** 501 502 | Type| Description| 503 | -------- | -------- | 504 | Promise<[SaveSuccessResponse](#savesuccessresponse9)> | Promise used to return **SaveSuccessResponse**, which contains information such as session ID, version, and device ID.| 505 506**Error codes** 507 508 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 509 510 | ID| Error Message| 511 | -------- | -------- | 512 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 513 | 801 | Capability not supported. | 514 515**Example** 516 517```ts 518g_object.setSessionId("123456"); 519g_object.save("local").then((result: distributedDataObject.SaveSuccessResponse) => { 520 console.info("save callback"); 521 console.info("save sessionId " + result.sessionId); 522 console.info("save version " + result.version); 523 console.info("save deviceId " + result.deviceId); 524}).catch((err: BusinessError) => { 525 console.info("save failed, error code = " + err.code); 526 console.info("save failed, error message: " + err.message); 527}); 528``` 529 530### revokeSave<sup>9+</sup> 531 532revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void 533 534Revokes the data of this distributed data object saved. This API uses an asynchronous callback to return the result. 535 536If the object is saved on the local device, the data saved on all trusted devices will be deleted. 537If the object is stored on another device, the data on the local device will be deleted. 538 539**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 540 541**Parameters** 542 543 | Name| Type| Mandatory| Description| 544 | -------- | -------- | -------- | -------- | 545 | callback | AsyncCallback<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | Yes| Callback used to return **RevokeSaveSuccessResponse**, which contains the session ID.| 546 547**Error codes** 548 549 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 550 551 | ID| Error Message| 552 | -------- | -------- | 553 | 401 | Parameter error. Incorrect parameter types. | 554 | 801 | Capability not supported. | 555 556**Example** 557 558```ts 559g_object.setSessionId("123456"); 560// Save data for persistence. 561g_object.save("local", (err: BusinessError, result: distributedDataObject.SaveSuccessResponse) => { 562 if (err) { 563 console.info("save failed, error code = " + err.code); 564 console.info("save failed, error message: " + err.message); 565 return; 566 } 567 console.info("save callback"); 568 console.info("save sessionId: " + result.sessionId); 569 console.info("save version: " + result.version); 570 console.info("save deviceId: " + result.deviceId); 571}); 572// Delete the persistence data. 573g_object.revokeSave((err: BusinessError, result: distributedDataObject.RevokeSaveSuccessResponse) => { 574 if (err) { 575 console.info("revokeSave failed, error code = " + err.code); 576 console.info("revokeSave failed, error message: " + err.message); 577 return; 578 } 579 console.info("revokeSave callback"); 580 console.info("revokeSave sessionId " + result.sessionId); 581}); 582``` 583 584### revokeSave<sup>9+</sup> 585 586revokeSave(): Promise<RevokeSaveSuccessResponse> 587 588Revokes the data of this distributed data object saved. This API uses a promise to return the result. 589 590If the object is saved on the local device, the data saved on all trusted devices will be deleted. 591If the object is stored on another device, the data on the local device will be deleted. 592 593**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 594 595**Return value** 596 597 | Type| Description| 598 | -------- | -------- | 599 | Promise<[RevokeSaveSuccessResponse](#revokesavesuccessresponse9)> | Promise used to return **RevokeSaveSuccessResponse**, which contains the session ID.| 600 601**Error codes** 602 603 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 604 605 | ID| Error Message| 606 | -------- | -------- | 607 | 801 | Capability not supported. | 608 609**Example** 610 611```ts 612g_object.setSessionId("123456"); 613// Save data for persistence. 614g_object.save("local").then((result: distributedDataObject.SaveSuccessResponse) => { 615 console.info("save callback"); 616 console.info("save sessionId " + result.sessionId); 617 console.info("save version " + result.version); 618 console.info("save deviceId " + result.deviceId); 619}).catch((err: BusinessError) => { 620 console.info("save failed, error code = " + err.code); 621 console.info("save failed, error message: " + err.message); 622}); 623// Delete the persistence data. 624g_object.revokeSave().then((result: distributedDataObject.RevokeSaveSuccessResponse) => { 625 console.info("revokeSave callback"); 626 console.info("sessionId" + result.sessionId); 627}).catch((err: BusinessError)=> { 628 console.info("revokeSave failed, error code = " + err.code); 629 console.info("revokeSave failed, error message = " + err.message); 630}); 631``` 632 633### bindAssetStore<sup>11+</sup> 634 635bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback<void>): void 636 637Binds joint assets. Currently, only the binding between an asset in a distributed data object and an asset in an RDB store is supported. This API uses an asynchronous callback to return the result. 638 639When an asset in a distributed object and an asset in an RDB store point to the same entity asset file, that is, the URIs of the two assets are the same, a conflict occurs. Such assets are called joint assets. To resolve the conflict, bind the joint assets. The binding is automatically released when the application exits the session. 640 641**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 642 643**Parameters** 644 645 | Name | Type | Mandatory| Description | 646 | -------- | ------------------------- | ---- | ---------------------------------------------------------------------------------- | 647 | assetKey | string | Yes | Key of the joint asset in the distributed data object. | 648 | bindInfo | [BindInfo](#bindinfo11) | Yes | Information about the joint asset in the RDB store, including the RDB store name, table name, primary key, column name, and asset name in the RDB store.| 649 | callback | AsyncCallback<void> | Yes | Callback used to return the result. | 650 651**Error codes** 652 653 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 654 655 | ID| Error Message| 656 | -------- | -------- | 657 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 658 | 801 | Capability not supported. | 659 660**Example** 661 662```ts 663import { UIAbility } from '@kit.AbilityKit'; 664import { window } from '@kit.ArkUI'; 665import { commonType } from '@kit.ArkData'; 666import { BusinessError } from '@kit.BasicServicesKit'; 667 668class Note { 669 title: string | undefined 670 text: string | undefined 671 attachment: commonType.Asset | undefined 672 673 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 674 this.title = title; 675 this.text = text; 676 this.attachment = attachment; 677 } 678} 679 680class EntryAbility extends UIAbility { 681 onWindowStageCreate(windowStage: window.WindowStage) { 682 let attachment: commonType.Asset = { 683 name: 'test_img.jpg', 684 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 685 path: '/dir/test_img.jpg', 686 createTime: '2024-01-02 10:00:00', 687 modifyTime: '2024-01-02 10:00:00', 688 size: '5', 689 status: commonType.AssetStatus.ASSET_NORMAL 690 } 691 let note: Note = new Note('test', 'test', attachment); 692 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 693 g_object.setSessionId('123456'); 694 695 const bindInfo: distributedDataObject.BindInfo = { 696 storeName: 'notepad', 697 tableName: 'note_t', 698 primaryKey: { 699 'uuid': '00000000-0000-0000-0000-000000000000' 700 }, 701 field: 'attachment', 702 assetName: attachment.name as string 703 } 704 705 g_object.bindAssetStore('attachment', bindInfo, (err: BusinessError) => { 706 if (err) { 707 console.error('bindAssetStore failed.'); 708 } 709 console.info('bindAssetStore success.'); 710 }); 711 } 712} 713``` 714 715### bindAssetStore<sup>11+</sup> 716 717bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise<void> 718 719Binds joint assets. Currently, only the binding between an asset in a distributed data object and an asset in an RDB store is supported. This API uses a promise to return the result. 720 721When an asset in a distributed object and an asset in an RDB store point to the same entity asset file, that is, the URIs of the two assets are the same, a conflict occurs. Such assets are called joint assets. To resolve the conflict, bind the joint assets. The binding is automatically released when the application exits the session. 722 723**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 724 725**Parameters** 726 727 | Name | Type | Mandatory| Description | 728 | -------- | ----------------------- | ---- | ---------------------------------------------------------------------------------- | 729 | assetKey | string | Yes | Key of the joint asset in the distributed data object. | 730 | bindInfo | [BindInfo](#bindinfo11) | Yes | Information about the joint asset in the RDB store, including the RDB store name, table name, primary key, column name, and asset name in the RDB store.| 731 732**Return value** 733 734 | Type | Description | 735 | ------------------- | ------------- | 736 | Promise<void> | Promise that returns no value.| 737 738**Error codes** 739 740 For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 741 742 | ID| Error Message| 743 | -------- | -------- | 744 | 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 745 | 801 | Capability not supported. | 746 747**Example** 748 749```ts 750import { UIAbility } from '@kit.AbilityKit'; 751import { window } from '@kit.ArkUI'; 752import { commonType } from '@kit.ArkData'; 753import { BusinessError } from '@kit.BasicServicesKit'; 754 755class Note { 756 title: string | undefined 757 text: string | undefined 758 attachment: commonType.Asset | undefined 759 760 constructor(title: string | undefined, text: string | undefined, attachment: commonType.Asset | undefined) { 761 this.title = title; 762 this.text = text; 763 this.attachment = attachment; 764 } 765} 766 767class EntryAbility extends UIAbility { 768 onWindowStageCreate(windowStage: window.WindowStage) { 769 let attachment: commonType.Asset = { 770 name: 'test_img.jpg', 771 uri: 'file://com.example.myapplication/data/storage/el2/distributedfiles/dir/test_img.jpg', 772 path: '/dir/test_img.jpg', 773 createTime: '2024-01-02 10:00:00', 774 modifyTime: '2024-01-02 10:00:00', 775 size: '5', 776 status: commonType.AssetStatus.ASSET_NORMAL 777 } 778 let note: Note = new Note('test', 'test', attachment); 779 let g_object: distributedDataObject.DataObject = distributedDataObject.create(this.context, note); 780 g_object.setSessionId('123456'); 781 782 const bindInfo: distributedDataObject.BindInfo = { 783 storeName: 'notepad', 784 tableName: 'note_t', 785 primaryKey: { 786 'uuid': '00000000-0000-0000-0000-000000000000' 787 }, 788 field: 'attachment', 789 assetName: attachment.name as string 790 } 791 792 g_object.bindAssetStore("attachment", bindInfo).then(() => { 793 console.info('bindAssetStore success.'); 794 }).catch((err: BusinessError) => { 795 console.error("bindAssetStore failed, error code = " + err.code); 796 }); 797 } 798} 799``` 800 801## distributedDataObject.createDistributedObject<sup>(deprecated)</sup> 802 803createDistributedObject(source: object): DistributedObject 804 805 806Creates a distributed data object. 807 808> **NOTE** 809> 810> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [distributedDataObject.create](#distributeddataobjectcreate9). 811 812**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 813 814**Parameters** 815 816 | Name| Type| Mandatory| Description| 817 | -------- | -------- | -------- | -------- | 818 | source | object | Yes | Properties of the distributed data object. | 819 820**Return value** 821 822| Type| Description| 823| -------- | -------- | 824| [DistributedObject](#distributedobjectdeprecated) | Distributed data object created.| 825 826**Example** 827 828```ts 829class SourceObject { 830 name: string 831 age: number 832 isVis: boolean 833 834 constructor(name: string, age: number, isVis: boolean) { 835 this.name = name 836 this.age = age 837 this.isVis = isVis 838 } 839} 840 841let source: SourceObject = new SourceObject("jack", 18, false); 842let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 843``` 844 845## DistributedObject<sup>(deprecated)</sup> 846 847Provides APIs for managing a distributed data object. Before using any API of this class, use [createDistributedObject()](#distributeddataobjectcreatedistributedobjectdeprecated) to create a **DistributedObject** object. 848 849### setSessionId<sup>(deprecated)</sup> 850 851setSessionId(sessionId?: string): boolean 852 853Sets a session ID. For the devices in the collaboration state in a trusted network, data of the distributed objects with the same session ID can be automatically synced across devices. 854 855> **NOTE** 856> 857> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [setSessionId](#setsessionid9). 858 859**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC 860 861**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 862 863**Parameters** 864 865 | Name| Type| Mandatory| Description| 866 | -------- | -------- | -------- | -------- | 867 | 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.| 868 869**Return value** 870 871 | Type| Description| 872 | -------- | -------- | 873 | boolean | Returns **true** if the session ID is set successfully;<br>returns **false** otherwise. | 874 875**Example** 876 877```ts 878class SourceObject { 879 name: string 880 age: number 881 isVis: boolean 882 883 constructor(name: string, age: number, isVis: boolean) { 884 this.name = name 885 this.age = age 886 this.isVis = isVis 887 } 888} 889 890let source: SourceObject = new SourceObject("jack", 18, false); 891let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 892// Add g_object to the distributed network. 893g_object.setSessionId(distributedDataObject.genSessionId()); 894// Remove g_object from the distributed network. 895g_object.setSessionId(""); 896``` 897 898### on('change')<sup>(deprecated)</sup> 899 900on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void 901 902Subscribes to data changes of this distributed data object. 903 904> **NOTE** 905> 906> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('change')](#onchange9). 907 908**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 909 910**Parameters** 911 912| Name| Type| Mandatory| Description| 913| -------- | -------- | -------- | -------- | 914| type | string | Yes| Event type. The value is **change**, which indicates data changes.| 915| callback | Function | 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 properties of the distributed data object. | 916 917**Example** 918 919```ts 920class SourceObject { 921 name: string 922 age: number 923 isVis: boolean 924 925 constructor(name: string, age: number, isVis: boolean) { 926 this.name = name 927 this.age = age 928 this.isVis = isVis 929 } 930} 931 932let source: SourceObject = new SourceObject("jack", 18, false); 933let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 934g_object.on("change", (sessionId: string, fields: Array<string>) => { 935 console.info("change" + sessionId); 936 if (fields != null && fields != undefined) { 937 for (let index: number = 0; index < fields.length; index++) { 938 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 939 } 940 } 941}); 942``` 943 944### off('change')<sup>(deprecated)</sup> 945 946off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void 947 948Unsubscribes from the data changes of this distributed data object. 949 950> **NOTE** 951> 952> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [off('change')](#offchange9). 953 954**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 955 956**Parameters** 957 958| Name| Type| Mandatory| Description| 959| -------- | -------- | -------- | -------- | 960| type | string | Yes| Event type. The value is **change**, which indicates data changes.| 961| callback | Function | No | Callback to unregister. If this parameter is not specified, this API unregisters all data change callbacks of this distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**fields** indicates the changed properties of the distributed data object. | 962 963**Example** 964 965```ts 966class SourceObject { 967 name: string 968 age: number 969 isVis: boolean 970 971 constructor(name: string, age: number, isVis: boolean) { 972 this.name = name 973 this.age = age 974 this.isVis = isVis 975 } 976} 977 978let source: SourceObject = new SourceObject("jack", 18, false); 979let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 980// Unregister the specified data change callback. 981g_object.off("change", (sessionId: string, fields: Array<string>) => { 982 console.info("change" + sessionId); 983 if (fields != null && fields != undefined) { 984 for (let index: number = 0; index < fields.length; index++) { 985 console.info("changed !" + fields[index] + " " + g_object[fields[index]]); 986 } 987 } 988}); 989// Unregister all data change callbacks. 990g_object.off("change"); 991``` 992 993### on('status')<sup>(deprecated)</sup> 994 995on(type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 996 997Subscribes to status changes of this distributed data object. 998 999> **NOTE** 1000> 1001> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('status')](#onstatus9). 1002 1003**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 1004 1005**Parameters** 1006 1007| Name| Type| Mandatory| Description| 1008| -------- | -------- | -------- | -------- | 1009| type | string | Yes| Event type. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| 1010| callback | Function | Yes| Callback used to return the status change.<br>**sessionId** indicates the session ID of the distributed data object.<br>**networkId** identifies the device.<br>**status** indicates the object status, which can be online or offline.| 1011 1012**Example** 1013 1014```ts 1015class SourceObject { 1016 name: string 1017 age: number 1018 isVis: boolean 1019 1020 constructor(name: string, age: number, isVis: boolean) { 1021 this.name = name 1022 this.age = age 1023 this.isVis = isVis 1024 } 1025} 1026 1027let source: SourceObject = new SourceObject("jack", 18, false); 1028let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1029 1030g_object.on("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1031 console.info("status changed " + sessionId + " " + status + " " + networkId); 1032}); 1033``` 1034 1035### off('status')<sup>(deprecated)</sup> 1036 1037off(type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void): void 1038 1039Unsubscribes from the status change of this distributed data object. 1040 1041> **NOTE** 1042> 1043> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [off('status')](#offstatus9). 1044 1045**System capability**: SystemCapability.DistributedDataManager.DataObject.DistributedObject 1046 1047**Parameters** 1048 1049| Name| Type| Mandatory| Description| 1050| -------- | -------- | -------- | -------- | 1051| type | string | Yes| Event type. The value is **status**, which indicates the status change (online or offline) of the distributed data object.| 1052| callback | Function | No| Callback to unregister. If this parameter is not specified, this API unregisters all status change callbacks of this distributed data object.<br>**sessionId** indicates the session ID of the distributed data object.<br>**networkId** identifies the distributed data object.<br>**status** indicates the object status, which can be online or offline.| 1053 1054 1055**Example** 1056 1057```ts 1058class SourceObject { 1059 name: string 1060 age: number 1061 isVis: boolean 1062 1063 constructor(name: string, age: number, isVis: boolean) { 1064 this.name = name 1065 this.age = age 1066 this.isVis = isVis 1067 } 1068} 1069 1070let source: SourceObject = new SourceObject("jack", 18, false); 1071let g_object: distributedDataObject.DistributedObject = distributedDataObject.createDistributedObject(source); 1072// Unregister the specified status change callback. 1073g_object.off("status", (sessionId: string, networkId: string, status: 'online' | 'offline') => { 1074 console.info("status changed " + sessionId + " " + status + " " + networkId); 1075}); 1076// Unregister all status change callbacks. 1077g_object.off("status"); 1078``` 1079
