diff --git a/en/application-dev/database/database-datashare-guidelines.md b/en/application-dev/database/database-datashare-guidelines.md index 95001df839e0d5ef56bc12126f0fdcd59c72db30..654f099dad350ce1158c2bfd3f5b01b39d781d4b 100644 --- a/en/application-dev/database/database-datashare-guidelines.md +++ b/en/application-dev/database/database-datashare-guidelines.md @@ -13,7 +13,7 @@ The **DataShare** module allows an application to manage its own data and share |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 information, see [DataShareExtensionAbility](../reference/apis/js-apis-application-dataShareExtensionAbility.md). +For details about the data provider APIs, see [DataShareExtensionAbility](../reference/apis/js-apis-application-dataShareExtensionAbility.md). **Table 2** APIs of the data consumer @@ -29,7 +29,7 @@ For more information, see [DataShareHelper](../reference/apis/js-apis-data-dataS ## When to Use -There are two roles in **DataShare**: +There are two roles in **DataShare**: - Data provider: adds, deletes, modifies, and queries data, opens files, and shares data. - Data consumer: accesses the data provided by the provider using **DataShareHelper**. @@ -38,7 +38,47 @@ Examples are given below. ### Data Provider Application Development (Only for System Applications) -1. Import the dependencies. +[DataShareExtensionAbility](../reference/apis/js-apis-application-dataShareExtensionAbility.md) provides the following APIs. You can override the APIs as required. + +- **onCreate** + + Called by the server to initialize service logic when the **DataShare** client connects to the **DataShareExtensionAbility** server. + +- **insert** + + Inserts data. This API is called when the client requests to insert data. + +- **update** + + Updates data. This API is called when the client requests to update data. + +- **delete** + + Deletes data. This API is called when the client requests to delete data. + +- **query** + + Queries data. This API is called when the client requests to query data. + +- **batchInsert** + + Batch inserts data. This API is called when the client requests to batch insert data. + +- **normalizeUri** + + Converts the URI provided by the client to the URI used by the server. This API can be overridden as required. + +- **denormalizeUri** + + Converts the URI used by the server to the initial URI passed by the client. This API can be overridden as required. + +Before implementing a **DataShare** service, create a **DataShareExtensionAbility** object in the DevEco Studio project as follows: + +1. In the **ets** directory of the **Module** project, right-click and choose **New > Directory** to create a directory named **DataShareAbility**. + +2. Right-click the **DataShareAbility** directory, and choose **New > TypeScript File** to create a file named **DataShareAbility.ts**. + +3. In the **DataShareAbility.ts** file, import the **DataShareExtensionAbility** and other dependencies. ```ts import Extension from '@ohos.application.DataShareExtensionAbility'; @@ -47,9 +87,9 @@ Examples are given below. 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. +4. Override the **DataShareExtensionAbility** APIs based on actual requirements. For example, if the data provider provides only data query, override only **query()**. -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. +5. 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 const DB_NAME = "DB00.db"; @@ -63,11 +103,11 @@ Examples are given below. export default class DataShareExtAbility extends Extension { private rdbStore_; - - // Override the onCreate() API. + + // Override onCreate(). onCreate(want, callback) { result = this.context.cacheDir + '/datashare.txt' - // Create an RDB. + // Create an RDB store. rdb.getRdbStore(this.context, { name: DB_NAME }, 1, function (err, data) { @@ -79,7 +119,7 @@ Examples are given below. }); } - // Override the query() API. + // Override query(). query(uri, predicates, columns, callback) { if (predicates == null || predicates == undefined) { console.info('invalid predicates'); @@ -102,14 +142,17 @@ Examples are given below. }; ``` -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 data consumer to connect to the provider. | - | "visible" | Whether it is visible to other applications. Data sharing is allowed only when the value is **true**. | +6. 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 data consumer to connect to the provider. | + | "visible" | Whether it is visible to other applications. Data sharing is allowed only when the value is **true**. | + | | | **module.json5 example** @@ -127,6 +170,8 @@ Examples are given below. ] ``` + + ### Data Consumer Application Development 1. Import dependencies. @@ -136,20 +181,20 @@ Examples are given below. 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"); ``` - + 3. Create a **DataShareHelper** instance. ```ts let dsHelper; let abilityContext; - + export default class EntryAbility extends UIAbility { onWindowStageCreate(windowStage) { abilityContext = this.context; @@ -159,7 +204,7 @@ Examples are given below. } } ``` - + 4. Use the APIs provided by **DataShareHelper** to access the services provided by the provider, for example, adding, deleting, modifying, and querying data. ```ts @@ -180,9 +225,8 @@ Examples are given below. dsHelper.query(dseUri, predicates, valArray, (err, data) => { console.log("dsHelper query result: " + data); }); - // Delete specified data. + // Delete data. dsHelper.delete(dseUri, predicates, (err, data) => { - console.log("dsHelper delete result: " + data); + console.log("dsHelper delete result: " + data); }); ``` - diff --git a/en/application-dev/database/database-datashare-overview.md b/en/application-dev/database/database-datashare-overview.md index 019adeb3fa6850ed5407e0107d5996054ef11de7..53fbd723922ea602e694e0844d2486b13f48538c 100644 --- a/en/application-dev/database/database-datashare-overview.md +++ b/en/application-dev/database/database-datashare-overview.md @@ -4,6 +4,8 @@ The **DataShare** module allows an application to manage its own data and share data with other applications. Currently, data can be shared only between applications on the same device. +**DataShare** must be used together with [DataShareExtensionAbility](../reference/apis/js-apis-application-dataShareExtensionAbility.md). + Data needs to be shared in a wealth of scenarios. For example, contacts, short message service (SMS), and media gallery always needs to be shared. However, certain data, such as accounts and passwords, cannot be shared. Some data, such as SMS messages, can be queried but not modified by other applications. **DataShare** provides a secure data sharing mechanism for applications in a variety of scenarios. 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. @@ -16,22 +18,22 @@ 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. + The **DataShareExtensionAbility** based on the stage model implements functions, such as selectively adding, deleting, modifying, and querying data, and opening files. It implements services related to cross-application data sharing. - Data consumer - An application that accesses the data or services provided by a data provider. It is also called a client. + The data consumer uses **DataShareHelper**, a utility class created by [createDataShareHelper()](../reference/apis/js-apis-data-dataShare.md#datasharecreatedatasharehelper), to access the data provided by the data provider. - **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 @@ -41,7 +43,7 @@ Before you get started, familiarize yourself with the following concepts: ![](figures/en_DataShare.png) -- The **DataShareExtAbility** module, as the data provider, implements data sharing between applications. +- The **DataShareExtAbility** module, as the data provider, implements services related to 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. diff --git a/en/application-dev/database/figures/en_DataShare.png b/en/application-dev/database/figures/en_DataShare.png index e0243b935e8cc61d61c5f572a20c66aadc5edbd3..b56e96d3bb3ff338f082efd75959d9b15cea6a86 100644 Binary files a/en/application-dev/database/figures/en_DataShare.png and b/en/application-dev/database/figures/en_DataShare.png differ