diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 4646544abd6e22a632a35faeba6184819d601097..9f818cacd2d6a4120fa2517f94c7845394ed63ce 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -13,6 +13,7 @@ - [@ohos.application.appManager](js-apis-appmanager.md) - [@ohos.application.Configuration](js-apis-configuration.md) - [@ohos.application.ConfigurationConstant](js-apis-configurationconstant.md) + - [@ohos.application.DataShareExtensionAbility](js-apis-application-DataShareExtensionAbility.md) - [@ohos.ability.featureAbility](js-apis-featureAbility.md) - [@ohos.application.formBindingData](js-apis-formbindingdata.md) - [@ohos.application.FormExtension](js-apis-formextension.md) @@ -121,11 +122,14 @@ - Data Management - [@ohos.data.dataAbility ](js-apis-data-ability.md) + - [@ohos.data.dataShare](js-apis-data-dataShare.md) + - [@ohos.data.dataSharePredicates](js-apis-data-dataSharePredicates.md) + - [@ohos.data.dataShareResultSet](js-apis-data-DataShareResultSet.md) - [@ohos.data.distributedData](js-apis-distributed-data.md) - [@ohos.data.distributedDataObject](js-apis-data-distributedobject.md) - [@ohos.data.preferences](js-apis-data-preferences.md) - [@ohos.data.rdb](js-apis-data-rdb.md) - - [@ohos.settings](js-apis-settings.md) + - [@ohos.data.ValuesBucket](js-apis-data-ValuesBucket.md) - data/rdb/[resultSet](js-apis-data-resultset.md) - File Management @@ -205,6 +209,7 @@ - [@ohos.power](js-apis-power.md) - [@ohos.runningLock](js-apis-runninglock.md) - [@ohos.sensor](js-apis-sensor.md) + - [@ohos.settings](js-apis-settings.md) - [@ohos.systemParameter](js-apis-system-parameter.md) - [@ohos.thermal](js-apis-thermal.md) - [@ohos.update](js-apis-update.md) diff --git a/en/application-dev/reference/apis/js-apis-application-DataShareExtensionAbility.md b/en/application-dev/reference/apis/js-apis-application-DataShareExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..c3dd60f0e942f6666ea4023bca50c0cef7e75fa5 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-DataShareExtensionAbility.md @@ -0,0 +1,376 @@ +# Data Share Extension Ability + +**DataShareExtensionAbility** provides extension abilities for data share services based on the ExtensionAbility framework. + +>**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. +> +>The APIs of this module can be used only in the stage model. + + +## Modules to Import + +```ts +import DataShareExtensionAbility from '@ohos.application.DataShareExtensionAbility' +``` + +## onCreate + +onCreate?(want: Want, callback: AsyncCallback<void>): void + +Called to initialize service logic of the server when the DataShare client connects to the DataShareExtensionAbility server. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----- | ------ | ------ | ------ | +| want | [Want](js-apis-application-Want.md#want) | Yes | **Want** information, including the ability name and bundle name.| +| callback | AsyncCallback<void> | Yes| Callback that returns no value.| + +**Example** + +```ts +import rdb from '@ohos.data.rdb'; + +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, phoneNumber DOUBLE, isStudent BOOLEAN, Binary BINARY)"; +let rdbStore; + +export default class DataShareExtAbility extends DataShareExtensionAbility { + onCreate(want: Want, callback: AsyncCallback) { + rdb.getRdbStore(this.context, { + name: DB_NAME + }, 1, function (err, data) { + console.log('getRdbStore done, data : ' + data); + rdbStore = data; + rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) { + console.log('executeSql done, error message : ' + err); + }); + if (callback) { + callback(); + } + }); + } +}; +``` + +## getFileTypes + +getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void + +Called by the server to obtain the Multipurpose Internet Mail Extensions (MIME) types supported by a file. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ---------------------------------------- | ---- | ---------------------------------- | +| uri | string | Yes | URI of the file. | +| mimeTypeFilter | string | Yes | MIME types to match. | +| callback | AsyncCallback<Array<string>> | Yes | Callback invoked to return the MIME types obtained.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + getFileTypes(uri: string, mimeTypeFilter: string, callback: AsyncCallback>) { + let err = {"code":0}; + let ret = new Array("type01", "type02", "type03"); + callback(err, ret); + } +}; +``` + +## openFile + +openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void + +Called by the server to open a file. This method can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ------------------------------------------ | +| uri | string | Yes | URI of the file to open. | +| mode | string | Yes | File open mode, including read-only mode and read/write mode.| +| callback | AsyncCallback<number> | Yes | Callback invoked to return the file descriptor. | + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + openFile(uri: string, mode: string, callback: AsyncCallback) { + let err = {"code":0}; + let fd = 0; + callback(err,fd); + } +}; +``` + +## insert + +insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void + +Called to insert data into the database. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----- | ------ | ------ | ------ | +| uri |string | Yes | URI of the data to insert.| +| valueBucket |[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes| Data to insert.| +| callback |AsyncCallback<number> | Yes| Callback invoked to return the index of the data inserted.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + insert(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback) { + if (value == null) { + console.info('invalid valueBuckets'); + return; + } + rdbStore.insert(TBL_NAME, value, function (err, ret) { + console.info('callback ret:' + ret); + if (callback != undefined) { + callback(err, ret); + } + }); + } +}; +``` + +## update + +update?(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void + +Called by the server to update data in the database. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----- | ------ | ------ | ------ | +| uri | string | Yes | URI of the data to update.| +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for updating data.| +| valueBucket | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes| New data.| +| callback | AsyncCallback<number> | Yes| Callback invoked to return the number of updated data records.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + update(uri: string, predicates: dataSharePredicates.DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback) { + if (predicates == null || predicates == undefined) { + return; + } + rdbStore.update(TBL_NAME, value, predicates, function (err, ret) { + if (callback != undefined) { + callback(err, ret); + } + }); + } +}; +``` + +## delete + +delete?(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void + +Called by the server to delete data from the database. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ---------------------------------- | +| uri | string | Yes | URI of the data to delete. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for deleting data. | +| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of data records deleted.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback) { + if (predicates == null || predicates == undefined) { + return; + } + rdbStore.delete(TBL_NAME, predicates, function (err, ret) { + if (callback != undefined) { + callback(err, ret); + } + }); + } +}; +``` + +## query + +query?(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void + +Called by the server to query data from the database. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----- | ------ | ------ | ------ | +| uri | string | Yes | URI of the data to query.| +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria for querying data.| +| columns | Array<string> | Yes| Columns to query. If this parameter is empty, all columns will be queried.| +| callback | AsyncCallback<Object> | Yes| Callback invoked to return the result set.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array, callback: AsyncCallback) { + if (predicates == null || predicates == undefined) { + return; + } + rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) { + if (resultSet != undefined) { + console.info('resultSet.rowCount: ' + resultSet.rowCount); + } + if (callback != undefined) { + callback(err, resultSet); + } + }); + } +}; +``` + +## getType + +getType?(uri: string, callback: AsyncCallback<string>): void + +Called by the server to obtain the MIME type corresponding to the given URI. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name| Type| Mandatory| Description| +| ----- | ------ | ------ | ------ | +| uri | string | Yes | URI of the target data.| +| callback | AsyncCallback<string> | Yes| Callback invoked to return the MIME type obtained.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + getType(uri: string, callback: AsyncCallback) { + let err = {"code":0}; + let ret = "image"; + callback(err, ret); + } +}; +``` + +## BatchInsert + +BatchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void + +Called by the server to insert batch data into the database. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------------ | ------------------------------------------------------------ | ---- | -------------------------------- | +| uri | string | Yes | URI of the data to insert. | +| valueBuckets | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | Yes | Data to insert. | +| callback | AsyncCallback<number> | Yes | Callback invoked to return the number of inserted data records.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + batchInsert(uri: string, valueBuckets: Array, callback: AsyncCallback) { + if (valueBuckets == null || valueBuckets.length == undefined) { + console.info('invalid valueBuckets'); + return; + } + let resultNum = valueBuckets.length + valueBuckets.forEach(vb => { + rdbStore.insert(TBL_NAME, vb, function (err, ret) { + if (callback != undefined) { + callback(err, resultNum); + } + }); + }); + } +}; +``` + +## normalizeUri + +normalizeUri?(uri: string, callback: AsyncCallback<string>): void + +Called by the server to normalize the specified URI. This API can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ----------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to normalize.| +| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, the normalized URI is returned. Otherwise, **null** is returned.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + normalizeUri(uri: string, callback: AsyncCallback) { + let err = {"code":0}; + let ret = "normalize+" + uri; + callback(err, ret); + } +}; +``` + +## denormalizeUri + +denormalizeUri?(uri: string, callback: AsyncCallback<string>): void + +Called by the server to denormalize the specified URI. This method can be overridden as required. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Provider + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ----------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to denormalize.| +| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, the URI obtained is returned. If the URI passed in is returned, denormalization is not required. If denormalization is not supported, **null** is returned.| + +**Example** + +```ts +export default class DataShareExtAbility extends DataShareExtensionAbility { + denormalizeUri(uri: string, callback: AsyncCallback) { + let err = {"code":0}; + let ret = "denormalize+" + uri; + callback(err, ret); + } +}; +``` diff --git a/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md b/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md new file mode 100644 index 0000000000000000000000000000000000000000..6adaa00f48cfb7f2e685841e013e3d719bc58548 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-data-DataShareResultSet.md @@ -0,0 +1,424 @@ +# 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. + +>**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. + + +## Modules to Import + +```ts +import DataShareResultSet from '@ohos.data.DataShareResultSet'; +``` + +## How to Use + +You can call [query()](js-apis-data-dataShare.md#query) to obtain the **DataShareResultSet** object. + +```ts +import dataShare from '@ohos.data.dataShare'; +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let dataShareHelper; +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +await dataShare.createDataShareHelper(this.context, uri, (err, data) => { + if (err != undefined) { + console.info("createDataShareHelper fail, error message : " + err); + } else { + console.info("createDataShareHelper end, data : " + data); + dataShareHelper = data; + } +}); + +let columns = ["*"]; +let da = new dataSharePredicates.DataSharePredicates(); +let resultSet; +da.equalTo("name", "ZhangSan"); +dataShareHelper.query(uri, da, columns).then((data) => { + console.log("query end, data : " + data); + resultSet = data; +}).catch((err) => { + console.log("query fail, error message : " + err); +}); +``` + +## Attributes + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +| Name | Type | Mandatory| Description | +| ----------- | ------------- | ---- | ------------------------ | +| columnNames | Array<string> | Yes | Names of all columns in the result set. | +| columnCount | number | Yes | Number of columns in the result set. | +| rowCount | number | Yes | Number of rows in the result set. | +| isClosed | boolean | Yes | Whether the result set is closed.| + +## goToFirstRow + +goToFirstRow(): boolean + +Moves to the first row of the result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| :------ | --------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let isGoTOFirstRow = resultSet.goToFirstRow(); +console.info('resultSet.goToFirstRow: ' + isGoTOFirstRow); +``` + +## goToLastRow + +goToLastRow(): boolean + +Moves to the last row of the result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let isGoToLastRow = resultSet.goToLastRow(); +console.info('resultSet.goToLastRow: ' + isGoToLastRow); +``` + +## goToNextRow + +goToNextRow(): boolean + +Moves to the next row in the result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------- | --------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let isGoToNextRow = resultSet.goToNextRow(); +console.info('resultSet.goToNextRow: ' + isGoToNextRow); +``` + +## goToPreviousRow + +goToPreviousRow(): boolean + +Moves to the previous row in the result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------- | --------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let isGoToPreviousRow = resultSet.goToPreviousRow(); +console.info('resultSet.goToPreviousRow: ' + isGoToPreviousRow); +``` + +## goTo + +goTo(offset:number): boolean + +Moves based on the specified offset. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name**| **Type**| **Mandatory**| Description | +| ---------- | -------- | -------- | ------------------------------------------------------------ | +| offset | number | Yes | Offset relative to the current position. A negative value means to move backward, and a positive value means to move forward.| + +**Return value** + +| Type | Description | +| ------- | --------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let goToNum = 1; +let isGoTo = resultSet.goTo(goToNum); +console.info('resultSet.goTo: ' + isGoTo); +``` + +## goToRow + +goToRow(position: number): boolean + +Moves to the specified row in the result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name**| **Type**| **Mandatory**| Description | +| ---------- | -------- | -------- | ------------------------ | +| position | number | Yes | Destination position to move.| + +**Return value** + +| Type | Description | +| ------- | --------------------------------------------- | +| boolean | Returns **true** if the operation is successful; returns **false** otherwise.| + +**Example** + +```ts +let goToRowNum = 2 +let isGoToRow = resultSet.goToRow(goToRowNum); +console.info('resultSet.goToRow: ' + isGoToRow); +``` + +## getBlob + +getBlob(columnIndex: number): Uint8Array + +Obtains the value in the specified column in the current row as a byte array. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | ----------------------- | +| columnIndex | number | Yes | Index of the target column, starting from 0.| + +**Return value** + +| Type | Description | +| ---------- | -------------------------------- | +| Uint8Array | Value obtained.| + +**Example** + +```ts +let columnIndex = 1 +let goToFirstRow = resultSet.goToFirstRow(); +let getBlob = resultSet.getBlob(columnIndex); +console.info('resultSet.getBlob: ' + getBlob); +``` + +## getString + +getString(columnIndex: number): *string* + +Obtains the value in the specified column in the current row as a string. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | ----------------------- | +| columnIndex | number | Yes | Index of the target column, starting from 0.| + +**Return value** + +| Type | Description | +| ------ | ---------------------------- | +| string | Value obtained.| + +**Example** + +```ts +let columnIndex = 1 +let goToFirstRow = resultSet.goToFirstRow(); +let getString = resultSet.getString(columnIndex); +console.info('resultSet.getString: ' + getString); +``` + +## getLong + +getLong(columnIndex: number): number + +Obtains the value in the specified column in the current row as a long integer. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | ----------------------- | +| columnIndex | number | Yes | Index of the target column, starting from 0.| + +**Return value** + +| Type | Description | +| ------ | -------------------------- | +| number | Value obtained.| + +**Example** + +```ts +let columnIndex = 1 +let goToFirstRow = resultSet.goToFirstRow(); +let getLong = resultSet.getLong(columnIndex); +console.info('resultSet.getLong: ' + getLong); +``` + +## getDouble + +getDouble(columnIndex: number): number + +Obtains the value in the specified column in the current row as a double-precision floating-point number. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | ----------------------- | +| columnIndex | number | Yes | Index of the target column, starting from 0.| + +**Return value** + +| Type | Description | +| ------ | ---------------------------- | +| number | Value obtained.| + +**Example** + +```ts +let columnIndex = 1 +let goToFirstRow = resultSet.goToFirstRow(); +let getDouble = resultSet.getDouble(columnIndex); +console.info('resultSet.getDouble: ' + getDouble); +``` + +## close + +close(): void + +Closes this result set. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Example** + +```ts +resultSet.close(); +``` + +## getColumnIndex + +getColumnIndex(columnName: string): number + +Obtains the column index based on the column name. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name**| **Type**| **Mandatory**| Description | +| ---------- | -------- | -------- | -------------------------- | +| columnName | string | Yes | Column name.| + +**Return value** + +| Type | Description | +| ------ | ------------------ | +| number | Column index obtained.| + +**Example** + +```ts +let ColumnName = "name" +let getColumnIndex = resultSet.getColumnIndex(ColumnName) +console.info('resultSet.getColumnIndex: ' + getColumnIndex); +``` + +## getColumnName + +getColumnName(columnIndex: number): *string* + +Obtains the column name based on the column index. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | -------------------------- | +| columnIndex | number | Yes | Column index.| + +**Return value** + +| Type | Description | +| ------ | ------------------ | +| string | Column name obtained.| + +**Example** + +```ts +let columnIndex = 1 +let getColumnName = resultSet.getColumnName(columnIndex) +console.info('resultSet.getColumnName: ' + getColumnName); +``` + +## getDataType + +getDataType(columnIndex: number): DataType + +Obtains the data type based on the specified column index. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| **Name** | **Type**| **Mandatory**| Description | +| ----------- | -------- | -------- | -------------------------- | +| columnIndex | number | Yes | Column index.| + +**Return value** + +| Type | Description | +| --------------------- | ------------------ | +| [DataType](#datatype) | Data type obtained.| + +**Example** + +```ts +let columnIndex = 1; +let getDataType = resultSet.getDataType(columnIndex); +console.info('resultSet.getDataType: ' + getDataType); +``` + +## DataType + +Enumerates the data types. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +| Name | Value| Description | +| ----------- | ------ | -------------------- | +| TYPE_NULL | 0 | Null. | +| TYPE_LONG | 1 | Long integer. | +| TYPE_DOUBLE | 2 | Double-precision floating-point number.| +| TYPE_STRING | 3 | String.| +| TYPE_BLOB | 4 | Byte array.| diff --git a/en/application-dev/reference/apis/js-apis-data-ValuesBucket.md b/en/application-dev/reference/apis/js-apis-data-ValuesBucket.md new file mode 100644 index 0000000000000000000000000000000000000000..b0666612257857244fdffc8462cfd9719883412a --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-data-ValuesBucket.md @@ -0,0 +1,37 @@ +# Value Bucket + +The **ValueBucket** holds data in key-value (KV) pairs. You can use it to insert data into a database. + +>**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. + + +## Modules to Import + +```ts +import { ValueType } from '@ohos.data.ValuesBucket'; +import { ValuesBucket } from '@ohos.data.ValuesBucket'; +``` + +## ValueType + +Enumerates the value types allowed by the database. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +| Name | Description | +| ------- | -------------------- | +| number | The value is a number. | +| string | The value is a string.| +| boolean | The value is of Boolean type.| + +## ValuesBucket + +Holds a set of KV pairs. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +| Name | Type | Mandatory| Description | +| ------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| [key: string] | [ValueType](#valuetype)\| Uint8Array \| null | Yes | KV pairs in a **ValuesBucket**. The key is of the string type. The value can be a number, string, Boolean value, Unit8Array, or **null**.| diff --git a/en/application-dev/reference/apis/js-apis-data-dataShare.md b/en/application-dev/reference/apis/js-apis-data-dataShare.md new file mode 100644 index 0000000000000000000000000000000000000000..14465e3daf5fe8e25a53ae3987dbb889a1f4dc23 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-data-dataShare.md @@ -0,0 +1,907 @@ +# Data Sharing + +The **DataShare** module allows applications to manage their own data and supports data sharing between applications on the same device. + +>**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. + + +## Modules to Import + +```ts +import Ability from '@ohos.application.Ability' +import dataShare from '@ohos.data.dataShare' +``` + + +## dataShare.createDataShareHelper + +createDataShareHelper(context: Context, uri: string, callback: AsyncCallback<DataShareHelper>): void + +Creates a **DataShareHelper** instance. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| context | [Context](js-apis-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.| + +**Example** + +```ts +import dataShare from '@ohos.data.dataShare' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let dataShareHelper; +dataShare.createDataShareHelper(this.context, uri, (err, data) => { + if (err != undefined) { + console.info("createDataShareHelper failed, error message : " + err); + } else { + console.info("createDataShareHelper succeed, data : " + data); + dataShareHelper = data; + } +}); +``` + +## dataShare.createDataShareHelper + +createDataShareHelper(context: Context, uri: string): Promise<DataShareHelper> + +Creates a **DataShareHelper** instance. This API uses a promise to return the result. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------------------------------------------------- | ---- | ------------------------------ | +| context | [Context](js-apis-application-context.md#context) | Yes | Context of an application. | +| uri | string | Yes | URI of the server application to connect.| + +**Return value** + +| Type | Description | +| -------------------------------------------------- | -------------------------------------- | +| Promise<[DataShareHelper](#datasharehelper)> | Promise used to return the **DataShareHelper** instance created.| + +**Example** + +```ts +import dataShare from '@ohos.data.dataShare' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let dataShareHelper; +dataShare.createDataShareHelper(this.context, uri).then((data) => { + console.info("createDataShareHelper succeed, data : " + data); + dataShareHelper = data; +}).catch((err) => { + console.info("createDataShareHelper failed, error message : " + err); +}) +``` + +## DataShareHelper + +Provides a **DataShareHelper** instance to access or manage data on the server. Before invoking any method provided by **DataShareHelper**, you must create a **DataShareHelper** instance using [createDataShareHelper](#datasharecreatedatasharehelper). + +### openFile + +openFile(uri: string, mode: string, callback: AsyncCallback<number>): void + +Opens a file. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ---------------------------------- | +| uri | string | Yes | URI of the file to open. | +| mode | string | Yes | File open mode.
**r** means to open a file for reading; **w** means to open a file for writing (erasing any data in the file); **wa** means to open a file in append mode for writing at the end of the file; **rw** means to open a file for both reading and writing.| +| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the file descriptor. Otherwise, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.openFile(uri, "rwt", (err, data) => { + if (err != undefined) { + console.info("openFile failed, error message : " + err); + }else { + console.info("openFile succeed, data : " + data); + let fd = data; + } +}); +``` + +### openFile + +openFile(uri: string, mode: string): Promise<number> + +Opens a file. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the file to open. | +| mode | string | Yes | File open mode.
**r** means to open a file for reading; **w** means to open a file for writing (erasing any data in the file); **wa** means to open a file in append mode for writing at the end of the file; **rw** means to open a file for both reading and writing.| + +**Return value** + +| Type | Description | +| --------------- | ---------------- | +| Promise<number> | Promise used to return the file descriptor.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.openFile(uri, "rwt").then((data) => { + console.info("openFile succeed, data : " + data); + let fd = data; +}).catch((err) => { + console.info("openFile failed, error message : " + err); +}) +``` + +### on('dataChange') + +on(type: 'dataChange', uri: string, callback: AsyncCallback<void>): void + +Subscribes to changes of the specified data. After an observer is registered, the subscriber will receive a notification when the change notification is triggered (the **notifyChange()** method is called). This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------ | +| type | string | Yes | Event type to subscribe to. The value is **dataChange**, which indicates data change events.| +| uri | string | Yes | URI of the data.| +| callback | AsyncCallback<void> | Yes | Called when the change notification is triggered. In this case, **err** is **undefined**. Otherwise, it is not called or **err** is an error object.| + +**Example** + +```ts +function onCallback() { + console.info("**** Observer on callback ****"); +} +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.on("dataChange", uri, onCallback); +``` + +### off('dataChange') + +off(type: 'dataChange', uri: string, callback?: AsyncCallback<void>): void + +Unsubscribes from the changes of the specified data. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------ | +| 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 used to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.| + +**Example** + +```ts +function offCallback() { + console.info("**** Observer off callback ****"); +} +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.off("dataChange", uri, offCallback); +``` + +### insert + +insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void + +Inserts a single data record into the database. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to insert. | +| value | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes | Data to insert. If this parameter is empty, a blank row will be inserted. | +| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the index of the inserted data record. Otherwise, **err** is an error object.
The data index is not returned if the APIs of the database in use, for example, the key-value database (KVDB), do not support the return of indexes.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +const valueBucket = { + "name": "rose", + "age": 22, + "salary": 200.5, +} +dataShareHelper.insert(uri, valueBucket, (err, data) => { + if (err != undefined) { + console.log("insert failed, error message : " + err); + }else{ + console.log("insert succeed, data : " + data); + } +}); +``` + +### insert + +insert(uri: string, value: ValuesBucket): Promise<number> + +Inserts a single data record into the database. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | --------------------------------------------------------- | ---- | -------------------------------------------------- | +| uri | string | Yes | URI of the data to insert. | +| value | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes | Data to insert. If this parameter is empty, a blank row will be inserted.| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| Promise<number> | Promise used to return the index of the inserted data record.
The data index is not returned if the APIs of the database (for example, KVDB) in use do not support the return of indexes.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +const valueBucket = { + "name": "rose1", + "age": 221, + "salary": 20.5, +} +dataShareHelper.insert(uri, valueBucket).then((data) => { + console.log("insert succeed, data : " + data); +}).catch((err) => { + console.log("insert failed, error message : " + err); +}); +``` + +### delete + +delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void + +Deletes one or more data records from the database. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to delete. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **delete()** vary depending on the database used. For example, the KVDB supports only **inKeys**.| +| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of deleted data records. Otherwise, **err** is an error object.
The number of deleted data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +dataShareHelper.delete(uri, da, (err, data) => { + if (err != undefined) { + console.log("delete failed, error message : " + err); + }else{ + console.log("delete succeed, data : " + data); + } +}); +``` + +### delete + +delete(uri: string, predicates: dataSharePredicates.DataSharePredicates): Promise<number> + +Deletes one or more data records from the database. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to delete. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **delete()** vary depending on the database used. For example, the KVDB supports only **inKeys**.| + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| Promise<number> | Promise used to return the number of deleted data records.
The number of deleted data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +dataShareHelper.delete(uri, da).then((data) => { + console.log("delete succeed, data : " + data); +}).catch((err) => { + console.log("delete failed, error message : " + err); +}); +``` + +### query + +query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void + +Queries data in the database. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to query. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **query()** vary depending on the database used. For example, the KVDB supports only **inKeys** and **prefixKey**.| +| columns | Array<string> | Yes | Columns to query. If this parameter is empty, all columns will be queried. | +| callback | AsyncCallback<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the result set obtained. Otherwise, **err** is an error object.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let columns = ["*"]; +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +dataShareHelper.query(uri, da, columns, (err, data) => { + if (err != undefined) { + console.log("query failed, error message : " + err); + }else{ + console.log("query succeed, rowCount : " + data.rowCount); + } +}); +``` + +### query + +query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>): Promise<DataShareResultSet> + +Queries data in the database. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to query. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **query()** vary depending on the database used. For example, the KVDB supports only **inKeys** and **prefixKey**.| +| columns | Array<string> | Yes | Columns to query. If this parameter is empty, all columns will be queried. | + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | --------------------------------- | +| Promise<[DataShareResultSet](js-apis-data-DataShareResultSet.md#datashareresultset)> | Promise used to return the result set obtained.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let columns = ["*"]; +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +dataShareHelper.query(uri, da, columns).then((data) => { + console.log("query succeed, rowCount : " + data.rowCount); +}).catch((err) => { + console.log("query failed, error message : " + err); +}); +``` + +### update + +update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void + +Updates data in the database. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to update. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **update()** vary depending on the database used. For example, only the relational database (RDB) supports predicates.| +| value | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes | New data. | +| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of updated data records. Otherwise, **err** is an error object.
The number of updated data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +const va = { + "name": "roe1", + "age": 21, + "salary": 20.5, + +} +dataShareHelper.update(uri, da, va, (err, data) => { + if (err != undefined) { + console.log("update failed, error message : " + err); + }else{ + console.log("update succeed, data : " + data); + } +}); +``` + +### update + +update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket): Promise<number> + +Updates data in the database. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to update. | +| predicates | [DataSharePredicates](js-apis-data-DataSharePredicates.md#datasharepredicates) | Yes | Filter criteria.
The predicate methods supported by **update()** vary depending on the database used. For example, only the RDB supports predicates.| +| value | [ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket) | Yes | New data. | + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| Promise<number> | Promise used to return the number of data records updated.
The number of updated data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates' + +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let da = new dataSharePredicates.DataSharePredicates(); +da.equalTo("name", "ZhangSan"); +const va = { + "name": "roe1", + "age": 21, + "salary": 20.5, + +} +dataShareHelper.update(uri, da, va).then((data) => { + console.log("update succeed, data : " + data); +}).catch((err) => { + console.log("update failed, error message : " + err); +}); +``` + +### batchInsert + +batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void + +Inserts batch data into the database. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the data to insert. | +| values | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | Yes | Data to insert. | +| callback | AsyncCallback<number> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of data records inserted. Otherwise, **err** is an error object.
The number of inserted data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, + {"name": "roe12", "age": 21, "salary": 20.5,}, + {"name": "roe13", "age": 21, "salary": 20.5,}) +dataShareHelper.batchInsert(uri, vbs, (err, data) => { + if (err != undefined) { + console.log("batchInsert failed, error message : " + err); + }else{ + console.log("batchInsert succeed, data : " + data); + } +}); +``` + +### batchInsert + +batchInsert(uri: string, values: Array<ValuesBucket>): Promise<number> + +Inserts batch data into the database. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------ | ------------------------------------------------------------ | ---- | ------------------------ | +| uri | string | Yes | URI of the data to insert.| +| values | Array<[ValuesBucket](js-apis-data-ValuesBucket.md#valuesbucket)> | Yes | Data to insert. | + +**Return value** + +| Type | Description | +| ---------------- | ------------------------------------------------------------ | +| Promise<number> | Promise used to return the number of data records inserted.
The number of inserted data records is not returned if the APIs of the database (for example, KVDB) in use do not support it.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let vbs = new Array({"name": "roe11", "age": 21, "salary": 20.5,}, + {"name": "roe12", "age": 21, "salary": 20.5,}, + {"name": "roe13", "age": 21, "salary": 20.5,}) +dataShareHelper.batchInsert(uri, vbs).then((data) => { + console.log("batchInsert succeed, data : " + data); +}).catch((err) => { + console.log("batchInsert failed, error message : " + err); +}); +``` + +### getType + +getType(uri: string, callback: AsyncCallback<string>): void + +Obtains the Multipurpose Internet Mail Extensions (MIME) type of the specified data. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | --------------------------------------------- | +| uri | string | Yes | URI of the data. | +| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the MIME type obtained. Otherwise, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.getType(uri, (err, data)=>{ + if (err != undefined) { + console.log("getType failed, error message : " + err); + }else{ + console.log("getType succeed, data : " + data); + let result = data; + } +}); +``` + +### getType + +getType(uri: string): Promise<string> + +Obtains the MIME type of the specified data. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | -------------------- | +| uri | string | Yes | URI of the data.| + +**Return value** + +| Type | Description | +| ---------------- | ----------------------------------- | +| Promise<string> | Promise used to return the MIME type obtained.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.getType(uri).then((data) => { + console.log("getType succeed, data : " + data); +}).catch((err) => { + console.log("getType failed, error message : " + err); +}); +``` + +### getFileTypes + +getFileTypes(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void + +Obtains the supported MIME types. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the file. | +| mimeTypeFilter | string | Yes | MIME types to match. Example:
**\*/\***: obtain all supported types.
**image/\***: obtain the MIMEs with the main type of **image**.
**\*/jpg**: obtains the MIMEs with subtype of **jpg**.| +| callback | openFile(uri: string, mode: string, callback: AsyncCallback) { let err = {"code":0}; let fd = 0; callback(err,fd);}ts | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the MIME types obtained. Otherwise, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let mimeTypeFilter = "image/*"; +dataShareHelper.getFileTypes(uri, mimeTypeFilter, (err,data) => { + if (err != undefined) { + console.log("getFileTypes failed, error message : " + err); + }else{ + console.log("getFileTypes succeed, data : " + data); + } +}); +``` + +### getFileTypes + +getFileTypes(uri: string, mimeTypeFilter: string): Promise<Array<string>> + +Obtains the supported MIME types. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | ------------------------------------------------------------ | +| uri | string | Yes | URI of the file. | +| mimeTypeFilter | string | Yes | MIME types to match. Example:
**\*/\***: obtain all supported types.
**image/\***: obtain the MIMEs with the main type of **image**.
**\*/jpg**: obtains the MIMEs with subtype of **jpg**.| + +**Return value** + +| Type | Description | +| ------------------------ | ------------------------ | +| Promise<Array<string>> | Promise used to return the MIME types obtained.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +let mimeTypeFilter = "image/*"; +dataShareHelper.getFileTypes(uri, mimeTypeFilter).then((data) => { + console.log("getFileTypes succeed, data : " + data); +}).catch((err) => { + console.log("getFileTypes failed, error message : " + err); +}); +``` + +### normalizeUri + +normalizeUri(uri: string, callback: AsyncCallback<string>): void + +Normalizes a DataShare URI. The normalized URI can be used across devices, and the DataShare URI can be used only by the local device. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | -------------------------------------------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to normalize. | +| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the normalized URI (if **null** is returned, URI normalization is not supported). Otherwise, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.normalizeUri(uri, (err, data) => { + if (err != undefined) { + console.log("normalizeUri failed, error message : " + err); + }else{ + console.log("normalizeUri = " + data); + } +}); +``` + +### normalizeUri + +normalizeUri(uri: string): Promise<string> + +Normalizes a DataShare URI. The normalized URI can be used across devices, and the DataShare URI can be used only by the local device. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | ----------------------------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to normalize.| + +**Return value** + +| Type | Description | +| ---------------- | ---------------------------------------------- | +| Promise<string> | Promise used to return the result. If URI normalization is supported, the normalized URI is returned. Otherwise, **null** is returned.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.normalizeUri(uri).then((data) => { + console.log("normalizeUri = " + data); +}).catch((err) => { + console.log("normalizeUri failed, error message : " + err); +}); +``` + +### denormalizeUri + +denormalizeUri(uri: string, callback: AsyncCallback<string>): void + +Denormalizes a URI. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ---------------------- | ---- | --------------------------------------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to denormalize.| +| callback | AsyncCallback<string> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the URI obtained. If the original URI is returned, denormalization is not required. If **null** is returned, denormalization is not supported. If the operation fails, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.denormalizeUri(uri, (err, data) => { + if (err != undefined) { + console.log("denormalizeUri failed, error message : " + err); + }else{ + console.log("denormalizeUri = " + data); + } +}); +``` + +### denormalizeUri + +denormalizeUri(uri: string): Promise<string> + +Denormalizes a URI. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | ------------------------------------------- | +| uri | string | Yes | [URI](js-apis-uri.md#uri) to denormalize.| + +**Return value** + +| Type | Description | +| ---------------- | ----------------------------------------- | +| Promise<string> | Promise used to return the result. If the denormalization is successful, the URI obtained is returned. If no operation is required, the original URI is returned. If denormalization is not supported, **null** is returned.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.denormalizeUri(uri).then((data) => { + console.log("denormalizeUri = " + data); +}).catch((err) => { + console.log("denormalizeUri failed, error message : " + err); +}); +``` + +### notifyChange + +notifyChange(uri: string, callback: AsyncCallback<void>): void + +Notifies the registered observer of data changes. This API uses an asynchronous callback to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------- | ---- | ------------------------ | +| uri | string | Yes | URI of the data.| +| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. If the observer is notified of the data changes, **err** is **undefined**. Otherwise, **err** is an error object.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.notifyChange(uri, () => { + console.log("***** notifyChange *****"); +}); +``` + +### notifyChange + +notifyChange(uri: string): Promise<void> + +Notifies the registered observer of data changes. This API uses a promise to return the result. + +This API can be used only in the stage model. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Consumer + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------ | ---- | -------------------- | +| uri | string | Yes | URI of the data.| + +**Return value** + +| Type | Description | +| -------------- | --------------------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +let uri = ("datashare:///com.samples.datasharetest.DataShare"); +dataShareHelper.notifyChange(uri); +``` diff --git a/en/application-dev/reference/apis/js-apis-data-dataSharePredicates.md b/en/application-dev/reference/apis/js-apis-data-dataSharePredicates.md new file mode 100644 index 0000000000000000000000000000000000000000..16c1c1c7b622782a577719bae992d10b1f4634a0 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-data-dataSharePredicates.md @@ -0,0 +1,861 @@ +# Data Share Predicates + +You can use **DataSharePredicates** to specify conditions for [updating](js-apis-data-dataShare.md#update), [deleting](js-apis-data-dataShare.md#delete), and [querying](js-apis-data-dataShare.md#query) data with **DataShare**. + +>**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. + + +## Modules to Import + +```ts +import dataSharePredicates from '@ohos.data.dataSharePredicates'; +``` + +## equalTo + +equalTo(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value equal to the specified value. + +Currently, only the relational database (RDB) and key-value database (KVDB, schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "Rose") +``` + +## notEqualTo + +notEqualTo(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value not equal to the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.notEqualTo("NAME", "Rose") +``` + +## beginWrap + +beginWrap(): DataSharePredicates + +Adds a left parenthesis to this **DataSharePredicates**. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------------------------------------------- | ---------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with a left parenthesis.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "lisi") + .beginWrap() + .equalTo("AGE", 18) + .or() + .equalTo("SALARY", 200.5) + .endWrap() +``` + +## endWrap + +endWrap(): DataSharePredicates + +Adds a right parenthesis to this **DataSharePredicates** object. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------------------------------------------- | ---------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with a right parenthesis.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "lisi") + .beginWrap() + .equalTo("AGE", 18) + .or() + .equalTo("SALARY", 200.5) + .endWrap() +``` + +## or + +or(): DataSharePredicates + +Adds the OR condition to this **DataSharePredicates** object. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------------------------------------------- | ---------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with the OR condition.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "lisi") + .or() + .equalTo("NAME", "Rose") +``` + +## and + +and(): DataSharePredicates + +Adds the AND condition to this **DataSharePredicates** object. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------------------------------------------- | ---------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object with the AND condition.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "lisi") + .and() + .equalTo("SALARY", 200.5) +``` + +## contains + +contains(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match the string that contains the specified value. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | Value contained in the string.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.contains("NAME", "os") +``` + +## beginsWith + +beginsWith(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match a string that starts with the specified value. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | Start value of the string.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.beginsWith("NAME", "os") +``` + +## endsWith + +endsWith(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match a string that ends with the specified value. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | End value of the string.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.endsWith("NAME", "os") +``` + +## isNull + +isNull(field: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field whose value is null. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| field | string | Yes | Column name in the database table.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.isNull("NAME") +``` + +## isNotNull + +isNotNull(field: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field whose value is not null. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| field | string | Yes | Column name in the database table.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.isNotNull("NAME") +``` + +## like + +like(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match a string that is similar to the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.like("NAME", "%os%") +``` + +## unlike + +unlike(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match a string that is not similar to the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.unlike("NAME", "%os%") +``` + +## glob + +glob(field: string, value: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match the specified string. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | string | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified string.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.glob("NAME", "?h*g") +``` + +## between + +between(field: string, low: ValueType, high: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value within the specified range. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------- | ---- | ------------------------ | +| field | string | Yes | Column name in the database table. | +| low | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | The lowest value of the range.| +| high | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | The highest value of the range.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.between("AGE", 10, 50) +``` + +## notBetween + +notBetween(field: string, low: ValueType, high: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value out of the specified range. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------- | ---- | ------------------------ | +| field | string | Yes | Column name in the database table. | +| low | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | The lowest value of the range.| +| high | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | The highest value of the range.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.notBetween("AGE", 10, 50) +``` + +## greaterThan + +greaterThan(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value greater than the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | --------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.greaterThan("AGE", 10) +``` + +## lessThan + +lessThan(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value less than the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | --------------------------------------------------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.lessThan("AGE", 50) +``` + +## greaterThanOrEqualTo + +greaterThanOrEqualTo(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value greater than or equal to the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | --------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.greaterThanOrEqualTo("AGE", 10) +``` + +## lessThanOrEqualTo + +lessThanOrEqualTo(field: string, value: ValueType): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **ValueType** and value less than or equal to the specified value. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | --------- | ---- | ---------------------- | +| field | string | Yes | Column name in the database table. | +| value | [ValueType](js-apis-data-ValuesBucket.md#valuetype) | Yes | Value to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.lessThanOrEqualTo("AGE", 50) +``` + +## orderByAsc + +orderByAsc(field: string): DataSharePredicates + +Sets a **DataSharePredicates** object that sorts the values in a column in ascending order. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| field | string | Yes | Column name in the database table.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.orderByAsc("AGE") +``` + +## orderByDesc + +orderByDesc(field: string): DataSharePredicates + +Sets a **DataSharePredicates** object that sorts the values in a column in descending order. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| field | string | Yes | Column name in the database table.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.orderByDesc("AGE") +``` + +## distinct + +distinct(): DataSharePredicates + +Sets a **DataSharePredicates** object to filter out duplicate records. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "Rose").distinct() +``` + +## limit + +limit(total: number, offset: number): DataSharePredicates + +Sets a **DataSharePredicates** object to specify the number of results and the start position. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------ | ---- | -------------- | +| total | number | Yes | Number of results. | +| offset | number | Yes | Start position.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.equalTo("NAME", "Rose").limit(10, 3) +``` + +## groupBy + +groupBy(fields: Array<string>): DataSharePredicates + +Sets a **DataSharePredicates** object to group the records according to the specified parameters. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------- | ---- | -------------------- | +| fields | Array<string> | Yes | Names of the columns to group.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.groupBy(["AGE", "NAME"]) +``` + +## indexedBy + +indexedBy(field: string): DataSharePredicates + +Sets a **DataSharePredicates** object to specify the index column. Currently, only the RDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------- | +| field | string | Yes | Name of the index column.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.indexedBy("SALARY_INDEX") +``` + +## in + +in(field: string, value: Array<ValueType>): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **Array** and value within the specified range. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------- | ---- | --------------------------------------- | +| field | string | Yes| Column name in the database table. | +| value | Array<[ValueType](js-apis-data-ValuesBucket.md#valuetype)> | Yes | Array of **ValueType**s to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.in("AGE", [18, 20]) +``` + +## notIn + +notIn(field: string, value: Array<ValueType>): DataSharePredicates + +Sets a **DataSharePredicates** object to match the field with data type **Array** and value out of the specified range. + +Currently, only the RDB and KVDB (schema) support this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ---------------- | ---- | --------------------------------------- | +| field | string | Yes | Column name in the database table. | +| value | Array<[ValueType](js-apis-data-ValuesBucket.md#valuetype)> | Yes | Array of **ValueType**s to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.notIn("NAME", ["Lisa", "Rose"]) +``` + +## prefixKey + +prefixKey(prefix: string): DataSharePredicates + +Sets a **DataSharePredicates** object to match a field with the specified key prefix. Currently, only the KVDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | -------------- | +| prefix | string | Yes | Key prefix to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.prefixKey("NAME") +``` + +## inKeys + +inKeys(keys: Array<string>): DataSharePredicates + +Sets a **DataSharePredicates** object to match the fields whose keys are within the given range. Currently, only the KVDB supports this **DataSharePredicates** object. + +**System capability**: SystemCapability.DistributedDataManager.DataShare.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------- | ---- | ------------------ | +| inKeys | Array<string> | Yes | Array of the keys to match.| + +**Return value** + +| Type | Description | +| ------------------------------------------- | -------------------------- | +| [DataSharePredicates](#datasharepredicates) | **DataSharePredicates** object that matches the specified field.| + +**Example** + +```ts +let predicates = new dataSharePredicates.DataSharePredicates() +predicates.inKeys(["Lisa", "Rose"]) +``` diff --git a/en/application-dev/reference/apis/js-apis-privacyManager.md b/en/application-dev/reference/apis/js-apis-privacyManager.md index e06a5536a8754922e0e82d14162296124f498665..42cf66fea697004eafe45bc775146e0aa77ce8ad 100644 --- a/en/application-dev/reference/apis/js-apis-privacyManager.md +++ b/en/application-dev/reference/apis/js-apis-privacyManager.md @@ -1,11 +1,11 @@ # Privacy Management -Provides APIs for privacy management, such as management of permission usage records. +The **PrivacyManager** module provides APIs for privacy management, such as management of permission usage records. > **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 of this module are system APIs and cannot be called by third-party applications. +> +> 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 of this module are system APIs and cannot be called by third-party applications. ## Modules to Import @@ -19,7 +19,6 @@ import privacyManager from '@ohos.privacyManager'; addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number): Promise<number> Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses a promise to return the result. - The permission usage record includes the application identity of the invoker, name of the permission used, and number of successful and failed accesses to the application. **Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications) @@ -41,10 +40,6 @@ The permission usage record includes the application identity of the invoker, na | :------------ | :---------------------------------- | | Promise<number> | Promise used to return the result. If **0** is returned, the record is added successfully. If **-1** is returned, the record fails to be added.| -``` - -``` - **Example** ```js @@ -59,7 +54,6 @@ privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED addPermissionUsedRecord(tokenID: number, permissionName: string, successCount: number, failCount: number, callback: AsyncCallback<number>): void Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses an asynchronous callback to return the result. - The permission usage record includes the application identity of the invoker, name of the permission used, and number of successful and failed accesses to the application. **Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications) @@ -202,7 +196,7 @@ Represents the permission usage records of all applications. ## BundleUsedRecord -Represents the application access records of an application. +Represents the permission access records of an application. **System capability**: SystemCapability.Security.AccessToken @@ -212,11 +206,11 @@ Represents the application access records of an application. | isRemote | boolean | No | Whether the token ID belongs to a remote device. The default value is **false**.| | deviceId | string | No | ID of the device hosting the target application. | | bundleName | string | No | Bundle name of the target application.| -| permissionRecords | Array<[PermissionUsedRecord](#PermissionUsedRecord)> | No | Permission usage records of the specified application obtained. | +| permissionRecords | Array<[PermissionUsedRecord](#PermissionUsedRecord)> | No | Permission usage records of the target application. | ## PermissionUsedRecord -Represents the access records of a permission. +Represents the usage records of a permission. **System capability**: SystemCapability.Security.AccessToken @@ -225,8 +219,8 @@ Represents the access records of a permission. | permissionName | string | No | Name of the permission. | | accessCount | number | No | Total number of times that the permission is accessed.| | rejectCount | number | No | Total number of times that the access to the permission is rejected.| -| lastAccessTime | number | No | Last time when the permission was accessed, in ms.| -| lastRejectTime | number | No | Last time when the access to the permission was rejected, in ms.| +| lastAccessTime | number | No | Last time when the permission was accessed, accurate to ms.| +| lastRejectTime | number | No | Last time when the access to the permission was rejected, accurate to ms.| | lastAccessDuration | number | No | Last access duration, in ms.| | accessRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. | | rejectRecords | Array<[UsedRecordDetail](#usedrecorddetail)> | No | Rejected records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided. |