From 9523f665fa348327e2d73e8a6d6b5b7adaa0fdc3 Mon Sep 17 00:00:00 2001 From: Sven Wang Date: Thu, 1 Jul 2021 16:15:51 +0800 Subject: [PATCH] add distributed data javascript interfaces https://gitee.com/openharmony/distributeddatamgr_datamgr/issues/I3YC8O?from=project-issue Signed-off-by: Sven Wang --- api/phone/@ohos.data.distributeddata.d.ts | 63 +++++ .../distributeddata/kvmanager_config.d.ts | 61 +++++ api/phone/data/distributeddata/kvstore.d.ts | 111 +++++++++ .../plain_ordinary_js_objects.d.ts | 215 ++++++++++++++++++ .../data/distributeddata/single_kvstore.d.ts | 59 +++++ 5 files changed, 509 insertions(+) create mode 100644 api/phone/@ohos.data.distributeddata.d.ts create mode 100644 api/phone/data/distributeddata/kvmanager_config.d.ts create mode 100644 api/phone/data/distributeddata/kvstore.d.ts create mode 100644 api/phone/data/distributeddata/plain_ordinary_js_objects.d.ts create mode 100644 api/phone/data/distributeddata/single_kvstore.d.ts diff --git a/api/phone/@ohos.data.distributeddata.d.ts b/api/phone/@ohos.data.distributeddata.d.ts new file mode 100644 index 000000000..579ab1129 --- /dev/null +++ b/api/phone/@ohos.data.distributeddata.d.ts @@ -0,0 +1,63 @@ +/* + * Copyright (c) 2021 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. + */ + +import { AsyncCallback, Callback } from './basic'; +import { KVStore } from "./data/distributeddata/kvstore"; +import { Options } from "./data/distributeddata/plain_ordinary_js_objects"; +import { KVManagerConfig } from './data/distributeddata/kvmanager_config' + +declare namespace distributedData { + /** + * Creates a {@link KVManager} instance based on the configuration information. + * + *

