@@ -4,12 +4,11 @@ The **DataShare** module allows an application to manage its own data and share
> **NOTE**
>
> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> The APIs provided by this module are system APIs.
>
> - The APIs provided by this module are system APIs.
>
> - The APIs of this module can be used only in the stage model.
> The APIs of this module can be used only in the stage model.
## Modules to Import
...
...
@@ -18,46 +17,74 @@ The **DataShare** module allows an application to manage its own data and share
-*Scheme*: scheme name, which has a fixed value of **datashare** for the **DataShare** module.
-*authority*: [userinfo@]host[:port]
-*userinfo*: login information, which can be left unspecified.
-*host*: server address. It is the target device ID for cross-device access and empty for local device access.
-*port*: port number of the server, which can be left unspecified.
-*path*: **DataShare** identifier and the resource path. The **DataShare** identifier is mandatory, and the resource path is optional.
Creates a **DataShareHelper** instance. This API uses an asynchronous callback to return the result.
Example:
Observe the following when using this API:
- If an application running in the background needs to call this API to access **DataShareExtension**, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **exported** of the target **DataShareExtension** is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
- URI without the resource path:<br>**datashare:///com.samples.datasharetest.DataShare**
| context | [Context](js-apis-inner-application-context.md#context) | Yes | Context of an application. |
| uri | string | Yes | Uniform Resource Identifier (URI) of the server application to connect. |
| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the **DataShareHelper** instance created. Otherwise, **err** is an error object.|
**Error codes**
## dataShare.createDataShareHelper
For details about the error codes, see [DataShare Error Codes](../errorcodes/errorcode-datashare.md).
Creates a **DataShareHelper** instance. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to access **DataShareExtension**, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target **DataShareExtension** is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target **DataShareExtension** is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
| context | [Context](js-apis-inner-application-context.md#context) | Yes | Context of an application. |
| uri | string | Yes | Uniform Resource Identifier (URI) of the server application to connect. |
| options | [DataShareHelperOptions](#datasharehelperoptions10)| Yes | Configuration specifying whether [DataShareHelper](#datasharehelper) is in proxy mode.|
| callback | AsyncCallback<[DataShareHelper](#datasharehelper)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the **DataShareHelper** instance created. Otherwise, **err** is an error object.|
**Error codes**
...
...
@@ -66,18 +93,18 @@ For details about the error codes, see [DataShare Error Codes](../errorcodes/err
Creates a **DataShareHelper** instance. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to access **DataShareExtension**, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target **DataShareExtension** is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- If **exported** of the target **DataShareExtension** is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
| context | [Context](js-apis-inner-application-context.md#context) | Yes | Context of an application. |
| uri | string | Yes | URI of the server application to connect.|
| uri | string | Yes | Uniform Resource Identifier (URI) of the server application to connect.|
| options | [DataShareHelperOptions](#datasharehelperoptions10) | No| Optional configuration of the **DataShareHelper** instance. This parameter is supported from API version 10. If it is not set, [DataShareHelper](#datasharehelper) is not in proxy mode.|
**Return value**
...
...
@@ -121,17 +148,17 @@ For details about the error codes, see [DataShare Error Codes](../errorcodes/err
| isProxy | boolean | No| Whether the [DataShareHelper](#datasharehelper) is in proxy mode. The default value is **false**.<br>If the value is **true**, the [DataShareHelper](#datasharehelper) to be created is in proxy mode, and all operations will not open the data provider application unless the database does not exist. If the database does not exist, [createDataShareHelper] (#datasharecreatedatasharehelper10) will start the data provider to create a database.|
## TemplateId<sup>10+</sup>
Defines the **TemplateId** struct. **TemplateId** is generated by [**addTemplate**](#addtemplate10) to identify a template.
| subscriberId | string | Yes| ID of the subscriber who handles the callback. The value must the same as the **subscriberId** in [**addTemplate**](#addtemplate10). The ID of each subscriber must be unique.|
| bundleNameOfOwner | string | Yes| Bundle name of the template owner. The value must be the same as the **bundleName** in [**addTemplate**](#addtemplate10).|
| predicates | { [key: string]: string } | Yes| Predicates to use. When [**on**](#onrdbdatachange10) is called, the predicates are used to generate data. This parameter applies only to RDB data storage. |
| scheduler | string | Yes| Template scheduler SQL, which is embedded with a custom function. Currently, the **remindTimer** function is embedded. The **remindTimer** triggers a subscription-based update in specified scenarios.<br>The scheduler SQL statement is triggered when:<br>1. The subscribed data is modified.<br>2. The first subscription is added to the corresponding database.|
## OperationResult<sup>10+</sup>
Defines the result of the operation for subscribing to or unsubscribing from the data changes or published data.
| key | string | Yes| Key of the operation result.|
| result | number | Yes| Operation result. |
## DataShareHelper
Provides a **DataShareHelper** instance to access or manage data on the server. Before calling an API provided by **DataShareHelper**, you must create a **DataShareHelper** instance using [createDataShareHelper](#datasharecreatedatasharehelper).
...
...
@@ -165,8 +269,6 @@ Subscribes to changes of the specified data. After an observer is registered, th
| type | string | Yes | Event type to unsubscribe from. The value is **dataChange**, which indicates data change events.|
| uri | string | Yes | URI of the data.|
| callback | AsyncCallback<void> | No | Callback for the data change event. If this parameter is left empty, all notification events of the URI are unsubscribed from.|
| type | string | Yes | Event or callback type to unsubscribe from. The value is **dataChange**, which indicates data change events.|
| uri | string | Yes | URI of the target data.|
| callback | AsyncCallback<void> | No | Callback for the data change event. If this parameter is left empty, all notification events of the URI will be unsubscribed from.|
| type | string | Yes | Type of the event to subscribe to. The value is **rdbDataChange**, which indicates the RDB data change event. |
| uris | Array<string> | Yes | URIs of the data to operate. |
| templateId | [TemplateId](#templateid10) | Yes | ID of the template that triggers the callback. |
| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | Yes | Callback invoked to return the result when the specified data changes. The **err** is **undefined**, and **node** is the new data. Otherwise, this callback is not triggered or **err** is an error object. |
| type | string | Yes | Type of the event to unsubscribe from. The value is **rdbDataChange**, which indicates the RDB data change event. |
| uris | Array<string> | Yes | URIs of the data to operate. |
| templateId | [TemplateId](#templateid10) | Yes | ID of the template that triggers the callback. |
| callback | AsyncCallback<[RdbDataChangeNode](#rdbdatachangenode10)> | No | Callback invoked to return the result. Callback for the data change event. If this parameter is left empty, all notification events of the URI will be unsubscribed from.|
| type | string | Yes | Type of the event to subscribe to. The value is **publishedDataChange**, which indicates the event of published data changes.|
| uris | Array<string> | Yes | URIs of the data to operate. |
| subscriberId | string | Yes | Subscriber ID of the callback. |
| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | Yes | Callback invoked to return the result when the published data changes. The **err** is **undefined**, and **node** is the new data. Otherwise, this callback is not triggered or **err** is an error object. |
| type | string | Yes | Type of the event to unsubscribe from. The value is **publishedDataChange**, which indicates the event of published data changes.|
| uris | Array<string> | Yes | URIs of the data to operate. |
| subscriberId | string | Yes | Subscriber ID of the callback. |
| callback | AsyncCallback<[PublishedDataChangeNode](#publisheddatachangenode10)> | No | Callback invoked to return the result. Callback for the published data change event. If this parameter is left empty, all notification events of the URI will be unsubscribed from.|
| data | Array<[PublishedItem](#publisheditem10)> | Yes | Data to publish. |
| bundleName | string | Yes | Application of the data to publish. This parameter is valid only for the private data published. Only the application can read the data. |
| version | number | Yes | Version of the data to publish. A larger value indicates a later data version. If the version of the data published is earlier than that of the data in the database, the data in the database will not be updated.|
| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | Yes | Callback invoked to return the result. If data is published, **err** is **undefined**, and **result** is the data publish result. Otherwise, this callback will not be triggered or **err** is an error object. |
**Error codes**
For details about the error codes, see [DataShare Error Codes](../errorcodes/errorcode-datashare.md).
| ID| Error Message |
| -------- | -------------------------- |
| 15700012 | The data area is not exist.|
**Example**
```ts
importrpcfrom'@ohos.rpc';
letashmem=null;
letsubscriberId='11';
letversion=1;
letdata:Array<dataShare.PublishedItem>=[
{key:"city",subscriberId:"11",data:"xian"},
{key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo",subscriberId:"11",data:"appinfo is just a test app"},
| data | Array<[PublishedItem](#publisheditem10)> | Yes | Data to publish. |
| bundleName | string | Yes | Application of the data to publish. This parameter is valid only for the private data published. Only the application can read the data. |
| callback | AsyncCallback<Array<[OperationResult](#operationresult10)>> | Yes | Callback invoked to return the result. If data is published, **err** is **undefined**, and **result** is the data publish result. Otherwise, this callback will not be triggered or **err** is an error object.|
**Example**
**Error codes**
For details about the error codes, see [DataShare Error Codes](../errorcodes/errorcode-datashare.md).
| data | Array<[PublishedItem](#publisheditem10)> | Yes | Data to publish.|
| bundleName | string | Yes | Application of the data to publish. This parameter is valid only for the private data published. Only the application can read the data. |
| version | number | No | Version of the data to publish. A larger value indicates a later data version. If the version of the data published is earlier than that of the data in the database, the data in the database will not be updated.<br> If the data version is not checked, leave this parameter unspecified.|
@@ -7,8 +7,7 @@ The APIs provided by **DataSharePredicates** correspond to the filter criteria
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> The APIs provided by this module are system APIs.
## Modules to Import
...
...
@@ -20,7 +19,7 @@ import dataSharePredicates from '@ohos.data.dataSharePredicates';
## DataSharePredicates
Provides methods for setting different **DataSharePredicates** objects. This type is not multi-thread safe. If a **DataSharePredicates** instance is operated by multiple threads at the same time in an application, use a lock for the instance.
@@ -4,8 +4,7 @@ The **ValueBucket** module holds data in key-value (KV) pairs. You can use it to
> **NOTE**
>
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
>
> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.