1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit ArkData 19 */ 20 21import { AsyncCallback, Callback } from './@ohos.base'; 22import type Context from './application/BaseContext'; 23import commonType from '@ohos.data.commonType'; 24 25/** 26 * Provides interfaces to sync distributed object. 27 * 28 * @namespace distributedDataObject 29 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 30 * @since 8 31 */ 32declare namespace distributedDataObject { 33 /** 34 * The information about the database bound to the asset. 35 * 36 * @interface BindInfo 37 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 38 * @since 11 39 */ 40 interface BindInfo { 41 /** 42 * The name of store where the asset resides. 43 * 44 * @type { string } 45 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 46 * @since 11 47 */ 48 storeName: string; 49 50 /** 51 * The name of table where the asset resides. 52 * 53 * @type { string } 54 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 55 * @since 11 56 */ 57 tableName: string; 58 59 /** 60 * The Primary key of the rdb table where the asset resides. 61 * 62 * @type { commonType.ValuesBucket } 63 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 64 * @since 11 65 */ 66 primaryKey: commonType.ValuesBucket; 67 68 /** 69 * The field(column) name of the rdb table where the asset resides. 70 * 71 * @type { string } 72 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 73 * @since 11 74 */ 75 field: string; 76 77 /** 78 * Name of the asset to be bound. When the column type is Assets, this field refers to the asset name of 79 * one of the assets. 80 * 81 * @type { string } 82 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 83 * @since 11 84 */ 85 assetName: string; 86 } 87 88 /** 89 * Create distributed object. 90 * 91 * @param { object } source - Source Init data of distributed object. 92 * @returns { DistributedObject } - Return the distributed object. 93 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 94 * @since 8 95 * @deprecated since 9 96 * @useinstead ohos.distributedDataObject.create 97 */ 98 function createDistributedObject(source: object): DistributedObject; 99 100 /** 101 * Create distributed object. 102 * 103 * @param { Context } context - Indicates the application context. 104 * @param { object } source - Source Init data of distributed object. 105 * @returns { DataObject } - Return the distributed object. 106 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 107 * 2. Incorrect parameter types. 108 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 109 * @since 9 110 */ 111 function create(context: Context, source: object): DataObject; 112 113 /** 114 * Generate a random sessionId. 115 * 116 * @returns { string } - Return generated sessionId. 117 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 118 * @since 8 119 */ 120 function genSessionId(): string; 121 122 /** 123 * The response of save. 124 * Contains the parameter information of the save object. 125 * 126 * @interface SaveSuccessResponse 127 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 128 * @since 9 129 */ 130 interface SaveSuccessResponse { 131 /** 132 * sessionId of saved object 133 * 134 * @type { string } 135 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 136 * @since 9 137 */ 138 sessionId: string; 139 140 /** 141 * version of saved object, can compare with DistributedObject.__version 142 * 143 * @type { number } 144 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 145 * @since 9 146 */ 147 version: number; 148 149 /** 150 * deviceid that data saved 151 * data is "local", means save in local device 152 * otherwise, means the deviceId of others device 153 * 154 * @type { string } 155 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 156 * @since 9 157 */ 158 deviceId: string; 159 } 160 161 /** 162 * The response of revokeSave. 163 * Contains the sessionId of the changed object. 164 * 165 * @interface RevokeSaveSuccessResponse 166 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 167 * @since 9 168 */ 169 interface RevokeSaveSuccessResponse { 170 /** 171 * The sessionId of the changed object. 172 * 173 * @type { string } 174 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 175 * @since 9 176 */ 177 sessionId: string; 178 } 179 180 /** 181 * Object create by {@link createDistributedObject}. 182 * 183 * @interface DistributedObject 184 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 185 * @since 8 186 * @deprecated since 9 187 * @useinstead ohos.distributedDataObject.DataObject 188 */ 189 interface DistributedObject { 190 /** 191 * Change object session 192 * 193 * @permission ohos.permission.DISTRIBUTED_DATASYNC 194 * @param { string } sessionId - sessionId The sessionId to be joined, if empty, leave all session. 195 * @returns { boolean } - Return a result of function. 196 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 197 * @since 8 198 * @deprecated since 9 199 * @useinstead ohos.distributedDataObject.DataObject.setSessionId 200 */ 201 setSessionId(sessionId?: string): boolean; 202 203 /** 204 * On watch of change 205 * 206 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 207 * @param { Function } callback 208 * Indicates the observer of object data changed. 209 * {string} sessionId - The sessionId of the changed object. 210 * {Array<string>} fields - Attribute names of changed data. 211 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 212 * @since 8 213 * @deprecated since 9 214 * @useinstead ohos.distributedDataObject.DataObject.on 215 */ 216 on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void; 217 218 /** 219 * Off watch of change 220 * 221 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 222 * @param { Function } callback 223 * Indicates the observer of object data changed. 224 * {string} sessionId - The sessionId of the changed object. 225 * {Array<string>} fields - Attribute names of changed data. 226 * callback If not null, off the callback, if undefined, off all callbacks. 227 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 228 * @since 8 229 * @deprecated since 9 230 * @useinstead ohos.distributedDataObject.DataObject.off 231 */ 232 off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void; 233 234 /** 235 * On watch of status 236 * 237 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 238 * @param { Function } callback 239 * Indicates the observer of object status changed. 240 * {string} sessionId - The sessionId of the changed object. 241 * {string} networkId - NetworkId of the changed device. 242 * {string} status 243 * 'online' The object became online on the device and data can be synced to the device. 244 * 'offline' The object became offline on the device and the object can not sync any data. 245 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 246 * @since 8 247 * @deprecated since 9 248 * @useinstead ohos.distributedDataObject.DataObject.on 249 */ 250 on( 251 type: 'status', 252 callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 253 ): void; 254 255 /** 256 * Off watch of status 257 * 258 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 259 * @param { Function } callback 260 * Indicates the observer of object status changed. 261 * {string} sessionId - The sessionId of the changed object. 262 * {string} networkId - NetworkId of the changed device. 263 * {string} status 264 * 'online' The object became online on the device and data can be synced to the device. 265 * 'offline' The object became offline on the device and the object can not sync any data. 266 * callback If not null, off the callback, if undefined, off all callbacks. 267 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 268 * @since 8 269 * @deprecated since 9 270 * @useinstead ohos.distributedDataObject.DataObject.off 271 */ 272 off( 273 type: 'status', 274 callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 275 ): void; 276 } 277 278 /** 279 * Object create by {@link create}. 280 * 281 * @interface DataObject 282 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 283 * @since 9 284 */ 285 interface DataObject { 286 /** 287 * Change object session. 288 * 289 * @permission ohos.permission.DISTRIBUTED_DATASYNC 290 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 291 * @param {AsyncCallback<void>} callback - The callback of setSessionId. 292 * @throws {BusinessError} 201 - Permission verification failed. 293 * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. 294 * @throws {BusinessError} 15400001 - Failed to create the in-memory database. 295 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 296 * @since 9 297 */ 298 /** 299 * Change object session. 300 * 301 * @permission ohos.permission.DISTRIBUTED_DATASYNC 302 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 303 * @param {AsyncCallback<void>} callback - The callback of setSessionId. 304 * @throws {BusinessError} 201 - Permission verification failed. 305 * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 306 * 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. 307 * @throws {BusinessError} 15400001 - Failed to create the in-memory database. 308 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 309 * @since 12 310 */ 311 setSessionId(sessionId: string, callback: AsyncCallback<void>): void; 312 313 /** 314 * Leave all session. 315 * 316 * @permission ohos.permission.DISTRIBUTED_DATASYNC 317 * @param {AsyncCallback<void>} callback - The callback of setSessionId. 318 * @throws {BusinessError} 201 - Permission verification failed. 319 * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. 320 * @throws {BusinessError} 15400001 - Failed to create the in-memory database. 321 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 322 * @since 9 323 */ 324 setSessionId(callback: AsyncCallback<void>): void; 325 326 /** 327 * Change object session. 328 * 329 * @permission ohos.permission.DISTRIBUTED_DATASYNC 330 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 331 * @returns {Promise<void>} - The promise returned by the function. 332 * @throws {BusinessError} 201 - Permission verification failed. 333 * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. 334 * @throws {BusinessError} 15400001 - Failed to create the in-memory database. 335 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 336 * @since 9 337 */ 338 /** 339 * Change object session. 340 * 341 * @permission ohos.permission.DISTRIBUTED_DATASYNC 342 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 343 * @returns {Promise<void>} - The promise returned by the function. 344 * @throws {BusinessError} 201 - Permission verification failed. 345 * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Incorrect parameter types; 346 * 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. 347 * @throws {BusinessError} 15400001 - Failed to create the in-memory database. 348 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 349 * @since 12 350 */ 351 setSessionId(sessionId?: string): Promise<void>; 352 353 /** 354 * On watch of change. 355 * 356 * @param { 'change' } type - event type, fixed as 'change', indicates data change. 357 * @param { Function } callback 358 * indicates the observer of object data changed. 359 * {string} sessionId - the sessionId of the changed object. 360 * {Array<string>} fields - Attribute names of changed data. 361 * sessionId The sessionId of the changed object. 362 * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 363 * 2. Incorrect parameter types. 364 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 365 * @since 9 366 */ 367 on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void ): void; 368 369 /** 370 * Off watch of change. 371 * 372 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 373 * @param { Function } callback 374 * indicates the observer of object data changed. 375 * {string} sessionId - The sessionId of the changed object. 376 * {Array<string>} fields - Attribute names of changed data. 377 * callback If not null, off the callback, if undefined, off all callbacks. 378 * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 379 * 2. Incorrect parameter types. 380 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 381 * @since 9 382 */ 383 off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void ): void; 384 385 /** 386 * On watch of status. 387 * 388 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 389 * @param { Function } callback 390 * indicates the observer of object status changed. 391 * {string} sessionId - The sessionId of the changed object. 392 * {string} networkId - NetworkId of the changed device. 393 * {string} status 394 * 'online' The object became online on the device and data can be synced to the device. 395 * 'offline' The object became offline on the device and the object can not sync any data. 396 * 'restored' The object restored success. 397 * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 398 * 2. Incorrect parameter types. 399 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 400 * @since 9 401 */ 402 on( 403 type: 'status', 404 callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 405 ): void; 406 407 /** 408 * Off watch of status. 409 * 410 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 411 * @param { Function } callback 412 * Indicates the observer of object status changed. 413 * {string} sessionId - The sessionId of the changed object. 414 * {string} networkId - NetworkId of the changed device. 415 * {string} status 416 * 'online' The object became online on the device and data can be synced to the device. 417 * 'offline' The object became offline on the device and the object can not sync any data. 418 * callback If not null, off the callback, if undefined, off all callbacks. 419 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 420 * 2. Incorrect parameter types. 421 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 422 * @since 9 423 */ 424 off( 425 type: 'status', 426 callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 427 ): void; 428 429 /** 430 * Save object, after save object data successfully, the object data will not release when app existed, 431 * and resume data on saved device after app existed. 432 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 433 * you should encrypt it 434 * The saved data will be released when 435 * 1. saved after 24h. 436 * 2. app uninstalled. 437 * 3. after resume data success, system will auto delete the saved data. 438 * 439 * @param { string } deviceId - Indicates the device that will resume the object data. 440 * @param { AsyncCallback<SaveSuccessResponse> } callback 441 * {SaveSuccessResponse}: The response of save. 442 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 443 * 2. Incorrect parameter types. 444 * @throws { BusinessError } 801 - Capability not supported. 445 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 446 * @since 9 447 */ 448 save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void; 449 450 /** 451 * Save object, after save object data successfully, the object data will not release when app existed, 452 * and resume data on saved device after app existed. 453 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 454 * you should encrypt it. 455 * The saved data will be released when 456 * 1. saved after 24h. 457 * 2. app uninstalled. 458 * 3. after resume data success, system will auto delete the saved data. 459 * 460 * @param { string } deviceId - Indicates the device that will resume the object data. 461 * @returns { Promise<SaveSuccessResponse> } {SaveSuccessResponse}: The response of save. 462 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 463 * 2. Incorrect parameter types. 464 * @throws { BusinessError } 801 - Capability not supported. 465 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 466 * @since 9 467 */ 468 save(deviceId: string): Promise<SaveSuccessResponse>; 469 470 /** 471 * Revoke save object, delete saved object immediately, if object is saved in local device, 472 * it will delete saved data on all trusted device. 473 * if object is saved in other device, it will delete data in local device. 474 * 475 * @param { AsyncCallback<RevokeSaveSuccessResponse> } callback 476 * {RevokeSaveSuccessResponse}: The response of revokeSave. 477 * @throws { BusinessError } 401 - Parameter error. Incorrect parameter types. 478 * @throws { BusinessError } 801 - Capability not supported. 479 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 480 * @since 9 481 */ 482 revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void; 483 484 /** 485 * Revoke save object, delete saved object immediately, if object is saved in local device, 486 * it will delete saved data on all trusted device. 487 * if object is saved in other device, it will delete data in local device. 488 * 489 * @returns { Promise<RevokeSaveSuccessResponse> } {RevokeSaveSuccessResponse}: The response of revokeSave. 490 * @throws { BusinessError } 801 - Capability not supported. 491 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 492 * @since 9 493 */ 494 revokeSave(): Promise<RevokeSaveSuccessResponse>; 495 496 /** 497 * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that 498 * both assets have the same uri. 499 * @param { string } assetKey - Indicates the key of the asset type in Object. 500 * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. 501 * @param { AsyncCallback<void> } callback - The callback of bindAssetStore. 502 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 503 * 2. Incorrect parameter types. 504 * @throws { BusinessError } 801 - Capability not supported. 505 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 506 * @since 11 507 */ 508 bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback<void>): void; 509 510 /** 511 * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that 512 * both assets have the same uri. 513 * @param { string } assetKey - Indicates the key of the asset type in Object. 514 * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. 515 * @returns { Promise<void> } The promise returned by the function. 516 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 517 * 2. Incorrect parameter types. 518 * @throws { BusinessError } 801 - Capability not supported. 519 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 520 * @since 11 521 */ 522 bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise<void>; 523 } 524} 525 526export default distributedDataObject; 527