You must pass {@link KVManagerConfig} to provide configuration information + * for creating the {@link KVManager} instance. + * + * @param config Indicates the {@link KVStore} configuration information, + * including the user information and package name. + * @return Returns the {@code KVManager} instance. + * @throws Throws exception if input is invalid. + * @since 7 + */ + function createKVManager(config: KVManagerConfig, callback: AsyncCallback): void; + function createKVManager(config: KVManagerConfig): Promise; + + /** + * Provides interfaces to manage a {@code KVStore} database, + * including obtaining, closing, and deleting the {@code KVStore}. + * + * @devices phone, tablet + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + * @version 1 + */ + interface KVManager { + /** + * Creates and obtains a {@code KVStore} database by specifying {@code Options} and {@code storeId}. + * + * @param options Indicates the options used for creating and obtaining the {@code KVStore} database, + * including {@code isCreateIfMissing}, {@code isEncrypt}, and {@code KVStoreType}. + * @param storeId Identifies the {@code KVStore} database. + * The value of this parameter must be unique for the same application, + * and different applications can share the same value. + * @return Returns a {@code KVStore}, or {@code SingleKVStore}, + * @since 7 + */ + getKVStore(storeId: string, options: Options): Promise; + getKVStore(storeId: string, options: Options, callback: AsyncCallback): void; + } +} + +export default distributedData; \ No newline at end of file diff --git a/api/phone/data/distributeddata/kvmanager_config.d.ts b/api/phone/data/distributeddata/kvmanager_config.d.ts new file mode 100644 index 000000000..643aa1c2a --- /dev/null +++ b/api/phone/data/distributeddata/kvmanager_config.d.ts @@ -0,0 +1,61 @@ +/* + * Copyright (c) 2021 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. + */ + +/** + * Provides configuration information for {@link KVManager} instances, + * including the caller's package name and distributed network type. + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + */ +export interface KVManagerConfig { + /** + * Indicates the user information + */ + userInfo: UserInfo; + + /** + * Indicates the bundleName + */ + bundleName: string; +} + +/** + * Manages user information. + * + *

This class provides methods for obtaining the user ID and type, setting the user ID and type, + * and checking whether two users are the same. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export interface UserInfo { + /** Indicates the user ID to set */ + userId?: string; + + /** Indicates the user type to set */ + userType?: UserType; +} + +/** + * Enumerates user types. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export enum UserType { + /** Indicates a user that logs in to different devices using the same account. */ + SAME_USER_ID = 0 +} \ No newline at end of file diff --git a/api/phone/data/distributeddata/kvstore.d.ts b/api/phone/data/distributeddata/kvstore.d.ts new file mode 100644 index 000000000..6f6da977f --- /dev/null +++ b/api/phone/data/distributeddata/kvstore.d.ts @@ -0,0 +1,111 @@ +/* + * Copyright (c) 2021 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. + */ + +import { AsyncCallback, Callback } from '../../basic'; +import { ChangeNotification, SubscribeType } from "./plain_ordinary_js_objects"; + +/** + * Represents a key-value distributed database and provides methods for adding, deleting, modifying, querying, + * and subscribing to distributed data. + * + *

You can create distributed databases of different types by {@link KVManager#getKVStore (Options, String)} + * with input parameter {@code Options}. Distributed database types are defined in {@code KVStoreType}, + * including {@code SingleKVStore}. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + * @version 1 + */ +export interface KVStore { + /** + * Writes a key-value pair of the byte array type into the {@code KVStore} database. + * + * @param key Indicates the key. The length must be less than {@code MAX_KEY_LENGTH}. + * Spaces before and after the key will be cleared. + * @param value Indicates the byte array, which must be less than 4 MB. + * @return Returns the error code of databases. + * @since 7 + */ + put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback): void; + put(key: string, value: Uint8Array | string | number | boolean): Promise; + + /** + * Deletes the key-value pair based on a specified key. + * + * @param key Indicates the key. The length must be less than {@code MAX_KEY_LENGTH}. + * Spaces before and after the key will be cleared. + * @return Returns the error code of databases. + * @since 7 + */ + delete(key: string, callback: AsyncCallback): void; + delete(key: string): Promise; + + /** + * turn on from the data change notify based on the specified {@code subscribeType}. + * + * @param type Indicates the subscription type, which is defined in {@code SubscribeType}. + * @param observer Indicates the observer of data change events in the distributed database. + * @return Returns the error code of databases. + * @since 7 + */ + on(event: 'dataChange', type: SubscribeType, observer: Callback): void; + + /** + * Subscribe to the notification of store synchronization completion. + * + *

Sync result is returned through asynchronous callback. + * + * @param syncCallback Indicates the callback used to send the synchronization result to the caller. + * @return Returns the {@code number} object. + * @since 7 + */ + on(event: 'syncComplete', syncCallback: Callback>): void; +} + +/** + * KVStore constants + */ +export module Constants { + /** + * max key length. + */ + const MAX_KEY_LENGTH = 1024; + + /** + * max value length. + */ + const MAX_VALUE_LENGTH = 4194303; + + /** + * max device coordinate key length. + */ + const MAX_KEY_LENGTH_DEVICE = 896; + + /** + * max store id length. + */ + const MAX_STORE_ID_LENGTH = 128; + + /** + * max query length. + */ + const MAX_QUERY_LENGTH = 512000; + + /** + * max batch operation size. + */ + const MAX_BATCH_SIZE = 128; +} \ No newline at end of file diff --git a/api/phone/data/distributeddata/plain_ordinary_js_objects.d.ts b/api/phone/data/distributeddata/plain_ordinary_js_objects.d.ts new file mode 100644 index 000000000..efcfd5607 --- /dev/null +++ b/api/phone/data/distributeddata/plain_ordinary_js_objects.d.ts @@ -0,0 +1,215 @@ +/* + * Copyright (c) 2021 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. + */ +/** + * Obtains {@code Value} objects stored in a {@link KVStore} database. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + */ +export interface Value { + /** + * Indicates value type + * + * @see ValueType + * @type {number} + * @memberof Value + */ + type: ValueType; + value: Uint8Array | string | number | boolean; +} + +/** + * Provides key-value pairs stored in the distributed database. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + */ +export interface Entry { + key: string; + value: Value; +} + +/** + * Receives notifications of all data changes, including data insertion, update, and deletion. + * + *

If you have subscribed to {@code KVStore}, you will receive data change notifications and obtain the changed data + * from the parameters in callback methods upon data insertion, update, or deletion. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + */ +export interface ChangeNotification { + /** Indicates data addition records. */ + insertEntries: Entry[]; + /** Indicates data update records. */ + updateEntries: Entry[]; + /** Indicates data deletion records. */ + deleteEntries: Entry[]; + /** Indicates from device id. */ + deviceId: string; +} + +/** + * Describes the subscription type. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @devices phone, tablet + * @since 7 + */ +export enum SubscribeType { + /** Subscription to local data changes */ + SUBSCRIBE_TYPE_LOCAL = 0, + + /** Subscription to remote data changes */ + SUBSCRIBE_TYPE_REMOTE = 1, + + /** Subscription to both local and remote data changes */ + SUBSCRIBE_TYPE_ALL = 2, +} + +/** + * Describes the {@code KVStore} type. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export enum KVStoreType { + /** Device-collaborated database, as specified by {@code DeviceKVStore} */ + DEVICE_COLLABORATION = 0, + + /** Single-version database, as specified by {@code SingleKVStore} */ + SINGLE_VERSION = 1, + + /** Multi-version database, as specified by {@code MultiKVStore} */ + MULTI_VERSION = 2, +} + +/** + * Describes the {@code KVStore} type. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export enum SecurityLevel { + /** + * NO_LEVEL: mains not set the security level. + * + * @since 7 + */ + NO_LEVEL = 0, + + /** + * S0: mains the db is public. + * There is no impact even if the data is leaked. + * + * @since 7 + */ + S0 = 1, + + /** + * S1: mains the db is low level security + * There are some low impact, when the data is leaked. + * + * @since 7 + */ + S1 = 2, + + /** + * S2: mains the db is middle level security + * There are some major impact, when the data is leaked. + * + * @since 7 + */ + S2 = 3, + + /** + * S3: mains the db is high level security + * There are some severity impact, when the data is leaked. + * + * @since 7 + */ + S3 = 5, + + /** + * S4: mains the db is critical level security + * There are some critical impact, when the data is leaked. + * + * @since 7 + */ + S4 = 6, +} + +/** + * Provides configuration options for creating a {@code KVStore}. + * + *

You can determine whether to create another database if a {@code KVStore} database is missing, + * whether to encrypt the database, and the database type. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export interface Options { + createIfMissing?: boolean; + encrypt?: boolean; + backup?: boolean; + autoSync?: boolean; + kvStoreType?: KVStoreType; + securityLevel?: SecurityLevel; +} + +/** + * Indicates the database synchronization mode. + * + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + */ +export enum SyncMode { + /** Indicates that data is only pulled from the remote end. */ + PULL_ONLY = 0, + /** Indicates that data is only pushed from the local end. */ + PUSH_ONLY = 1, + /** Indicates that data is pushed from the local end, and then pulled from the remote end. */ + PUSH_PULL = 2 +} + +/** + * Indicates the {@code ValueType}. + * + *

{@code ValueType} is obtained based on the value. + * + * @since 7 + */ +export enum ValueType { + /** Indicates that the value type is string. */ + STRING = 0, + + /** Indicates that the value type is int. */ + INTEGER = 1, + + /** Indicates that the value type is float. */ + FLOAT = 2, + + /** Indicates that the value type is byte array. */ + BYTE_ARRAY = 3, + + /** Indicates that the value type is boolean. */ + BOOLEAN = 4, + + /** Indicates that the value type is double. */ + DOUBLE = 5 +} diff --git a/api/phone/data/distributeddata/single_kvstore.d.ts b/api/phone/data/distributeddata/single_kvstore.d.ts new file mode 100644 index 000000000..a631e52d2 --- /dev/null +++ b/api/phone/data/distributeddata/single_kvstore.d.ts @@ -0,0 +1,59 @@ +/* + * Copyright (c) 2021 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. + */ +import { AsyncCallback } from '../../basic'; +import { KVStore } from "./kvstore"; +import { SyncMode } from "./plain_ordinary_js_objects"; + +/** + * Provides methods related to single-version distributed databases. + * + *

To create a {@code SingleKVStore} database, + * you can use the {@link data.distributed.common.KVManager#getKVStore​(Options, String)} method + * with {@code KVStoreType} set to {@code SINGLE_VERSION} for the input parameter {@code Options}. + * This database synchronizes data to other databases in time sequence. + * The {@code SingleKVStore} database does not support + * synchronous transactions, or data search using snapshots. + * + * @devices phone, tablet + * @Syscap SystemCapability.Data.DATA_DISTRIBUTEDDATAMGR + * @since 7 + * @version 1 + */ +export interface SingleKVStore extends KVStore { + /** + * Obtains the value of a specified key. + * + * @param key Indicates the key of the value to be queried. + * @return Returns the value matching the given criteria. + * @throws Throws exception if any of the following errors occurs: {@code INVALID_ARGUMENT}, + * {@code SERVER_UNAVAILABLE}, {@code IPC_ERROR}, {@code DB_ERROR}, and {@code KEY_NOT_FOUND}. + * @since 7 + */ + get(key: string, callback: AsyncCallback): void; + get(key: string): Promise; + + /** + * Synchronizing KVStore Data Between Devices. + * + * @param deviceIdList Indicates the {@code string}. + * @param mode Indicates the {@code SyncMode} object. + * @param allowedDelayMs Indicates the number type parameter. + * @return Returns the {@code number} object. + * @since 7 + */ + sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void; +} + +