diff --git a/en/application-dev/database/Readme-EN.md b/en/application-dev/database/Readme-EN.md index 9f7ccd0d08e8683aca6e6c86ddef80f8e0e5aad4..a8aff91550cb265137a89d8718f6232c34e1aa43 100644 --- a/en/application-dev/database/Readme-EN.md +++ b/en/application-dev/database/Readme-EN.md @@ -3,12 +3,19 @@ - Distributed Data Service - [Distributed Data Service Overview](database-mdds-overview.md) - [Distributed Data Service Development](database-mdds-guidelines.md) + - Relational Database - [RDB Overview](database-relational-overview.md) - [RDB Development](database-relational-guidelines.md) + - Preferences - [Preferences Overview](database-preference-overview.md) - [Preferences Development](database-preference-guidelines.md) + - Distributed Data Object - [Distributed Data Object Overview](database-distributedobject-overview.md) - [Distributed Data Object Development](database-distributedobject-guidelines.md) + +- Data Share + - [DataShare Overview](database-datashare-overview.md) + - [DataShare Development](database-datashare-guidelines.md) diff --git a/en/application-dev/database/database-datashare-guidelines.md b/en/application-dev/database/database-datashare-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..251c33fbc54aadba8aa07b92f0292ab86f322d70 --- /dev/null +++ b/en/application-dev/database/database-datashare-guidelines.md @@ -0,0 +1,191 @@ +# DataShare Development +The **DataShare** module allows an application to manage its own data and share data with other applications. Currently, data can be shared only between the applications on the same device. + +## Available APIs + +**Table 1** APIs of the data provider + +|API|Description| +|:------|:------| +|onCreate?(want: Want, callback: AsyncCallback<void>): void|Called to initialize service logic when the data provider application is created, for example, when a database is created.| +|insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|Inserts data into the database.| +|update?(uri: string, predicates: DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|Updates data in the database.| +|query?(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void|Queries data from the database.| +|delete?(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void|Deletes data from the database.| + +For more details, see [DataShareExtensionAbility](../reference/apis/js-apis-application-DataShareExtensionAbility.md). + +**Table 2** APIs of the data consumer + +| API | Description | +| :----------------------------------------------------------- | :--------------------------------- | +| createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void | Creates a **DataShareHelper** instance. | +| insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void | Inserts a single data record into the database. | +| update(uri: string, predicates: DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void | Updates data in the database. | +| query(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void | Queries data from the database. | +| delete(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void | Deletes one or more data records from the database.| + +For more details, see [DataShareHelper](../reference/apis/js-apis-data-dataShare.md). + +## When to Use + +**DataShare** can be divided into the following: + +- Data provider: Implement functions of adding, deleting, modifying, and querying data, and opening files, and share data. +- Data consumer: Access the data provided by the provider using **DataShareHelper**. + +Examples are given below. + +### Data Provider Application Development (Only for System Applications) + +1. Import the dependencies. + + ```ts + import Extension from '@ohos.application.DataShareExtensionAbility' + import rdb from '@ohos.data.rdb'; + import fileIo from '@ohos.fileio' + import dataSharePredicates from '@ohos.data.dataSharePredicates' + ``` + +2. Override **DataShareExtensionAbility** APIs based on actual requirements. For example, if the data provider provides only data query, override only the query() API. + +3. Implement the data provider services. For example, implement data storage of the data provider by using a database, reading and writing files, or accessing the network. + + ```ts + let DB_NAME = "DB00.db"; + let TBL_NAME = "TBL00"; + let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS " + + TBL_NAME + + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, isStudent BOOLEAN, Binary BINARY)"; + + let rdbStore; + let result; + + export default class DataShareExtAbility extends Extension { + private rdbStore_; + + // Override the onCreate() API. + onCreate(want, callback) { + result = this.context.cacheDir + '/datashare.txt' + // Create an RDB. + rdb.getRdbStore(this.context, { + name: DB_NAME + }, 1, function (err, data) { + rdbStore = data; + rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) { + console.log('DataShareExtAbility onCreate, executeSql done err:' + JSON.stringify(err)); + }); + callback(); + }); + } + + // Override the query() API. + query(uri, predicates, columns, callback) { + if (predicates == null || predicates == undefined) { + console.info('invalid predicates'); + } + try { + rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) { + if (resultSet != undefined) { + console.info('resultSet.rowCount: ' + resultSet.rowCount); + } + if (callback != undefined) { + callback(err, resultSet); + } + }); + } catch (err) { + console.error('error' + err); + } + } + // Override other APIs as required. + // ... + }; + ``` + +4. Define **DataShareExtensionAbility** in **module.json5**. + + | Field| Description | + | ------------ | ------------------------------------------------------------ | + | "name" | Ability name, corresponding to the **ExtensionAbility** class name derived from **Ability**. | + | "type" | Ability type. The value is **dataShare**, indicating the development is based on the **Datashare** template.| + | "uri" | URI used for communication. It is the unique identifier for the client to connect to the server. | + | "visible" | Whether it is visible to other applications. Communication with other applications is allowed only when the value is **true**.| + + **module.json5 example** + + ```json + "extensionAbilities": [ + { + "srcEntrance": "./ets/DataShareExtAbility/DataShareExtAbility.ts", + "name": "DataShareExtAbility", + "icon": "$media:icon", + "description": "$string:description_datashareextability", + "type": "dataShare", + "uri": "datashare://com.samples.datasharetest.DataShare", + "visible": true + } + ] + ``` + +### Data Consumer Application Development + +1. Import basic dependencies. + + ```ts + import Ability from '@ohos.application.Ability' + import dataShare from '@ohos.data.dataShare' + import dataSharePredicates from '@ohos.data.dataSharePredicates' + ``` + +2. Define the URI string for communicating with the data provider. + + ```ts + // Different from the URI defined in the module.json5 file, the URI passed in the parameter has an extra slash (/), because there is a DeviceID parameter between the second and the third slash (/). + let dseUri = ("datashare:///com.samples.datasharetest.DataShare"); + ``` + +2. Create a **DataShareHelper** instance. + + ```ts + let dsHelper; + let abilityContext; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + abilityContext = this.context; + dataShare.createDataShareHelper(abilityContext, dseUri, (err,data)=>{ + dsHelper = data; + }); + } + } + ``` + +3. Use the APIs provided by **DataShareHelper** to access the services provided by the provider, for example, adding, deleting, modifying, and querying data. + + ```ts + // Construct a piece of data. + var valuesBucket = {"name": "ZhangSan", "age": 21, "isStudent": false, "Binary": new Uint8Array([1,2,3])}; + var updateBucket = {"name": "LiSi", "age": 18, "isStudent": true, "Binary": new Uint8Array([1,2,3])}; + let da = new dataSharePredicates.DataSharePredicates(); + var valArray =new Array("*"); + let people = new Array( + {"name": "LiSi", "age": 41, "Binary": ar}, + {"name": "WangWu", "age": 21, "Binary": arr}, + {"name": "ZhaoLiu", "age": 61, "Binary": arr}); + // Insert a piece of data. + dsHelper.insert(dseUri, valuesBucket, (err,data) => { + console.log("dsHelper insert result: " + data); + }); + // Delete the specified data. + dsHelper.delete(dseUri, da, (err,data) => { + console.log("dsHelper delete result: " + data); + }); + // Update data. + dsHelper.update(dseUri, da, updateBucket, (err,data) => { + console.log("dsHelper update result: " + data); + }); + // Query data. + dsHelper.query(dseUri, da, valArray, (err,data) => { + console.log("dsHelper query result: " + data); + }); + ``` + diff --git a/en/application-dev/database/database-datashare-overview.md b/en/application-dev/database/database-datashare-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..857e9fa4205cd0545803643af1515da485b83d8a --- /dev/null +++ b/en/application-dev/database/database-datashare-overview.md @@ -0,0 +1,54 @@ +# DataShare Overview + +## Introduction + +The **DataShare** module allows an application to manage its own data and share data with other applications. Currently, data can be shared only between the applications on the same device. + +**DataShare** is used in application scenarios, such as contacts, short message service (SMS), and media gallery. However, not all data, such as accounts and passwords, can be accessed by other applications. Some data, such as SMS messages, can only be queried by other applications. **DataShare** provides a secure data sharing mechanism for applications. + +The data provider can directly use the **DataShare** framework to share data with other applications without complex encapsulation. The data consumer only needs to learn and use a set of interfaces because the data access mode does not vary with the data provisioning mode. This greatly reduces the learning time and development difficulty. + +## Basic Concepts + + +Before you get started, familiarize yourself with the following concepts: + + +- Data provider + + An application that provides data and implements related services. It is also called a producer or server. + +- Data consumer + + An application that accesses the data or services provided by a data provider. It is also called a client. + +- Value bucket (**ValuesBucket**) + + One or more data records stored in the form of key-value (KV) pairs. The keys are of the string type. The values can be of the number, string, Boolean, or Unit8Array type. + +- Result set + + A collection of query results. Flexible data access modes are provided for users to obtain data. + +- Predicate + + Conditions specified for updating, deleting, or querying data in the database. + +## Working Principles + +**Figure 1** DataShare mechanism + + +![](figures/en_DataShare.png) + +- The **DataShareExtAbility** module, as the data provider, implements data sharing between applications. +- The **DataShareHelper** module, as the data consumer, provides interfaces for accessing data, including adding, deleting, modifying, and querying data. +- The data consumer communicates with the data provider using inter-process communication (IPC). The data provider can be implemented through a database or other data storage. + +- The **ResultSet** module is implemented through shared memory. Share memory stores the result sets, and interfaces are provided to traverse result sets. + +## Constraints + +- **DataShare** is subject to the limitations on the database used by the data provider. For example, the supported data models, length of the keys and values, and maximum number of databases that can be accessed at a time by each application vary with the database in use. + +- The payloads of **ValuesBucket**, predicates, and result sets are restricted by IPC. diff --git a/en/application-dev/database/figures/en_DataShare.png b/en/application-dev/database/figures/en_DataShare.png new file mode 100644 index 0000000000000000000000000000000000000000..e0243b935e8cc61d61c5f572a20c66aadc5edbd3 Binary files /dev/null and b/en/application-dev/database/figures/en_DataShare.png differ diff --git a/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md b/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md index 6adaa00f48cfb7f2e685841e013e3d719bc58548..82935f9623b2cfb1878112aa2b7a8b27564f7ec7 100644 --- a/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md +++ b/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md @@ -1,6 +1,6 @@ # Data Share Result Set -The **DataShareResultSet** module provides methods for accessing the result set obtained from the database. You can access the values in the specified rows or the value of the specified data type. +The **DataShareResultSet** module provides APIs for accessing the result set obtained from the database. You can access the values in the specified rows or the value of the specified data type. >**NOTE** > @@ -13,7 +13,7 @@ The **DataShareResultSet** module provides methods for accessing the result set import DataShareResultSet from '@ohos.data.DataShareResultSet'; ``` -## How to Use +## Usage You can call [query()](js-apis-data-dataShare.md#query) to obtain the **DataShareResultSet** object. @@ -179,7 +179,7 @@ Moves to the specified row in the result set. | **Name**| **Type**| **Mandatory**| Description | | ---------- | -------- | -------- | ------------------------ | -| position | number | Yes | Destination position to move.| +| position | number | Yes | Destination position to move to.| **Return value** @@ -199,7 +199,7 @@ console.info('resultSet.goToRow: ' + isGoToRow); getBlob(columnIndex: number): Uint8Array -Obtains the value in the specified column in the current row as a byte array. +Obtains the value in the form of a byte array based on the specified column and the current row. **System capability**: SystemCapability.DistributedDataManager.DataShare.Core @@ -228,7 +228,7 @@ console.info('resultSet.getBlob: ' + getBlob); getString(columnIndex: number): *string* -Obtains the value in the specified column in the current row as a string. +Obtains the value in the form of a string based on the specified column and the current row. **System capability**: SystemCapability.DistributedDataManager.DataShare.Core @@ -257,7 +257,7 @@ console.info('resultSet.getString: ' + getString); getLong(columnIndex: number): number -Obtains the value in the specified column in the current row as a long integer. +Obtains the value in the form of a long integer based on the specified column and the current row. **System capability**: SystemCapability.DistributedDataManager.DataShare.Core @@ -286,7 +286,7 @@ console.info('resultSet.getLong: ' + getLong); getDouble(columnIndex: number): number -Obtains the value in the specified column in the current row as a double-precision floating-point number. +Obtains the value in the form of a double-precision floating-point number based on the specified column and the current row. **System capability**: SystemCapability.DistributedDataManager.DataShare.Core