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 16import {AsyncCallback, Callback} from './basic'; 17import Context from './application/Context'; 18 19/** 20 * Provides interfaces to sync distributed object. 21 * 22 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 23 * @since 8 24 */ 25declare namespace distributedDataObject { 26 27 /** 28 * Create distributed object. 29 * 30 * @param {object} source - source Init data of distributed object. 31 * @returns {DistributedObject} - return the distributed object. 32 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 33 * @since 8 34 * @deprecated since 9 35 * @useinstead ohos.distributedDataObject.create 36 */ 37 function createDistributedObject(source: object): DistributedObject; 38 39 /** 40 * Create distributed object. 41 * 42 * @param {Context} context - Indicates the application context. 43 * @param {object} source - source Init data of distributed object. 44 * @returns {DataObject} - return the distributed object. 45 * @throws {BusinessError} 401 - the parameter check failed. 46 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 47 * @since 9 48 */ 49 function create(context: Context, source: object): DataObject; 50 51 /** 52 * Generate a random sessionId. 53 * 54 * @returns {string} - return generated sessionId. 55 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 56 * @since 8 57 */ 58 function genSessionId(): string; 59 60 /** 61 * The response of save. 62 * Contains the parameter information of the save object. 63 * 64 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 65 * @since 9 66 */ 67 interface SaveSuccessResponse { 68 69 /** 70 * sessionId of saved object 71 * 72 * @since 9 73 */ 74 sessionId: string; 75 76 /** 77 * version of saved object, can compare with DistributedObject.__version 78 * 79 * @since 9 80 */ 81 version: number; 82 83 /** 84 * deviceid that data saved 85 * data is "local", means save in local device 86 * otherwise, means the networkId of device 87 * 88 * @since 9 89 */ 90 deviceId: string; 91 } 92 93 /** 94 * The response of revokeSave. 95 * Contains the sessionId of the changed object. 96 * 97 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 98 * @since 9 99 */ 100 interface RevokeSaveSuccessResponse { 101 102 /** 103 * The sessionId of the changed object. 104 * 105 * @since 9 106 */ 107 sessionId: string; 108 } 109 110 /** 111 * Object create by {@link createDistributedObject}. 112 * 113 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 114 * @since 8 115 * @deprecated since 9 116 * @useinstead ohos.distributedDataObject.DataObject 117 */ 118 interface DistributedObject { 119 120 /** 121 * Change object session 122 * 123 * @permission ohos.permission.DISTRIBUTED_DATASYNC 124 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 125 * @returns {boolean} - return a result of function. 126 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 127 * @since 8 128 * @deprecated since 9 129 * @useinstead ohos.distributedDataObject.DataObject.setSessionId 130 */ 131 setSessionId(sessionId?: string): boolean; 132 133 /** 134 * On watch of change 135 * 136 * @param {string} type - event type, fixed as' change ', indicates data change. 137 * @param {Callback<{sessionId: string, fields: Array<string>}>} callback 138 * indicates the observer of object data changed. 139 * {string} sessionId - the sessionId of the changed object. 140 * {Array<string>} fields - changed data. 141 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 142 * @since 8 143 * @deprecated since 9 144 * @useinstead ohos.distributedDataObject.DataObject.on 145 */ 146 on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void; 147 148 /** 149 * Off watch of change 150 * 151 * @param {string} type - event type, fixed as' change ', indicates data change. 152 * @param {Callback<{sessionId: string, fields: Array<string>}>} callback 153 * indicates the observer of object data changed. 154 * {string} sessionId - the sessionId of the changed object. 155 * {Array<string>} fields - changed data. 156 * callback If not null, off the callback, if undefined, off all callbacks. 157 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 158 * @since 8 159 * @deprecated since 9 160 * @useinstead ohos.distributedDataObject.DataObject.off 161 */ 162 off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void; 163 164 /** 165 * On watch of status 166 * 167 * @param {string} type - event type, fixed as' status', indicates the online and offline of the object. 168 * @param {Callback<{sessionId: string, networkId: string, status: 'online' | 'offline'}>} callback 169 * indicates the observer of object status changed. 170 * {string} sessionId - the sessionId of the changed object. 171 * {string} networkId - networkId of the changed device. 172 * {string} status 173 * 'online' The object became online on the device and data can be synced to the device. 174 * 'offline' The object became offline on the device and the object can not sync any data. 175 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 176 * @since 8 177 * @deprecated since 9 178 * @useinstead ohos.distributedDataObject.DataObject.on 179 */ 180 on(type: 'status', 181 callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void; 182 183 /** 184 * Off watch of status 185 * 186 * @param {string} type - event type, fixed as' status', indicates the online and offline of the object. 187 * @param {Callback<{sessionId: string, networkId: string, status: 'online' | 'offline'}>} callback 188 * Indicates the observer of object status changed. 189 * {string} sessionId - the sessionId of the changed object. 190 * {string} networkId - networkId of the changed device. 191 * {string} status 192 * 'online' The object became online on the device and data can be synced to the device. 193 * 'offline' The object became offline on the device and the object can not sync any data. 194 * callback If not null, off the callback, if undefined, off all callbacks. 195 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 196 * @since 8 197 * @deprecated since 9 198 * @useinstead ohos.distributedDataObject.DataObject.off 199 */ 200 off(type: 'status', 201 callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void; 202 } 203 204 /** 205 * Object create by {@link create}. 206 * 207 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 208 * @since 9 209 */ 210 interface DataObject { 211 212 /* 213 * Change object session. 214 * 215 * @permission ohos.permission.DISTRIBUTED_DATASYNC 216 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 217 * @param {AsyncCallback<void>} callback - the callback of setSessionId. 218 * @throws {BusinessError} 201 - the permissions check failed. 219 * @throws {BusinessError} 401 - the parameter check failed. 220 * @throws {BusinessError} 15400001 - create table failed. 221 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 222 * @since 9 223 */ 224 setSessionId(sessionId: string, callback: AsyncCallback<void>): void; 225 setSessionId(callback: AsyncCallback<void>): void; 226 227 /* 228 * Change object session. 229 * 230 * @permission ohos.permission.DISTRIBUTED_DATASYNC 231 * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. 232 * @returns {Promise<void>} - the promise returned by the function. 233 * @throws {BusinessError} 201 - the permissions check failed. 234 * @throws {BusinessError} 401 - the parameter check failed. 235 * @throws {BusinessError} 15400001 - create table failed. 236 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 237 * @since 9 238 */ 239 setSessionId(sessionId?: string): Promise<void>; 240 241 /** 242 * On watch of change. 243 * 244 * @param {string} type - event type, fixed as' change ', indicates data change. 245 * @param {Callback<{sessionId: string, fields: Array<string>}>} callback 246 * indicates the observer of object data changed. 247 * {string} sessionId - the sessionId of the changed object. 248 * {Array<string>} fields - changed data. 249 * sessionId the sessionId of the changed object. 250 * @throws {BusinessError} 401 - the parameter check failed. 251 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 252 * @since 9 253 */ 254 on(type: 'change', callback: Callback<{ sessionId: string, fields: Array<string> }>): void; 255 256 /** 257 * Off watch of change. 258 * 259 * @param {string} type - event type, fixed as' change ', indicates data change. 260 * @param {Callback<{sessionId: string, fields: Array<string>}>} callback 261 * indicates the observer of object data changed. 262 * {string} sessionId - the sessionId of the changed object. 263 * {Array<string>} fields - changed data. 264 * callback If not null, off the callback, if undefined, off all callbacks. 265 * @throws {BusinessError} 401 - the parameter check failed. 266 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 267 * @since 9 268 */ 269 off(type: 'change', callback?: Callback<{ sessionId: string, fields: Array<string> }>): void; 270 271 /** 272 * On watch of status. 273 * 274 * @param {string} type - event type, fixed as' status', indicates the online and offline of the object. 275 * @param {Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>} callback 276 * indicates the observer of object status changed. 277 * {string} sessionId - the sessionId of the changed object. 278 * {string} networkId - networkId of the changed device. 279 * {string} status 280 * 'online' The object became online on the device and data can be synced to the device. 281 * 'offline' The object became offline on the device and the object can not sync any data. 282 * 'restored' The object restored success. 283 * @throws {BusinessError} 401 - the parameter check failed. 284 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 285 * @since 9 286 */ 287 on(type: 'status', 288 callback: Callback<{ sessionId: string, networkId: string, status: 'online' | 'offline' }>): void; 289 290 /** 291 * Off watch of status. 292 * 293 * @param {string} type - event type, fixed as' status', indicates the online and offline of the object. 294 * @param {Callback<{sessionId: string, networkId: string, status: 'online' | 'offline'}>} callback 295 * Indicates the observer of object status changed. 296 * {string} sessionId - the sessionId of the changed object. 297 * {string} networkId - networkId of the changed device. 298 * {string} status 299 * 'online' The object became online on the device and data can be synced to the device. 300 * 'offline' The object became offline on the device and the object can not sync any data. 301 * callback If not null, off the callback, if undefined, off all callbacks. 302 * @throws {BusinessError} 401 - the parameter check failed. 303 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 304 * @since 9 305 */ 306 off(type: 'status', 307 callback?: Callback<{ sessionId: string, deviceId: string, status: 'online' | 'offline' }>): void; 308 309 /** 310 * Save object, after save object data successfully, the object data will not release when app existed, 311 * and resume data on saved device after app existed. 312 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 313 * you should encrypt it 314 * 315 * The saved data will be released when 316 * 1. saved after 24h. 317 * 2. app uninstalled. 318 * 3. after resume data success, system will auto delete the saved data. 319 * 320 * @param {string} deviceId - Indicates the device that will resume the object data. 321 * @param {AsyncCallback<SaveSuccessResponse>} callback 322 * {SaveSuccessResponse}: the response of save. 323 * @throws {BusinessError} 401 - the parameter check failed. 324 * @throws {BusinessError} 801 - Capability not supported. 325 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 326 * @since 9 327 */ 328 save(deviceId: string, callback: AsyncCallback<SaveSuccessResponse>): void; 329 330 /** 331 * Save object, after save object data successfully, the object data will not release when app existed, 332 * and resume data on saved device after app existed. 333 * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, 334 * you should encrypt it. 335 * 336 * The saved data will be released when 337 * 1. saved after 24h. 338 * 2. app uninstalled. 339 * 3. after resume data success, system will auto delete the saved data. 340 * 341 * @param {string} deviceId - Indicates the device that will resume the object data. 342 * @returns {Promise<SaveSuccessResponse>} {SaveSuccessResponse}: the response of save. 343 * @throws {BusinessError} 401 - the parameter check failed. 344 * @throws {BusinessError} 801 - Capability not supported. 345 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 346 * @since 9 347 */ 348 save(deviceId: string): Promise<SaveSuccessResponse>; 349 350 /** 351 * Revoke save object, delete saved object immediately, if object is saved in local device, 352 * it will delete saved data on all trusted device. 353 * if object is saved in other device, it will delete data in local device. 354 * 355 * @param {AsyncCallback<RevokeSaveSuccessResponse>} callback 356 * {RevokeSaveSuccessResponse}: the response of revokeSave. 357 * @throws {BusinessError} 401 - the parameter check failed. 358 * @throws {BusinessError} 801 - Capability not supported. 359 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 360 * @since 9 361 */ 362 revokeSave(callback: AsyncCallback<RevokeSaveSuccessResponse>): void; 363 364 /** 365 * Revoke save object, delete saved object immediately, if object is saved in local device, 366 * it will delete saved data on all trusted device. 367 * if object is saved in other device, it will delete data in local device. 368 * 369 * @returns {Promise<RevokeSaveSuccessResponse>} {RevokeSaveSuccessResponse}: the response of revokeSave. 370 * @throws {BusinessError} 401 - the parameter check failed. 371 * @throws {BusinessError} 801 - Capability not supported. 372 * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject 373 * @since 9 374 */ 375 revokeSave(): Promise<RevokeSaveSuccessResponse>; 376 } 377} 378 379export default distributedDataObject; 380