/* * Copyright (c) 2022 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @file * @kit ArkData */ import { AsyncCallback, Callback } from './@ohos.base'; import type Context from './application/BaseContext'; import commonType from '@ohos.data.commonType'; /** * Provides interfaces to sync distributed object. * * @namespace distributedDataObject * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 */ declare namespace distributedDataObject { /** * The information about the database bound to the asset. * * @interface BindInfo * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ interface BindInfo { /** * The name of store where the asset resides. * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ storeName: string; /** * The name of table where the asset resides. * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ tableName: string; /** * The Primary key of the rdb table where the asset resides. * * @type { commonType.ValuesBucket } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ primaryKey: commonType.ValuesBucket; /** * The field(column) name of the rdb table where the asset resides. * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ field: string; /** * Name of the asset to be bound. When the column type is Assets, this field refers to the asset name of * one of the assets. * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ assetName: string; } /** * Create distributed object. * * @param { object } source - Source Init data of distributed object. * @returns { DistributedObject } - Return the distributed object. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.create */ function createDistributedObject(source: object): DistributedObject; /** * Create distributed object. * * @param { Context } context - Indicates the application context. * @param { object } source - Source Init data of distributed object. * @returns { DataObject } - Return the distributed object. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ function create(context: Context, source: object): DataObject; /** * Generate a random sessionId. * * @returns { string } - Return generated sessionId. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 */ function genSessionId(): string; /** * The response of save. * Contains the parameter information of the save object. * * @interface SaveSuccessResponse * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ interface SaveSuccessResponse { /** * sessionId of saved object * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ sessionId: string; /** * version of saved object, can compare with DistributedObject.__version * * @type { number } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ version: number; /** * deviceid that data saved * data is "local", means save in local device * otherwise, means the deviceId of others device * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ deviceId: string; } /** * The response of revokeSave. * Contains the sessionId of the changed object. * * @interface RevokeSaveSuccessResponse * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ interface RevokeSaveSuccessResponse { /** * The sessionId of the changed object. * * @type { string } * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ sessionId: string; } /** * Indicates the observer of object data changed. * * @typedef { function } ChangeCallback * @param { string } sessionId - The sessionId of the changed object. * @param { Array } fields - Property names of changed data. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ type DataObserver = (sessionId: string, fields: Array) => void; /** * Indicates the observer of object status changed. * * @typedef { function } StatusObserver * @param { string } sessionId - The sessionId of the changed object. * @param { string } networkId - The networkId of the changed device. * @param { string } status 'online' The object became online on the device and data can be synced to the device; * 'offline' The object became offline on the device and the object can not sync any data; * 'restored' The object restored success. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ type StatusObserver = (sessionId: string, networkId: string, status: string) => void; /** * Defines a callback used to return the asset sync progress. * * @typedef { function } ProcessObserver * @param { string } sessionId - Session ID of the observed object. * @param { number } progress - Asset sync progress. The value range is -1 to 100, where *
100 indicates that the asset sync is complete and -1 indicates that the asset sync failed. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ type ProgressObserver = (sessionId: string, progress: number) => void; /** * Object create by {@link createDistributedObject}. * * @interface DistributedObject * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject */ interface DistributedObject { /** * Change object session * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param { string } sessionId - sessionId The sessionId to be joined, if empty, leave all session. * @returns { boolean } - Return a result of function. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject.setSessionId */ setSessionId(sessionId?: string): boolean; /** * On watch of change * * @param { 'change' } type - Event type, fixed as 'change', indicates data change. * @param { Function } callback * Indicates the observer of object data changed. * {string} sessionId - The sessionId of the changed object. * {Array} fields - Attribute names of changed data. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject.on */ on(type: 'change', callback: (sessionId: string, fields: Array) => void): void; /** * Off watch of change * * @param { 'change' } type - Event type, fixed as 'change', indicates data change. * @param { Function } callback * Indicates the observer of object data changed. * {string} sessionId - The sessionId of the changed object. * {Array} fields - Attribute names of changed data. * callback If not null, off the callback, if undefined, off all callbacks. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject.off */ off(type: 'change', callback?: (sessionId: string, fields: Array) => void): void; /** * On watch of status * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { Function } callback * Indicates the observer of object status changed. * {string} sessionId - The sessionId of the changed object. * {string} networkId - NetworkId of the changed device. * {string} status * 'online' The object became online on the device and data can be synced to the device. * 'offline' The object became offline on the device and the object can not sync any data. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject.on */ on( type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void ): void; /** * Off watch of status * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { Function } callback * Indicates the observer of object status changed. * {string} sessionId - The sessionId of the changed object. * {string} networkId - NetworkId of the changed device. * {string} status * 'online' The object became online on the device and data can be synced to the device. * 'offline' The object became offline on the device and the object can not sync any data. * callback If not null, off the callback, if undefined, off all callbacks. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 8 * @deprecated since 9 * @useinstead ohos.distributedDataObject.DataObject.off */ off( type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void ): void; } /** * Object create by {@link create}. * * @interface DataObject * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ interface DataObject { /** * Change object session. * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. * @param {AsyncCallback} callback - The callback of setSessionId. * @throws {BusinessError} 201 - Permission verification failed. * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ /** * Change object session. * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. * @param {AsyncCallback} callback - The callback of setSessionId. * @throws {BusinessError} 201 - Permission verification failed. * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Incorrect parameter types; * 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 12 */ setSessionId(sessionId: string, callback: AsyncCallback): void; /** * Leave all session. * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param {AsyncCallback} callback - The callback of setSessionId. * @throws {BusinessError} 201 - Permission verification failed. * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ /** * Leave all session. * * @param {AsyncCallback} callback - The callback of setSessionId. * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ setSessionId(callback: AsyncCallback): void; /** * Change object session. * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. * @returns {Promise} - The promise returned by the function. * @throws {BusinessError} 201 - Permission verification failed. * @throws {BusinessError} 401 - Parameter error. Incorrect parameter types. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ /** * Change object session. * * @permission ohos.permission.DISTRIBUTED_DATASYNC * @param {string} sessionId - sessionId The sessionId to be joined, if empty, leave all session. * @returns {Promise} - The promise returned by the function. * @throws {BusinessError} 201 - Permission verification failed. * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Incorrect parameter types; * 2. The sessionId allows only letters, digits, and underscores(_), and cannot exceed 128 in length. * @throws {BusinessError} 15400001 - Failed to create the in-memory database. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 12 */ setSessionId(sessionId?: string): Promise; /** * On watch of change. * * @param { 'change' } type - event type, fixed as 'change', indicates data change. * @param { Function } callback * indicates the observer of object data changed. * {string} sessionId - the sessionId of the changed object. * {Array} fields - Attribute names of changed data. * sessionId The sessionId of the changed object. * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ on(type: 'change', callback: (sessionId: string, fields: Array) => void ): void; /** * Off watch of change. * * @param { 'change' } type - Event type, fixed as 'change', indicates data change. * @param { Function } callback * indicates the observer of object data changed. * {string} sessionId - The sessionId of the changed object. * {Array} fields - Attribute names of changed data. * callback If not null, off the callback, if undefined, off all callbacks. * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ off(type: 'change', callback?: (sessionId: string, fields: Array) => void ): void; /** * On watch of status. * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { Function } callback * indicates the observer of object status changed. * {string} sessionId - The sessionId of the changed object. * {string} networkId - NetworkId of the changed device. * {string} status * 'online' The object became online on the device and data can be synced to the device. * 'offline' The object became offline on the device and the object can not sync any data. * 'restored' The object restored success. * @throws {BusinessError} 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ on( type: 'status', callback: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void ): void; /** * Off watch of status. * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { Function } callback * Indicates the observer of object status changed. * {string} sessionId - The sessionId of the changed object. * {string} networkId - NetworkId of the changed device. * {string} status * 'online' The object became online on the device and data can be synced to the device. * 'offline' The object became offline on the device and the object can not sync any data. * callback If not null, off the callback, if undefined, off all callbacks. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ off( type: 'status', callback?: (sessionId: string, networkId: string, status: 'online' | 'offline' ) => void ): void; /** * Save object, after save object data successfully, the object data will not release when app existed, * and resume data on saved device after app existed. * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, * you should encrypt it * The saved data will be released when * 1. saved after 24h. * 2. app uninstalled. * 3. after resume data success, system will auto delete the saved data. * * @param { string } deviceId - Indicates the device that will resume the object data. * @param { AsyncCallback } callback * {SaveSuccessResponse}: The response of save. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ save(deviceId: string, callback: AsyncCallback): void; /** * Save object, after save object data successfully, the object data will not release when app existed, * and resume data on saved device after app existed. * the saved data secure level is S0, it is not safe, can only save public data, if there is privacy data, * you should encrypt it. * The saved data will be released when * 1. saved after 24h. * 2. app uninstalled. * 3. after resume data success, system will auto delete the saved data. * * @param { string } deviceId - Indicates the device that will resume the object data. * @returns { Promise } {SaveSuccessResponse}: The response of save. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ save(deviceId: string): Promise; /** * Revoke save object, delete saved object immediately, if object is saved in local device, * it will delete saved data on all trusted device. * if object is saved in other device, it will delete data in local device. * * @param { AsyncCallback } callback * {RevokeSaveSuccessResponse}: The response of revokeSave. * @throws { BusinessError } 401 - Parameter error. Incorrect parameter types. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ revokeSave(callback: AsyncCallback): void; /** * Revoke save object, delete saved object immediately, if object is saved in local device, * it will delete saved data on all trusted device. * if object is saved in other device, it will delete data in local device. * * @returns { Promise } {RevokeSaveSuccessResponse}: The response of revokeSave. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 9 */ revokeSave(): Promise; /** * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that * both assets have the same uri. * @param { string } assetKey - Indicates the key of the asset type in Object. * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. * @param { AsyncCallback } callback - The callback of bindAssetStore. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ bindAssetStore(assetKey: string, bindInfo: BindInfo, callback: AsyncCallback): void; /** * Bind an Asset of a distributed object to an asset in rdb that points to the same asset file, which means that * both assets have the same uri. * @param { string } assetKey - Indicates the key of the asset type in Object. * @param { BindInfo } bindInfo - Indicates the information of the asset in RelationalStore. * @returns { Promise } The promise returned by the function. * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; * 2. Incorrect parameter types. * @throws { BusinessError } 801 - Capability not supported. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 11 */ bindAssetStore(assetKey: string, bindInfo: BindInfo): Promise; /** * On watch of change. * * @param { 'change' } type - Event type, fixed as 'change', indicates data change. * @param { DataObserver } callback - The observer of object data changed. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ on(type: 'change', callback: DataObserver): void; /** * Off watch of change. * * @param { 'change' } type - Event type, fixed as 'change', indicates data change. * @param { DataObserver } [callback] - The observer of object data changed, if not null, off the callback, if undefined, off all callbacks. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ off(type: 'change', callback?: DataObserver): void; /** * On watch of status. * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { StatusObserver } callback - The observer of object status changed. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ on(type: 'status', callback: StatusObserver): void; /** * Off watch of status. * * @param { 'status' } type - Event type, fixed as 'status', indicates the online and offline of the object. * @param { StatusObserver } [callback] - The observer of object status changed, if not null, off the callback, if undefined, off all callbacks. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ off(type: 'status', callback?: StatusObserver): void; /** * On watch of progress. * * @param { 'progressChanged' } type - Event type, fixed as 'progressChanged', indicates the progress of asset sync *
in object. * @param { ProgressObserver } callback - The observer of progress of asset sync. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ on(type: 'progressChanged', callback: ProgressObserver): void; /** * Off watch of process. * * @param { 'progressChanged' } type - Event type, fixed as 'progressChanged', indicates the progress of asset sync *
in object. * @param { ProgressObserver } [callback] - The observer of object status changed, if not null, off the callback, if *
undefined, off all callbacks. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ off(type: 'progressChanged', callback?: ProgressObserver): void; /** * Mark an attribute of a distributed object as an asset type. This interface must be called before setSessionId. * * @param { string } assetKey - Indicates the key of the asset type in Object. * @param { string } uri - Indicates the uri of asset. * @returns { Promise } The promise returned by the function. * @throws { BusinessError } 15400002 - Parameter error. Possible causes: * 1. The assetKey is invalid, such as ""; * 2. The uri is invalid, such as "". * @throws {BusinessError} 15400003 - The sessionId of the distributed object has been set. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ setAsset(assetKey: string, uri: string): Promise; /** * Marks an attribute of a distributed object as an asset array type. This interface must be called before setSessionId. * * @param { string } assetsKey - Indicates the key of the asset type in Object. * @param { Array } uris - Indicates the uri array of asset. * @returns { Promise } The promise returned by the function. * @throws { BusinessError } 15400002 - Parameter error. Possible causes: * 1. The assetsKey is invalid, such as ""; * 2. The uris is invalid, such as the length of uris is more than 50. * @throws {BusinessError} 15400003 - The sessionId of the distributed object has been set. * @syscap SystemCapability.DistributedDataManager.DataObject.DistributedObject * @since 20 */ setAssets(assetsKey: string, uris: Array): Promise; } } export default distributedDataObject;