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. 107 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 108 * @since 9 109 */ 110 function create(context: Context, source: object): DataObject; 111 112 /** 113 * Generate a random sessionId. 114 * 115 * @returns { string } - Return generated sessionId. 116 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 117 * @since 8 118 */ 119 function genSessionId(): string; 120 121 /** 122 * The response of save. 123 * Contains the parameter information of the save object. 124 * 125 * @interface SaveSuccessResponse 126 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 127 * @since 9 128 */ 129 interface SaveSuccessResponse { 130 /** 131 * sessionId of saved object 132 * 133 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 134 * @since 9 135 */ 136 sessionId: string; 137 138 /** 139 * version of saved object, can compare with DistributedObject.__version 140 * 141 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 142 * @since 9 143 */ 144 version: number; 145 146 /** 147 * deviceid that data saved 148 * data is "local", means save in local device 149 * otherwise, means the deviceId of others device 150 * 151 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 152 * @since 9 153 */ 154 deviceId: string; 155 } 156 157 /** 158 * The response of revokeSave. 159 * Contains the sessionId of the changed object. 160 * 161 * @interface RevokeSaveSuccessResponse 162 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 163 * @since 9 164 */ 165 interface RevokeSaveSuccessResponse { 166 /** 167 * The sessionId of the changed object. 168 * 169 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 170 * @since 9 171 */ 172 sessionId: string; 173 } 174 175 /** 176 * Object create by {@link createDistributedObject}. 177 * 178 * @interface DistributedObject 179 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 180 * @since 8 181 * @deprecated since 9 182 * @useinstead ohos.distributedDataObject.DataObject 183 */ 184 interface DistributedObject { 185 /** 186 * Change object session 187 * 188 * @permission ohos.permission.DISTRIBUTED_DATASYNC 189 * @param { string } sessionId - sessionId The sessionId to be joined, if empty, leave all session. 190 * @returns { boolean } - Return a result of function. 191 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 192 * @since 8 193 * @deprecated since 9 194 * @useinstead ohos.distributedDataObject.DataObject.setSessionId 195 */ 196 setSessionId(sessionId?: string): boolean; 197 198 /** 199 * On watch of change 200 * 201 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 202 * @param { Function } callback 203 * Indicates the observer of object data changed. 204 * {string} sessionId - The sessionId of the changed object. 205 * {Array<string>} fields - Attribute names of changed data. 206 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 207 * @since 8 208 * @deprecated since 9 209 * @useinstead ohos.distributedDataObject.DataObject.on 210 */ 211 on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void): void; 212 213 /** 214 * Off watch of change 215 * 216 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 217 * @param { Function } callback 218 * Indicates the observer of object data changed. 219 * {string} sessionId - The sessionId of the changed object. 220 * {Array<string>} fields - Attribute names of changed data. 221 * callback If not null, off the callback, if undefined, off all callbacks. 222 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 223 * @since 8 224 * @deprecated since 9 225 * @useinstead ohos.distributedDataObject.DataObject.off 226 */ 227 off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void): void; 228 229 /** 230 * On watch of status 231 * 232 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 233 * @param { Function } callback 234 * Indicates the observer of object status changed. 235 * {string} sessionId - The sessionId of the changed object. 236 * {string} networkId - NetworkId of the changed device. 237 * {string} status 238 * 'online' The object became online on the device and data can be synced to the device. 239 * 'offline' The object became offline on the device and the object can not sync any data. 240 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 241 * @since 8 242 * @deprecated since 9 243 * @useinstead ohos.distributedDataObject.DataObject.on 244 */ 245 on( 246 type: 'status', 247 callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 248 ): void; 249 250 /** 251 * Off watch of status 252 * 253 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 254 * @param { Function } callback 255 * Indicates the observer of object status changed. 256 * {string} sessionId - The sessionId of the changed object. 257 * {string} networkId - NetworkId of the changed device. 258 * {string} status 259 * 'online' The object became online on the device and data can be synced to the device. 260 * 'offline' The object became offline on the device and the object can not sync any data. 261 * callback If not null, off the callback, if undefined, off all callbacks. 262 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 263 * @since 8 264 * @deprecated since 9 265 * @useinstead ohos.distributedDataObject.DataObject.off 266 */ 267 off( 268 type: 'status', 269 callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 270 ): void; 271 } 272 273 /** 274 * Object create by {@link create}. 275 * 276 * @interface DataObject 277 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 278 * @since 9 279 */ 280 interface DataObject { 281 /** 282 * Change object session. 283 * 284 * @permission ohos.permission.DISTRIBUTED_DATASYNC 285 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 286 * @param {AsyncCallback<void>} callback - The callback of setSessionId. 287 * @throws {BusinessError} 201 - Permission verification failed. 288 * @throws {BusinessError} 401 - Parameter error. 289 * @throws {BusinessError} 15400001 - Create table failed. 290 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 291 * @since 9 292 */ 293 setSessionId(sessionId: string, callback: AsyncCallback<void>): void; 294 295 /** 296 * Leave all session. 297 * 298 * @permission ohos.permission.DISTRIBUTED_DATASYNC 299 * @param {AsyncCallback<void>} callback - The callback of setSessionId. 300 * @throws {BusinessError} 201 - Permission verification failed. 301 * @throws {BusinessError} 401 - Parameter error. 302 * @throws {BusinessError} 15400001 - Create table failed. 303 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 304 * @since 9 305 */ 306 setSessionId(callback: AsyncCallback<void>): void; 307 308 /** 309 * Change object session. 310 * 311 * @permission ohos.permission.DISTRIBUTED_DATASYNC 312 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 313 * @returns {Promise<void>} - The promise returned by the function. 314 * @throws {BusinessError} 201 - Permission verification failed. 315 * @throws {BusinessError} 401 - Parameter error. 316 * @throws {BusinessError} 15400001 - Create table failed. 317 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 318 * @since 9 319 */ 320 setSessionId(sessionId?: string): Promise<void>; 321 322 /** 323 * On watch of change. 324 * 325 * @param { 'change' } type - event type, fixed as 'change', indicates data change. 326 * @param { Function } callback 327 * indicates the observer of object data changed. 328 * {string} sessionId - the sessionId of the changed object. 329 * {Array<string>} fields - Attribute names of changed data. 330 * sessionId The sessionId of the changed object. 331 * @throws { BusinessError } 401 - Parameter error. 332 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 333 * @since 9 334 */ 335 on(type: 'change', callback: (sessionId: string, fields: Array<string>) => void ): void; 336 337 /** 338 * Off watch of change. 339 * 340 * @param { 'change' } type - Event type, fixed as 'change', indicates data change. 341 * @param { Function } callback 342 * indicates the observer of object data changed. 343 * {string} sessionId - The sessionId of the changed object. 344 * {Array<string>} fields - Attribute names of changed data. 345 * callback If not null, off the callback, if undefined, off all callbacks. 346 * @throws { BusinessError } 401 - Parameter error. 347 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 348 * @since 9 349 */ 350 off(type: 'change', callback?: (sessionId: string, fields: Array<string>) => void ): void; 351 352 /** 353 * On watch of status. 354 * 355 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 356 * @param { Function } callback 357 * indicates the observer of object status changed. 358 * {string} sessionId - The sessionId of the changed object. 359 * {string} networkId - NetworkId of the changed device. 360 * {string} status 361 * 'online' The object became online on the device and data can be synced to the device. 362 * 'offline' The object became offline on the device and the object can not sync any data. 363 * 'restored' The object restored success. 364 * @throws { BusinessError } 401 - Parameter error. 365 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 366 * @since 9 367 */ 368 on( 369 type: 'status', 370 callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 371 ): void; 372 373 /** 374 * Off watch of status. 375 * 376 * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. 377 * @param { Function } callback 378 * Indicates the observer of object status changed. 379 * {string} sessionId - The sessionId of the changed object. 380 * {string} networkId - NetworkId of the changed device. 381 * {string} status 382 * 'online' The object became online on the device and data can be synced to the device. 383 * 'offline' The object became offline on the device and the object can not sync any data. 384 * callback If not null, off the callback, if undefined, off all callbacks. 385 * @throws { BusinessError } 401 - Parameter error. 386 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 387 * @since 9 388 */ 389 off( 390 type: 'status', 391 callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void 392 ): void; 393 394 /** 395 * Save object, after save object data successfully, the object data will not release when app existed, 396 * and resume data on saved device after app existed. 397 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 398 * you should encrypt it 399 * The saved data will be released when 400 * 1. saved after 24h. 401 * 2. app uninstalled. 402 * 3. after resume data success, system will auto delete the saved data. 403 * 404 * @param { string } deviceId - Indicates the device that will resume the object data. 405 * @param { AsyncCallback<SaveSuccessResponse> } callback 406 * {SaveSuccessResponse}: The response of save. 407 * @throws { BusinessError } 401 - Parameter error. 408 * @throws { BusinessError } 801 - Capability not supported. 409 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 410 * @since 9 411 */ 412 save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void; 413 414 /** 415 * Save object, after save object data successfully, the object data will not release when app existed, 416 * and resume data on saved device after app existed. 417 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 418 * you should encrypt it. 419 * The saved data will be released when 420 * 1. saved after 24h. 421 * 2. app uninstalled. 422 * 3. after resume data success, system will auto delete the saved data. 423 * 424 * @param { string } deviceId - Indicates the device that will resume the object data. 425 * @returns { Promise<SaveSuccessResponse> } {SaveSuccessResponse}: The response of save. 426 * @throws { BusinessError } 401 - Parameter error. 427 * @throws { BusinessError } 801 - Capability not supported. 428 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 429 * @since 9 430 */ 431 save(deviceId: string): Promise<SaveSuccessResponse>; 432 433 /** 434 * Revoke save object, delete saved object immediately, if object is saved in local device, 435 * it will delete saved data on all trusted device. 436 * if object is saved in other device, it will delete data in local device. 437 * 438 * @param { AsyncCallback<RevokeSaveSuccessResponse> } callback 439 * {RevokeSaveSuccessResponse}: The response of revokeSave. 440 * @throws { BusinessError } 401 - Parameter error. 441 * @throws { BusinessError } 801 - Capability not supported. 442 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 443 * @since 9 444 */ 445 revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void; 446 447 /** 448 * Revoke save object, delete saved object immediately, if object is saved in local device, 449 * it will delete saved data on all trusted device. 450 * if object is saved in other device, it will delete data in local device. 451 * 452 * @returns { Promise<RevokeSaveSuccessResponse> } {RevokeSaveSuccessResponse}: The response of revokeSave. 453 * @throws { BusinessError } 401 - Parameter error. 454 * @throws { BusinessError } 801 - Capability not supported. 455 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 456 * @since 9 457 */ 458 revokeSave(): Promise<RevokeSaveSuccessResponse>; 459 460 /** 461 * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that 462 * both assets have the same uri. 463 * @param { string } assetKey - Indicates the key of the asset type in Object. 464 * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. 465 * @param { AsyncCallback<void> } callback - The callback of bindAssetStore. 466 * @throws { BusinessError } 401 - Parameter error. 467 * @throws { BusinessError } 801 - Capability not supported. 468 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 469 * @since 11 470 */ 471 bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback<void>): void; 472 473 /** 474 * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that 475 * both assets have the same uri. 476 * @param { string } assetKey - Indicates the key of the asset type in Object. 477 * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. 478 * @returns { Promise<void> } The promise returned by the function. 479 * @throws { BusinessError } 401 - Parameter error. 480 * @throws { BusinessError } 801 - Capability not supported. 481 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 482 * @since 11 483 */ 484 bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise<void>; 485 } 486} 487 488export default distributedDataObject; 489