Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
提交 f1affe03 编写于 作者: A Annie_wang
浏览文件
操作

update docs 

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 dd816222
显示空白变更内容
内联 并排
Showing with 1618 addition and 111 deletion
en/application-dev/reference/apis/js-apis-data-preferences.md
浏览文件 @ f1affe03
......@@ -40,7 +40,7 @@ Obtains a **Preferences** instance. This API uses an asynchronous callback to re
| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and the **Preferences** instance obtained is returned. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and the **Preferences** instance obtained is returned. Otherwise, **err** is an error object.|
**Example**
......@@ -159,15 +159,166 @@ class EntryAbility extends UIAbility {
}
```
## data_preferences.getPreferences<sup>10+</sup>
getPreferences(context: Context, options: Options, callback: AsyncCallback&lt;Preferences&gt;): void
Obtains a **Preferences** instance. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
| callback | AsyncCallback&lt;[Preferences](#preferences)&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and the **Preferences** instance obtained is returned. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
let preferences = null;
try {
data_preferences.getPreferences(context, {name: 'mystore'}, function (err, val) {
if (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
return;
}
preferences = val;
console.info("Obtained the preferences successfully.");
})
} catch (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
let preferences = null;
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.getPreferences(this.context, {name: 'mystore', dataGroupId:'myId'}, function (err, val) {
if (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
return;
}
preferences = val;
console.info("Obtained the preferences successfully.");
})
} catch (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.getPreferences<sup>10+</sup>
getPreferences(context: Context, options: Options): Promise&lt;Preferences&gt;
Obtains a **Preferences** instance. This API uses a promise to return the result.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Return value**
| Type | Description |
| --------------------------------------- | ---------------------------------- |
| Promise&lt;[Preferences](#preferences)&gt; | Promise used to return the **Preferences** instance obtained.|
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
let preferences = null;
try {
let promise = data_preferences.getPreferences(context, {name: 'mystore'});
promise.then((object) => {
preferences = object;
console.info("Obtained the preferences successfully.");
}).catch((err) => {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
let preferences = null;
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
let promise = data_preferences.getPreferences(this.context, {name: 'mystore', dataGroupId:'myId'});
promise.then((object) => {
preferences = object;
console.info("Obtained the preferences successfully.");
}).catch((err) => {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.deletePreferences
deletePreferences(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
Deletes a **Preferences** instance from the memory. This API uses an asynchronous callback to return the result.
Deletes a **Preferences** instance from the cache. If the **Preferences** instance has a persistent file, the persistent file will also be deleted. This API uses an asynchronous callback to return the result.
If the **Preferences** instance has a persistent file, this API also deletes the persistent file.
The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
After the **Preferences** instance is deleted, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the deleted **Preferences** instance to null. The system will reclaim the deleted **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -176,8 +327,8 @@ The deleted **Preferences** instance cannot be used for data operations. Otherwi
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance to delete. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Error codes**
......@@ -235,11 +386,296 @@ class EntryAbility extends UIAbility {
deletePreferences(context: Context, name: string): Promise&lt;void&gt;
Deletes a **Preferences** instance from the memory. This API uses a promise to return the result.
Deletes a **Preferences** instance from the cache. If the **Preferences** instance has a persistent file, the persistent file will also be deleted. This API uses a promise to return the result.
If the **Preferences** instance has a persistent file, this API also deletes the persistent file.
After the **Preferences** instance is deleted, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the deleted **Preferences** instance to null. The system will reclaim the deleted **Preferences** instances in a unified manner.
The deleted **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------|
| 15500010 | Failed to delete preferences file. |
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
let promise = data_preferences.deletePreferences(context, 'mystore');
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try{
let promise = data_preferences.deletePreferences(this.context, 'mystore');
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.deletePreferences<sup>10+</sup>
deletePreferences(context: Context, options: Options, callback: AsyncCallback&lt;void&gt;): void
Deletes a **Preferences** instance from the cache. If the **Preferences** instance has a persistent file, the persistent file will also be deleted. This API uses an asynchronous callback to return the result.
After the **Preferences** instance is deleted, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the deleted **Preferences** instance to null. The system will reclaim the deleted **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ---------------------------------- |
| 15500010 | Failed to delete preferences file. |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.deletePreferences(context, {name: 'mystore'}, function (err) {
if (err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Deleted the preferences successfully." );
})
} catch (err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.deletePreferences(this.context, {name: 'mystore', dataGroupId:'myId'}, function (err) {
if (err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Deleted the preferences successfully." );
})
} catch (err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.deletePreferences<sup>10+</sup>
deletePreferences(context: Context, options: Options): Promise&lt;void&gt;
Deletes a **Preferences** instance from the cache. If the **Preferences** instance has a persistent file, the persistent file will also be deleted. This API uses a promise to return the result.
After the **Preferences** instance is deleted, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the deleted **Preferences** instance to null. The system will reclaim the deleted **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ---------------------------------- |
| 15500010 | Failed to delete preferences file. |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
let promise = data_preferences.deletePreferences(context, {name: 'mystore'});
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try{
let promise = data_preferences.deletePreferences(this.context, {name: 'mystore', dataGroupId:'myId'});
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCache
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
Removes a **Preferences** instance from the cache. This API uses an asynchronous callback to return the result.
After an application calls [getPreferences](#data_preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#data_preferencesgetpreferences) again, the **Preferences** instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling **getPreferences** again will read data from the persistent file and create a new **Preferences** instance.
After the **Preferences** instance is removed, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the removed **Preferences** instance to null. The system will reclaim the removed **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.removePreferencesFromCache(context, 'mystore', function (err) {
if (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Removed the preferences successfully.");
})
} catch (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) {
if (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Removed the preferences successfully.");
})
} catch (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCache
removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt;
Removes a **Preferences** instance from the cache. This API uses a promise to return the result.
After an application calls [getPreferences](#data_preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#data_preferencesgetpreferences) again, the **Preferences** instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling **getPreferences** again will read data from the persistent file and create a new **Preferences** instance.
After the **Preferences** instance is removed, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the removed **Preferences** instance to null. The system will reclaim the removed **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -248,7 +684,7 @@ The deleted **Preferences** instance cannot be used for data operations. Otherwi
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance to delete.|
| name | string | Yes | Name of the **Preferences** instance.|
**Return value**
......@@ -256,13 +692,65 @@ The deleted **Preferences** instance cannot be used for data operations. Otherwi
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Error codes**
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
let promise = data_preferences.removePreferencesFromCache(context, 'mystore');
promise.then(() => {
console.info("Removed the preferences successfully.");
}).catch((err) => {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore');
promise.then(() => {
console.info("Removed the preferences successfully.");
}).catch((err) => {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCacheSync<sup>10+</sup>
removePreferencesFromCacheSync(context: Context, name: string): void
Synchronously removes a **Preferences** instance from the cache.
After an application calls [getPreferences](#data_preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#data_preferencesgetpreferences) again, the **Preferences** instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling **getPreferences** again will read data from the persistent file and create a new **Preferences** instance.
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
After the **Preferences** instance is removed, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the removed **Preferences** instance to null. The system will reclaim the removed **Preferences** instances in a unified manner.
| ID| Error Message |
| -------- | ------------------------------|
| 15500010 | Failed to delete preferences file. |
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
**Example**
......@@ -272,16 +760,10 @@ FA model:
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
let promise = data_preferences.deletePreferences(context, 'mystore');
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
data_preferences.removePreferencesFromCacheSync(context, 'mystore');
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
......@@ -292,37 +774,43 @@ import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try{
let promise = data_preferences.deletePreferences(this.context, 'mystore');
promise.then(() => {
console.info("Deleted the preferences successfully.");
}).catch((err) => {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
})
try {
data_preferences.removePreferencesFromCacheSync(this.context, 'mystore');
} catch(err) {
console.info("Failed to delete the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCache
## data_preferences.removePreferencesFromCache<sup>10+</sup>
removePreferencesFromCache(context: Context, name: string, callback: AsyncCallback&lt;void&gt;): void
removePreferencesFromCache(context: Context, options: Options, callback: AsyncCallback&lt;void&gt;): void
Removes a **Preferences** instance from the cache. This API uses an asynchronous callback to return the result.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
After an application calls [getPreferences](#data_preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#data_preferencesgetpreferences) again, the **Preferences** instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling **getPreferences** again will read data from the persistent file and create a new **Preferences** instance.
After the **Preferences** instance is removed, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the removed **Preferences** instance to null. The system will reclaim the removed **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ---------------------------------------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance to remove. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
| -------- | ------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
......@@ -332,17 +820,16 @@ FA model:
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.removePreferencesFromCache(context, 'mystore', function (err) {
data_preferences.removePreferencesFromCache(context, {name: 'mystore'}, function (err) {
if (err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Removed the preferences successfully.");
})
} catch (err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
......@@ -354,37 +841,38 @@ import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.removePreferencesFromCache(this.context, 'mystore', function (err) {
data_preferences.removePreferencesFromCache(this.context, {name: 'mystore', dataGroupId:'myId'}, function (err) {
if (err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Removed the preferences successfully.");
})
} catch (err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCache
## data_preferences.removePreferencesFromCache<sup>10+</sup>
removePreferencesFromCache(context: Context, name: string): Promise&lt;void&gt;
removePreferencesFromCache(context: Context, options: Options): Promise&lt;void&gt;
Removes a **Preferences** instance from the cache. This API uses a promise to return the result.
The removed **Preferences** instance cannot be used for data operations. Otherwise, data inconsistency will be caused.
After an application calls [getPreferences](#data_preferencesgetpreferences) for the first time to obtain a **Preferences** instance, the obtained **Preferences** instance is cached. When the application calls [getPreferences](#data_preferencesgetpreferences) again, the **Preferences** instance will be read from the cache instead of from the persistent file. After this API is called to remove the instance from the cache, calling **getPreferences** again will read data from the persistent file and create a new **Preferences** instance.
After the **Preferences** instance is removed, do not use it to perform data operations. Otherwise, data inconsistency may be caused. For this purpose, set the removed **Preferences** instance to null. The system will reclaim the removed **Preferences** instances in a unified manner.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance to remove.|
| ------- | ---------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| options | [Options](#options10) | Yes | Configuration options of the **Preferences** instance. |
**Return value**
......@@ -392,6 +880,15 @@ The removed **Preferences** instance cannot be used for data operations. Otherwi
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | ------------------------------ |
| 15501001 | Only supported in stage mode. |
| 15501002 | The data group id is not valid. |
**Example**
FA model:
......@@ -400,16 +897,15 @@ FA model:
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
let promise = data_preferences.removePreferencesFromCache(context, 'mystore');
let promise = data_preferences.removePreferencesFromCache(context, {name: 'mystore'});
promise.then(() => {
console.info("Removed the preferences successfully.");
}).catch((err) => {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
......@@ -421,67 +917,29 @@ import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
let promise = data_preferences.removePreferencesFromCache(this.context, 'mystore');
let promise = data_preferences.removePreferencesFromCache(this.context, {name: 'mystore', dataGroupId:'myId'});
promise.then(() => {
console.info("Removed the preferences successfully.");
}).catch((err) => {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to remove the preferences. code =" + err.code + ", message =" + err.message);
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
## data_preferences.removePreferencesFromCacheSync<sup>10+</sup>
removePreferencesFromCacheSync(context: Context, name: string): void
Synchronously removes a **Preferences** instance from the cache.
## Options<sup>10+</sup>
The deleted **Preferences** instance cannot be used to perform data operations. Otherwise, data inconsistency will be caused.
Represents the configuration options of a **Preferences** instance.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------- |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md). |
| name | string | Yes | Name of the **Preferences** instance.|
**Example**
FA model:
```js
// Obtain the context.
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
try {
data_preferences.removePreferencesFromCacheSync(context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility';
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage) {
try {
data_preferences.removePreferencesFromCacheSync(this.context, 'mystore');
} catch(err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
}
}
```
| ----------- | ------ | ---- | ------------------------------------------------------------ |
| name | string | Yes | Name of the **Preferences** instance. |
| dataGroupId | string | No | Application group ID, which needs to be obtained from the AppGallery.<br>**Model restriction**: This attribute can be used only in the stage model.<br>This parameter is supported since API version 10. It specifies the **Preferences** instance created in the sandbox directory corresponding to the **dataGroupId**. If this parameter is not specified, the **Preferences** instance is created in the sandbox directory of the application.|
## Preferences
......@@ -504,7 +962,7 @@ Obtains the value corresponding to the specified key from the cached **Preferenc
| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| key | string | Yes | Key of the data to obtain. It cannot be empty. |
| defValue | [ValueType](#valuetype) | Yes | Default value to be returned. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback&lt;[ValueType](#valuetype)&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is** undefined** and **data** is the value obtained. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;[ValueType](#valuetype)&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **data** is the value obtained. Otherwise, **err** is an error object.|
**Example**
......@@ -512,13 +970,13 @@ Obtains the value corresponding to the specified key from the cached **Preferenc
try {
preferences.get('startup', 'default', function (err, val) {
if (err) {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain value of 'startup'. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Obtained the value of 'startup' successfully. val: " + val);
})
} catch (err) {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain value of 'startup'. code =" + err.code + ", message =" + err.message);
}
```
......@@ -552,10 +1010,10 @@ try {
promise.then((data) => {
console.info("Got the value of 'startup'. Data: " + data);
}).catch((err) => {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain value of 'startup'. code =" + err.code + ", message =" + err.message);
})
} catch(err) {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain value of 'startup'. code =" + err.code + ", message =" + err.message);
}
```
......@@ -587,7 +1045,7 @@ try {
let value = preferences.getSync('startup', 'default');
console.info("Obtained the value of 'startup'. Data: " + value);
} catch(err) {
console.info("Failed to obtain the value of 'startup'. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain value of 'startup'. code =" + err.code + ", message =" + err.message);
}
```
......@@ -603,7 +1061,7 @@ Obtains all KV pairs from the cached **Preferences** instance. This API uses an
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback&lt;Object&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value** provides all KV pairs obtained. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;Object&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined** and **value** provides all KV pairs obtained. Otherwise, **err** is an error object.|
**Example**
......@@ -611,7 +1069,7 @@ Obtains all KV pairs from the cached **Preferences** instance. This API uses an
try {
preferences.getAll(function (err, value) {
if (err) {
console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain all KV pairs. code =" + err.code + ", message =" + err.message);
return;
}
let allKeys = Object.keys(value);
......@@ -619,7 +1077,7 @@ try {
console.info("getAll object = " + JSON.stringify(value));
})
} catch (err) {
console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain all KV pairs. code =" + err.code + ", message =" + err.message);
}
```
......@@ -648,10 +1106,10 @@ try {
console.info('getAll keys = ' + allKeys);
console.info("getAll object = " + JSON.stringify(value));
}).catch((err) => {
console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain all KV pairs. code =" + err.code + ", message =" + err.message);
})
} catch (err) {
console.info("Failed to get all KV pairs. code =" + err.code + ", message =" + err.message);
console.info("Failed to obtain all KV pairs. code =" + err.code + ", message =" + err.message);
}
```
......@@ -659,7 +1117,7 @@ try {
getAllSync(): Object
Synchronously obtains all KV pairs from the cached **Preferences** instance.
Obtains all KV pairs from the cached **Preferences** instance synchronously.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
......@@ -696,7 +1154,7 @@ Writes data to the cached **Preferences** instance. This API uses an asynchronou
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| key | string | Yes | Key of the data. It cannot be empty. |
| value | [ValueType](#valuetype) | Yes | Value to write. The value can be a number, a string, a Boolean value, or an array of numbers, strings, or Boolean values.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is undefined. Otherwise, **err** is an error code. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If data is written successfully, **err** is **undefined**. Otherwise, **err** is an error object. |
**Example**
......@@ -707,7 +1165,7 @@ try {
console.info("Failed to put the value of 'startup'. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Put the value of 'startup' successfully.");
console.info("Successfully put the value of 'startup'.");
})
} catch (err) {
console.info("Failed to put the value of 'startup'. code =" + err.code + ", message =" + err.message);
......@@ -742,7 +1200,7 @@ Writes data to the cached **Preferences** instance. This API uses a promise to r
try {
let promise = preferences.put('startup', 'auto');
promise.then(() => {
console.info("Put the value of 'startup' successfully.");
console.info("Successfully put the value of 'startup'.");
}).catch((err) => {
console.info("Failed to put the value of 'startup'. code =" + err.code +", message =" + err.message);
})
......@@ -773,7 +1231,7 @@ Synchronously writes data to the cached **Preferences** instance. You can use [f
try {
preferences.putSync('startup', 'auto');
} catch(err) {
console.info("Failed to put value of 'startup'. code =" + err.code +", message =" + err.message);
console.info("Failed to put the value of 'startup'. code =" + err.code +", message =" + err.message);
}
```
......@@ -903,7 +1361,7 @@ Deletes a KV pair from the cached **Preferences** instance based on the specifie
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| key | string | Yes | Key of the KV pair to delete. It cannot be empty. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
......@@ -995,7 +1453,7 @@ Flushes the data in the cached **Preferences** instance to the persistent file.
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
......@@ -1006,7 +1464,7 @@ try {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Flushed data successfully.");
console.info("Successfully flushed data.");
})
} catch (err) {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
......@@ -1034,7 +1492,7 @@ Flushes the data in the cached **Preferences** instance to the persistent file.
try {
let promise = preferences.flush();
promise.then(() => {
console.info("Flushed data successfully.");
console.info("Successfully flushed data.");
}).catch((err) => {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
})
......@@ -1056,7 +1514,7 @@ Clears all data in the cached **Preferences** instance. This API uses an asynchr
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ---------------------------------------------------- |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error code.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. If the operation is successful, **err** is **undefined**. Otherwise, **err** is an error object.|
**Example**
......@@ -1067,7 +1525,7 @@ try {
console.info("Failed to clear data. code =" + err.code + ", message =" + err.message);
return;
}
console.info("Cleared data successfully.");
console.info("Successfully cleared data.");
})
} catch (err) {
console.info("Failed to clear data. code =" + err.code + ", message =" + err.message);
......@@ -1095,7 +1553,7 @@ Clears all data in the cached **Preferences** instance. This API uses a promise
try {
let promise = preferences.clear();
promise.then(() => {
console.info("Cleared data successfully.");
console.info("Successfully cleared data.");
}).catch((err) => {
console.info("Failed to clear data. code =" + err.code + ", message =" + err.message);
})
......@@ -1119,7 +1577,7 @@ Synchronously clears all data in the cached **Preferences** instance. You can us
try {
preferences.clearSync();
} catch(err) {
console.info("Failed to clear. code =" + err.code + ", message =" + err.message);
console.info("Failed to clear data. code =" + err.code + ", message =" + err.message);
}
```
......@@ -1157,14 +1615,73 @@ try {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Put the value of 'startup' successfully.");
console.info("Successfully put the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Successfully flushed data.");
})
})
})
} catch (err) {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
}
```
### on('multiProcessChange')<sup>10+</sup>
on(type: 'multiProcessChange', callback: Callback&lt;{ key : string }&gt;): void
Subscribes to inter-process data changes. For the multiple processes holding the same preference file, if the value of the subscribed key changes in any process, the callback in this API will be invoked after [flush()](#flush) is executed.
This API can be used with [removePreferencesFromCache](#data_preferencesremovepreferencesfromcache) to update the **Preferences** instance in the callback when detecting that a process updates a file. For details, see example 2.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | -------------------------------------------------------------- |
| type | string | Yes | Event type. The value is **multiProcessChange**, which indicates data changes between multiple processes.|
| callback | Callback&lt;{ key : string }&gt; | Yes | Callback invoked to return data changes. |
**Error codes**
For details about the error codes, see [User Preference Error Codes](../errorcodes/errorcode-preferences.md).
| ID| Error Message |
| -------- | -------------------------------------- |
| 15500019 | Failed to obtain subscription service. |
**Example 1**
```js
try {
data_preferences.getPreferences(this.context, {name: 'mystore', dataGroupId:'myId'}, function (err, preferences) {
if (err) {
console.info("Failed to obtain the preferences.");
return;
}
let observer = function (key) {
console.info("The key " + key + " changed.");
}
preferences.on('multiProcessChange', observer);
preferences.put('startup', 'manual', function (err) {
if (err) {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Successfully put the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Flushed data successfully.");
console.info("Successfully flushed data.");
})
})
})
......@@ -1173,6 +1690,66 @@ try {
}
```
**Example 2**
```js
let preferences = null;
try {
data_preferences.getPreferences(this.context, { name: 'mystore' }, function (err, val) {
if (err) {
console.info("Failed to obtain the preferences.");
return;
}
preferences = val;
let observer = function (key) {
console.info("The key " + key + " changed.");
try {
data_preferences.removePreferencesFromCache(context, { name: 'mystore' }, function (err) {
if (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
return;
}
preferences = null;
console.info("Removed the preferences successfully.");
})
} catch (err) {
console.info("Failed to remove preferences. code =" + err.code + ", message =" + err.message);
}
try {
data_preferences.getPreferences(context, { name: 'mystore' }, function (err, val) {
if (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
return;
}
preferences = val;
console.info("Obtained the preferences successfully.");
})
} catch (err) {
console.info("Failed to obtain the preferences. code =" + err.code + ", message =" + err.message);
}
}
preferences.on('multiProcessChange', observer);
preferences.put('startup', 'manual', function (err) {
if (err) {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Successfully put the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Successfully flushed data.");
})
})
})
} catch (err) {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
}
```
### off('change')
......@@ -1207,14 +1784,14 @@ try {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Put the value of 'startup' successfully.");
console.info("Successfully put the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Flushed data successfully.");
console.info("Successfully flushed data.");
})
preferences.off('change', observer);
})
......@@ -1224,6 +1801,55 @@ try {
}
```
### off('multiProcessChange')<sup>10+</sup>
off(type: 'multiProcessChange', callback?: Callback&lt;{ key : string }&gt;): void
Unsubscribes from inter-process data changes.
**System capability**: SystemCapability.DistributedDataManager.Preferences.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------- | ---- | -------------------------------------------------------------- |
| type | string | Yes | Event type. The value is **multiProcessChange**, which indicates data changes between multiple processes.|
| callback | Callback&lt;{ key : string }&gt; | No | Callback to unregister. If this parameter is left blank, all callbacks for **multiProcessChange** will be unregistered. |
**Example**
```js
try {
data_preferences.getPreferences(this.context, {name: 'mystore', dataGroupId:'myId'}, function (err, preferences) {
if (err) {
console.info("Failed to obtain the preferences.");
return;
}
let observer = function (key) {
console.info("The key " + key + " changed.");
}
preferences.on('multiProcessChange', observer);
preferences.put('startup', 'auto', function (err) {
if (err) {
console.info("Failed to put the value of 'startup'. Cause: " + err);
return;
}
console.info("Successfully put the value of 'startup'.");
preferences.flush(function (err) {
if (err) {
console.info("Failed to flush data. Cause: " + err);
return;
}
console.info("Successfully flushed data.");
})
preferences.off('multiProcessChange', observer);
})
})
} catch (err) {
console.info("Failed to flush data. code =" + err.code + ", message =" + err.message);
}
```
## ValueType
Enumerates the value types.
......@@ -1237,4 +1863,4 @@ Enumerates the value types.
| boolean | The value is of Boolean type. |
| Array\<number> | The value is an array of numbers. |
| Array\<boolean> | The value is a Boolean array. |
| Array\<string> | The value is an array of the strings.|
| Array\<string> | The value is an array of strings.|
en/application-dev/reference/apis/js-apis-data-relationalStore.md
浏览文件 @ f1affe03
# @ohos.data.relationalStore (RDB Store)
The relational database (RDB) store manages data based on relational models. The RDB store provides a complete mechanism for managing local databases based on the underlying SQLite. To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. The worker threads are not supported.
The relational database (RDB) store manages data based on relational models. It provides a complete mechanism for managing local databases based on the underlying SQLite. To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. The worker threads are not supported.
The **relationalStore** module provides the following functions:
......@@ -43,6 +43,8 @@ For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode
| 14800010 | Failed to open or delete database by invalid database path. |
| 14800011 | Failed to open database by database corrupted. |
| 14800000 | Inner error. |
| 14801001 | Only supported in stage mode. |
| 14801002 | The data group id is not valid. |
**Example**
......@@ -127,6 +129,8 @@ For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode
| 14800010 | Failed to open or delete database by invalid database path. |
| 14800011 | Failed to open database by database corrupted. |
| 14800000 | Inner error. |
| 14801001 | Only supported in stage mode. |
| 14801002 | The data group id is not valid. |
**Example**
......@@ -184,6 +188,8 @@ deleteRdbStore(context: Context, name: string, callback: AsyncCallback&lt;void&g
Deletes an RDB store. This API uses an asynchronous callback to return the result.
After the deletion, you are advised to set the database object to null.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
......@@ -218,6 +224,7 @@ relationalStore.deleteRdbStore(context, "RdbTest.db", function (err) {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
return;
}
store = null;
console.info(`Delete RdbStore successfully.`);
})
```
......@@ -234,6 +241,7 @@ class EntryAbility extends UIAbility {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
return;
}
store = null;
console.info(`Delete RdbStore successfully.`);
})
}
......@@ -246,6 +254,8 @@ deleteRdbStore(context: Context, name: string): Promise&lt;void&gt;
Deletes an RDB store. This API uses a promise to return the result.
After the deletion, you are advised to set the database object to null.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
......@@ -282,6 +292,7 @@ let context = featureAbility.getContext();
let promise = relationalStore.deleteRdbStore(context, "RdbTest.db");
promise.then(()=>{
store = null;
console.info(`Delete RdbStore successfully.`);
}).catch((err) => {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
......@@ -297,6 +308,162 @@ class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage){
let promise = relationalStore.deleteRdbStore(this.context, "RdbTest.db");
promise.then(()=>{
store = null;
console.info(`Delete RdbStore successfully.`);
}).catch((err) => {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
})
}
}
```
## relationalStore.deleteRdbStore<sup>10+</sup>
deleteRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback\<void>): void
Deletes an RDB store. This API uses an asynchronous callback to return the result.
After the deletion, you are advised to set the database object to null. If the database file is in the public sandbox directory, you must use this API to delete the database. If the database is accessed by multiple processes at the same time, you are advised to send a database deletion notification to other processes.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| config | [StoreConfig](#storeconfig) | Yes | Configuration of the RDB store. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | ----------------------------------------------------------- |
| 14800010 | Failed to open or delete database by invalid database path. |
| 14800000 | Inner error. |
| 14801001 | Only supported in stage mode. |
| 14801002 | The data group id is not valid. |
**Example**
FA model:
```js
import featureAbility from '@ohos.ability.featureAbility'
// Obtain the context.
let context = featureAbility.getContext()
const STORE_CONFIG = {
name: "RdbTest.db",
securityLevel: relationalStore.SecurityLevel.S1
};
relationalStore.deleteRdbStore(context, STORE_CONFIG, function (err) {
if (err) {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
return;
}
store = null;
console.info(`Delete RdbStore successfully.`);
})
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility'
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage){
const STORE_CONFIG = {
name: "RdbTest.db",
securityLevel: relationalStore.SecurityLevel.S1
};
relationalStore.deleteRdbStore(this.context, STORE_CONFIG, function (err) {
if (err) {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
return;
}
store = null;
console.info(`Delete RdbStore successfully.`);
})
}
}
```
## relationalStore.deleteRdbStore<sup>10+</sup>
deleteRdbStore(context: Context, config: StoreConfig): Promise\<void>
Deletes an RDB store. This API uses a promise to return the result.
After the deletion, you are advised to set the database object to null. If the database file is in the public sandbox directory, you must use this API to delete the database. If the database is accessed by multiple processes at the same time, you are advised to send a database deletion notification to other processes.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------- | ---- | ------------------------------------------------------------ |
| context | Context | Yes | Application context.<br>For details about the application context of the FA model, see [Context](js-apis-inner-app-context.md).<br>For details about the application context of the stage model, see [Context](js-apis-inner-application-uiAbilityContext.md).|
| config | [StoreConfig](#storeconfig) | Yes | Configuration of the RDB store. |
**Return value**
| Type | Description |
| ------------------- | ------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | ----------------------------------------------------------- |
| 14800010 | Failed to open or delete database by invalid database path. |
| 14800000 | Inner error. |
| 14801001 | Only supported in stage mode. |
| 14801002 | The data group id is not valid. |
**Example**
FA model:
```js
import featureAbility from '@ohos.ability.featureAbility'
// Obtain the context.
let context = featureAbility.getContext();
const STORE_CONFIG = {
name: "RdbTest.db",
securityLevel: relationalStore.SecurityLevel.S1
};
let promise = relationalStore.deleteRdbStore(context, STORE_CONFIG);
promise.then(()=>{
store = null;
console.info(`Delete RdbStore successfully.`);
}).catch((err) => {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
})
```
Stage model:
```ts
import UIAbility from '@ohos.app.ability.UIAbility'
class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage){
const STORE_CONFIG = {
name: "RdbTest.db",
securityLevel: relationalStore.SecurityLevel.S1
};
let promise = relationalStore.deleteRdbStore(this.context, STORE_CONFIG);
promise.then(()=>{
store = null;
console.info(`Delete RdbStore successfully.`);
}).catch((err) => {
console.error(`Delete RdbStore failed, code is ${err.code},message is ${err.message}`);
......@@ -315,7 +482,8 @@ Defines the RDB store configuration.
| ------------- | ------------- | ---- | --------------------------------------------------------- |
| name | string | Yes | Database file name. |
| securityLevel | [SecurityLevel](#securitylevel) | Yes | Security level of the RDB store. |
| encrypt | boolean | No | Whether to encrypt the RDB store.<br> The value **true** means to encrypt the RDB store;<br> the value **false** (default) means the opposite.|
| encrypt | boolean | No | Whether to encrypt the RDB store.<br>The value **true** means to encrypt the RDB store;<br>the value **false** (default) means the opposite.|
| dataGroupId<sup>10+</sup> | string | No| Application group ID, which needs to be obtained from the AppGallery.<br>**Model restriction**: This attribute can be used only in the stage model.<br>This parameter is supported since API version 10. It specifies the **relationalStore** instance created in the sandbox directory corresponding to the **dataGroupId**. If this parameter is not specified, the **relationalStore** instance is created in the sandbox directory of the application.|
## SecurityLevel
......@@ -323,7 +491,7 @@ Enumerates the RDB store security levels.
> **NOTE**
>
> To perform data synchronization operations, the RDB store security level must be lower than or equal to that of the peer device. For details, see the [Access Control Mechanism in Cross-Device Synchronization]( ../../database/access-control-by-device-and-data-level.md#access-control-mechanism-in-cross-device-synchronization).
> To perform data synchronization operations, the RDB store security level must be lower than or equal to that of the peer device. For details, see the [Access Control Mechanism in Cross-Device Synchronization](../../database/access-control-by-device-and-data-level.md#access-control-mechanism-in-cross-device-synchronization).
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
......@@ -369,6 +537,8 @@ Defines information about an asset (such as a document, image, and video). The a
Defines an array of the [Asset](#asset10) type.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Type | Description |
| ------- | -------------------- |
| [Asset](#asset10)[] | Array of assets. |
......@@ -399,6 +569,36 @@ Defines the types of the key and value in a KV pair. This type is not multi-thre
| ------ | ----------------------- |
| string | [ValueType](#valuetype) |
## PRIKeyType<sup>10+</sup>
Represents the type of the primary key in a row of a database table.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Type | Description |
| ---------------- | ---------------------------------- |
| number \| string | The type of the primary key can be number or string.|
## UTCTime<sup>10+</sup>
Represents the data type of the UTC time.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Type| Description |
| ---- | --------------- |
| Date | UTC time.|
## ModifyTime<sup>10+</sup>
Represents the data type of the primary key and modification time of a database table.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Type | Description |
| ------------------------------------------------------- | ------------------------------------------------------------ |
| Map<[PRIKeyType](#prikeytype10), [UTCTime](#utctime10)> | The key is the primary key of a row in the database table, and the value is the last modification time of the row in UTC format.|
## SyncMode
Enumerates the database synchronization modes.
......@@ -407,9 +607,9 @@ Enumerates the database synchronization modes.
| -------------- | ---- | ---------------------------------- |
| SYNC_MODE_PUSH | 0 | Push data from a local device to a remote device.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| SYNC_MODE_PULL | 1 | Pull data from a remote device to a local device.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| SYNC_MODE_TIME_FIRST<sup>10+</sup> | - | Synchronize with the data with the latest modification time. Use the enum names instead of the enum values. Currently, manual synchronization between the device and cloud is not supported.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client|
| SYNC_MODE_NATIVE_FIRST<sup>10+</sup> | - | Synchronize data from a local device to the cloud. Use the enum names instead of the enum values. Currently, manual synchronization between the device and cloud is not supported.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client |
| SYNC_MODE_CLOUD_FIRST<sup>10+</sup> | - | Synchronize data from the cloud to a local device. Use the enum names instead of the enum values. Currently, manual synchronization between the device and cloud is not supported.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client |
| SYNC_MODE_TIME_FIRST<sup>10+</sup> | - | Synchronize with the data with the latest modification time. Use the enum names instead of the enum values.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client|
| SYNC_MODE_NATIVE_FIRST<sup>10+</sup> | - | Synchronize data from a local device to the cloud. Use the enum names instead of the enum values.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client |
| SYNC_MODE_CLOUD_FIRST<sup>10+</sup> | - | Synchronize data from the cloud to a local device. Use the enum names instead of the enum values.<br>**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client |
## SubscribeType
......@@ -440,15 +640,15 @@ Enumerates data change types. Use the enum names instead of the enum values.
Defines the details about the device-cloud synchronization process.
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Type | Mandatory | Description |
| -------- | ---------------------------------- | --- | -------------------------------------------------------------------------------------------------------------------- |
| table | string | Yes | Name of the table with data changes.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| type | [ChangeType](#changetype10) | Yes | Type of the data changed, which can be data or asset.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| inserted | Array\<string\> \| Array\<number\> | Yes | Location where data is inserted. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the inserted data.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| updated | Array\<string\> \| Array\<number\> | Yes | Location where data is updated. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the updated data.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| deleted | Array\<string\> \| Array\<number\> | Yes | Location where data is deleted. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the deleted data.<br>**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core |
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ |
| table | string | Yes | Name of the table with data changes. |
| type | [ChangeType](#changetype10) | Yes | Type of the data changed, which can be data or asset. |
| inserted | Array\<string\> \| Array\<number\> | Yes | Location where data is inserted. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the inserted data.|
| updated | Array\<string\> \| Array\<number\> | Yes | Location where data is updated. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the updated data.|
| deleted | Array\<string\> \| Array\<number\> | Yes | Location where data is deleted. If the primary key of the table is of the string type, the value is the value of the primary key. Otherwise, the value is the row number of the deleted data.|
## DistributedType<sup>10+</sup>
......@@ -486,6 +686,70 @@ Defines the resolution to use when **insert()** and **update()** conflict.
| ON_CONFLICT_IGNORE | 4 | Skip the rows that contain constraint violations and continue to process the subsequent rows of the SQL statement.|
| ON_CONFLICT_REPLACE | 5 | Delete pre-existing rows that cause the constraint violation before inserting or updating the current row, and continue to execute the command normally.|
## Progress<sup>10+</sup>
Enumerates the device-cloud synchronization processes. Use the enum names instead of the enum values.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Value | Description |
| ---------------- | ---- | ------------------------ |
| SYNC_BEGIN | - | The device-cloud synchronization starts. |
| SYNC_IN_PROGRESS | - | The device-cloud synchronization is in progress.|
| SYNC_FINISH | - | The device-cloud synchronization is complete.|
## Statistic<sup>10+</sup>
Represents the device-cloud synchronization statistics information.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | ---------------------------------------- |
| total | number | Yes | Total number of rows to be synchronized between the device and cloud in the database table. |
| success | number | Yes | Number of rows that are successfully synchronized between the device and cloud in the database table. |
| failed | number | Yes | Number of rows that failed to be synchronized between the device and cloud in the database table. |
| remained | number | Yes | Number of rows that are not executed for device-cloud synchronization in the database table.|
## TableDetails<sup>10+</sup>
Represents the upload and download statistics of device-cloud synchronization tasks.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------ |
| upload | [Statistic](#statistic10) | Yes | Statistics of the device-cloud upload tasks.|
| download | [Statistic](#statistic10) | Yes | Statistics of the device-cloud download tasks.|
## ProgressCode<sup>10+</sup>
Enumerates the device-cloud synchronization states. Use the enum names instead of the enum values.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Value | Description |
| --------------------- | ---- | ------------------------------------------------------------ |
| SUCCESS | - | The device-cloud synchronization is successful. |
| UNKNOWN_ERROR | - | An unknown error occurs during device-cloud synchronization. |
| NETWORK_ERROR | - | A network error occurs during device-cloud synchronization. |
| CLOUD_DISABLED | - | The cloud is unavailable. |
| LOCKED_BY_OTHERS | - | The device-cloud synchronization of another device is being performed.<br>Start device-cloud synchronization after checking that cloud resources are not occupied by other devices.|
| RECORD_LIMIT_EXCEEDED | - | The number of records or size of the data to be synchronized exceeds the maximum. The maximum value is configured on the cloud.|
| NO_SPACE_FOR_ASSET | - | The remaining cloud space is less than the size of the data to be synchronized. |
## ProgressDetails<sup>10+</sup>
Represents the statistics of the overall device-cloud synchronization (upload and download) tasks.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| schedule | [Progress](#progress10) | Yes | Device-cloud synchronization process. |
| code | [ProgressCode](#progresscode10) | Yes | Device-cloud synchronization state. |
| details | [table: string] : [TableDetails](#tabledetails10) | Yes | Statistics of each table.<br>The key indicates the table name, and the value indicates the device-cloud synchronization statistics of the table.|
## RdbPredicates
Defines the predicates for an RDB store. This class determines whether the conditional expression for the RDB store is true or false. This type is not multi-thread safe. If an **RdbPredicates** instance is operated by multiple threads at the same time in an application, use a lock for the instance.
......@@ -2133,6 +2397,53 @@ promise.then((rows) => {
})
```
### query<sup>10+</sup>
query(predicates: RdbPredicates, callback: AsyncCallback&lt;ResultSet&gt;):void
Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| predicates | [RdbPredicates](#rdbpredicates) | Yes | Query conditions specified by the **RdbPredicates** object. |
| callback | AsyncCallback&lt;[ResultSet](#resultset)&gt; | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | ---------------------------- |
| 14800000 | Inner error. |
**Example**
```js
let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
predicates.equalTo("NAME", "Rose");
store.query(predicates, function (err, resultSet) {
if (err) {
console.error(`Query failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
// resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
while(resultSet.goToNextRow()) {
const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
}
// Release the dataset memory.
resultSet.close();
})
```
### query
query(predicates: RdbPredicates, columns: Array&lt;string&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void
......@@ -2233,9 +2544,9 @@ promise.then((resultSet) => {
})
```
### query
### query<sup>10+</sup>
query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array&lt;string&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void
query(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback&lt;ResultSet&gt;):void
Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result.
......@@ -2251,7 +2562,6 @@ Queries data from the RDB store based on specified conditions. This API uses an
| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| table | string | Yes | Name of the target table. |
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Query conditions specified by the **DataSharePredicates** object. |
| columns | Array&lt;string&gt; | Yes | Columns to query. If this parameter is not specified, the query applies to all columns. |
| callback | AsyncCallback&lt;[ResultSet](#resultset)&gt; | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
**Error codes**
......@@ -2268,7 +2578,7 @@ For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode
import dataSharePredicates from '@ohos.data.dataSharePredicates'
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) {
store.query("EMPLOYEE", predicates, function (err, resultSet) {
if (err) {
console.error(`Query failed, code is ${err.code},message is ${err.message}`);
return;
......@@ -2289,9 +2599,9 @@ store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], fu
### query
query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns?: Array&lt;string&gt;):Promise&lt;ResultSet&gt;
query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array&lt;string&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void
Queries data from the RDB store based on specified conditions. This API uses a promise to return the result.
Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
......@@ -2302,16 +2612,11 @@ Queries data from the RDB store based on specified conditions. This API uses a p
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ |
| ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- |
| table | string | Yes | Name of the target table. |
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Query conditions specified by the **DataSharePredicates** object. |
| columns | Array&lt;string&gt; | No | Columns to query. If this parameter is not specified, the query applies to all columns.|
**Return value**
| Type | Description |
| ------------------------------------------------------- | -------------------------------------------------- |
| Promise&lt;[ResultSet](#resultset)&gt; | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.|
| columns | Array&lt;string&gt; | Yes | Columns to query. If this parameter is not specified, the query applies to all columns. |
| callback | AsyncCallback&lt;[ResultSet](#resultset)&gt; | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned.|
**Error codes**
......@@ -2327,8 +2632,67 @@ For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode
import dataSharePredicates from '@ohos.data.dataSharePredicates'
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
let promise = store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]);
promise.then((resultSet) => {
store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], function (err, resultSet) {
if (err) {
console.error(`Query failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
// resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
while(resultSet.goToNextRow()) {
const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
}
// Release the dataset memory.
resultSet.close();
})
```
### query
query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns?: Array&lt;string&gt;):Promise&lt;ResultSet&gt;
Queries data from the RDB store based on specified conditions. This API uses a promise to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Model restriction**: This API can be used only in the stage model.
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ |
| table | string | Yes | Name of the target table. |
| predicates | [dataSharePredicates.DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | Yes | Query conditions specified by the **DataSharePredicates** object. |
| columns | Array&lt;string&gt; | No | Columns to query. If this parameter is not specified, the query applies to all columns.|
**Return value**
| Type | Description |
| ------------------------------------------------------- | -------------------------------------------------- |
| Promise&lt;[ResultSet](#resultset)&gt; | Promise used to return the result. If the operation is successful, a **ResultSet** object will be returned.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | ---------------------------- |
| 14800000 | Inner error. |
**Example**
```js
import dataSharePredicates from '@ohos.data.dataSharePredicates'
let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
let promise = store.query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]);
promise.then((resultSet) => {
console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
// resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
while(resultSet.goToNextRow()) {
......@@ -2487,6 +2851,51 @@ promise.then((resultSet) => {
})
```
### querySql<sup>10+</sup>
querySql(sql: string, callback: AsyncCallback&lt;ResultSet&gt;):void
Queries data using the specified SQL statement. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| sql | string | Yes | SQL statement to run. |
| callback | AsyncCallback&lt;[ResultSet](#resultset)&gt; | Yes | Callback invoked to return the result. If the operation is successful, a **ResultSet** object will be returned. |
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | ---------------------------- |
| 14800000 | Inner error. |
**Example**
```js
store.querySql("SELECT * FROM EMPLOYEE CROSS JOIN BOOK WHERE BOOK.NAME = 'sanguo'", function (err, resultSet) {
if (err) {
console.error(`Query failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
// resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
while(resultSet.goToNextRow()) {
const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
}
// Release the dataset memory.
resultSet.close();
})
```
### querySql
querySql(sql: string, bindArgs: Array&lt;ValueType&gt;, callback: AsyncCallback&lt;ResultSet&gt;):void
......@@ -2583,6 +2992,43 @@ promise.then((resultSet) => {
})
```
### executeSql<sup>10+</sup>
executeSql(sql: string, callback: AsyncCallback&lt;void&gt;):void
Executes an SQL statement that contains specified arguments but returns no value. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | ------------------------------------------------------------ |
| sql | string | Yes | SQL statement to run. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result. |
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | -------------------------------------------- |
| 14800047 | The WAL file size exceeds the default limit. |
| 14800000 | Inner error. |
**Example**
```js
const SQL_DELETE_TABLE = "DELETE FROM test WHERE name = 'zhangsan'"
store.executeSql(SQL_DELETE_TABLE, function(err) {
if (err) {
console.error(`ExecuteSql failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info(`Delete table done.`);
})
```
### executeSql
executeSql(sql: string, bindArgs: Array&lt;ValueType&gt;, callback: AsyncCallback&lt;void&gt;):void
......@@ -2663,6 +3109,85 @@ promise.then(() => {
})
```
### getModifyTime<sup>10+</sup>
getModifyTime(table: string, columnName: string, primaryKeys: PRIKeyType[], callback: AsyncCallback&lt;ModifyTime&gt;): void
Obtains the last modification time of the data in a table. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ |
| table | string | Yes | Name of the database table to query. |
| columnName | string | Yes | Column name of the database table to query. |
| primaryKeys | [PRIKeyType](#prikeytype10)[] | Yes | Primary keys of the rows to query.<br>If the database table has no primary key, **rowid** must be passed in through **columnName**. In this case, **primaryKeys** specifies the row numbers of the database table to query.<br>If the database table has no primary key and no **rowid** is passed in through **columnName**, an error code will be returned.|
| callback | AsyncCallback&lt;[ModifyTime](#modifytime10)&gt; | Yes | Callback invoked to return the result. If the operation is successful, the **ModifyTime** object is returned.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message**|
| ------------ | ------------ |
| 14800000 | Inner error. |
**Example**
```js
let PRIKey = [1, 4, 2, 3];
store.getModifyTime("cloud_tasks", "uuid", PRIKey, function (err, modifyTime) {
if (err) {
console.error(`getModifyTime failed, code is ${err.code},message is ${err.message}`);
return;
}
let size = modifyTime.size();
});
```
### getModifyTime<sup>10+</sup>
getModifyTime(table: string, columnName: string, primaryKeys: PRIKeyType[]): Promise&lt;ModifyTime&gt;
Obtains the last modification time of the data in a table. This API uses a promise to return the result.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ----------- | ----------------------------- | ---- | ------------------------------------------------------------ |
| table | string | Yes | Name of the database table to query. |
| columnName | string | Yes | Column name of the database table to query. |
| primaryKeys | [PRIKeyType](#prikeytype10)[] | Yes | Primary keys of the rows to query.<br>If the database table has no primary key, **rowid** must be passed in through **columnName**. In this case, **primaryKeys** specifies the row numbers of the database table to query.<br>If the database table has no primary key and no **rowid** is passed in through **columnName**, an error code will be returned.|
**Return value**
| Type | Description |
| ------------------------------------------ | --------------------------------------------------------- |
| Promise&lt;[ModifyTime](#modifytime10)&gt; | Promise used to return the **ModifyTime** object.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message**|
| ------------ | ------------ |
| 14800000 | Inner error. |
**Example**
```js
let PRIKey = [1, 2, 3];
store.getModifyTime("cloud_tasks", "uuid", PRIKey).then((modifyTime) => {
let size = modifyTime.size();
}).catch((err) => {
console.error(`getModifyTime failed, code is ${err.code},message is ${err.message}`);
});
```
### beginTransaction
beginTransaction():void
......@@ -3021,14 +3546,14 @@ Sets distributed tables. This API uses an asynchronous callback to return the re
| Name | Type | Mandatory | Description |
| -------- | ----------------------------------- | --- | --------------- |
| tables | Array&lt;string&gt; | Yes | Names of the distributed tables to set. |
| type | number | Yes | Distributed type of the tables. Currently, only **relationalStore.DistributedType.DISTRIBUTED_DEVICE** and **relationalStore.DistributedType.DISTRIBUTED_CLOUD** are supported.<br> The value **relationalStore.DistributedType.DISTRIBUTED_DEVICE** indicates distributed tables across different devices.<br> The value **relationalStore.DistributedType.DISTRIBUTED_CLOUD** indicates distributed tables between the device and cloud.|
| type | number | Yes | Distributed type of the tables. Currently, only **relationalStore.DistributedType.DISTRIBUTED_DEVICE** and **relationalStore.DistributedType.DISTRIBUTED_CLOUD** are supported.<br>The value **relationalStore.DistributedType.DISTRIBUTED_DEVICE** indicates distributed tables across different devices.<br>The value **relationalStore.DistributedType.DISTRIBUTED_CLOUD** indicates distributed tables between the device and cloud.|
| config | [DistributedConfig](#distributedconfig10) | Yes| Configuration of the distributed mode.|
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to return the result.|
**Example**
```js
let config = new DistributedConfig();
let config = new relationalStore.DistributedConfig();
config.autoSync = true;
store.setDistributedTables(["EMPLOYEE"], relationalStore.DistributedType.DISTRIBUTED_CLOUD, config, function (err) {
if (err) {
......@@ -3054,7 +3579,7 @@ Sets distributed tables. This API uses a promise to return the result.
| Name| Type | Mandatory| Description |
| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| tables | Array&lt;string&gt; | Yes | Names of the distributed tables to set. |
| type | number | No | Distributed type of the tables. The default value is **relationalStore.DistributedType.DISTRIBUTED_DEVICE**.<br> Currently, only **relationalStore.DistributedType.DISTRIBUTED_DEVICE** and **relationalStore.DistributedType.DISTRIBUTED_CLOUD** are supported.<br> The value **relationalStore.DistributedType.DISTRIBUTED_DEVICE** indicates distributed tables across different devices.<br> The value **relationalStore.DistributedType.DISTRIBUTED_CLOUD** indicates distributed tables between the device and cloud.|
| type | number | No | Distributed type of the tables. The default value is **relationalStore.DistributedType.DISTRIBUTED_DEVICE**.<br>Currently, only **relationalStore.DistributedType.DISTRIBUTED_DEVICE** and **relationalStore.DistributedType.DISTRIBUTED_CLOUD** are supported.<br>The value **relationalStore.DistributedType.DISTRIBUTED_DEVICE** indicates distributed tables across different devices.<br>The value **relationalStore.DistributedType.DISTRIBUTED_CLOUD** indicates distributed tables between the device and cloud.|
| config | [DistributedConfig](#distributedconfig10) | No | Configuration of the distributed mode. If this parameter is not specified, the value of **autoSync** is **false** by default, which means only manual synchronization is supported.|
**Return value**
......@@ -3066,7 +3591,7 @@ Sets distributed tables. This API uses a promise to return the result.
**Example**
```js
let config = new DistributedConfig();
let config = new relationalStore.DistributedConfig();
config.autoSync = true;
let promise = store.setDistributedTables(["EMPLOYEE"], relationalStore.DistributedType.DISTRIBUTED_CLOUD, config);
promise.then(() => {
......@@ -3314,11 +3839,153 @@ promise.then((result) =>{
})
```
### cloudSync<sup>10+</sup>
cloudSync(mode: SyncMode, progress: Callback&lt;ProgressDetails&gt;, callback: AsyncCallback&lt;void&gt;): void
Manually starts device-cloud synchronization for all distributed tables. This API uses an asynchronous callback to return the result. Before using this API, ensure that the cloud service must be available.
**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- |
| mode | [SyncMode](#syncmode) | Yes | Synchronization mode of the database. |
| progress | Callback&lt;[ProgressDetails](#progressdetails10)&gt; | Yes | Callback used to process database synchronization details. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to send the synchronization result to the caller.|
**Example**
```js
relationalStore.cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, function (progressDetails) {
console.info(`Progess: ${progressDetails}`);
}, function (err) {
if (err) {
console.error(`Cloud sync failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info('Cloud sync succeeded');
});
```
### cloudSync<sup>10+</sup>
cloudSync(mode: SyncMode, progress: Callback&lt;ProgressDetails&gt;): Promise&lt;void&gt;
Manually starts device-cloud synchronization for all distributed tables. This API uses a promise to return the result. Before using this API, ensure that the cloud service must be available.
**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| mode | [SyncMode](#syncmode) | Yes | Synchronization mode of the database. |
| progress | Callback&lt;[ProgressDetails](#progressdetails10)&gt; | Yes | Callback used to process database synchronization details.|
**Return value**
| Type | Description |
| ------------------- | --------------------------------------- |
| Promise&lt;void&gt; | Promise used to send the synchronization result.|
**Example**
```js
function progress(progressDetail) {
console.info(`progress: ${progressDetail}`);
}
relationalStore.cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, progress).then(() => {
console.info('Cloud sync succeeded');
}).catch((err) => {
console.error(`cloudSync failed, code is ${err.code},message is ${err.message}`);
});
```
### cloudSync<sup>10+</sup>
cloudSync(mode: SyncMode, tables: string[], progress: Callback&lt;ProgressDetails&gt;, callback: AsyncCallback&lt;void&gt;): void
Manually starts device-cloud synchronization of the specified table. This API uses an asynchronous callback to return the result. Before using this API, ensure that the cloud service must be available.
**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------------------- |
| mode | [SyncMode](#syncmode) | Yes | Synchronization mode of the database. |
| tables | string[] | Yes | Name of the table to synchronize. |
| progress | Callback&lt;[ProgressDetails](#progressdetails10)&gt; | Yes | Callback used to process database synchronization details. |
| callback | AsyncCallback&lt;void&gt; | Yes | Callback invoked to send the synchronization result to the caller.|
**Example**
```js
const tables = ["table1", "table2"];
relationalStore.cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, tables, function (progressDetails) {
console.info(`Progess: ${progressDetails}`);
}, function (err) {
if (err) {
console.error(`Cloud sync failed, code is ${err.code},message is ${err.message}`);
return;
}
console.info('Cloud sync succeeded');
});
```
### cloudSync<sup>10+</sup>
cloudSync(mode: SyncMode, tables: string[], progress: Callback&lt;ProgressDetails&gt;): Promise&lt;void&gt;
Manually starts device-cloud synchronization of the specified table. This API uses a promise to return the result. Before using this API, ensure that the cloud service must be available.
**Required permissions**: ohos.permission.DISTRIBUTED_DATASYNC
**System capability**: SystemCapability.DistributedDataManager.CloudSync.Client
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | -------------------------------------- |
| mode | [SyncMode](#syncmode) | Yes | Synchronization mode of the database. |
| tables | string[] | Yes | Name of the table to synchronize. |
| progress | Callback&lt;[ProgressDetails](#progressdetails10)&gt; | Yes | Callback used to process database synchronization details.|
**Return value**
| Type | Description |
| ------------------- | --------------------------------------- |
| Promise&lt;void&gt; | Promise used to send the synchronization result.|
**Example**
```js
const tables = ["table1", "table2"];
function progress(progressDetail) {
console.info(`progress: ${progressDetail}`);
}
relationalStore.cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, tables, progress).then(() => {
console.info('Cloud sync succeeded');
}).catch((err) => {
console.error(`cloudSync failed, code is ${err.code},message is ${err.message}`);
});
```
### on('dataChange')
on(event: 'dataChange', type: SubscribeType, observer: Callback&lt;Array&lt;string&gt;&gt;): void
Registers the data change event listener for the RDB store. When the data in the RDB store changes, a callback is invoked to return the data changes.
Registers a data change event listener for the RDB store. When the data in the RDB store changes, a callback is invoked to return the data changes.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
......@@ -3327,12 +3994,12 @@ Registers the data change event listener for the RDB store. When the data in the
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| event | string | Yes | Event to observe. The value is **dataChange**, which indicates a data change event. |
| type | [SubscribeType](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-data-relationalStore.md#subscribetype) | Yes | Subscription type to register. |
| type | [SubscribeType](#subscribetype) | Yes | Subscription type to register. |
| observer | Callback&lt;Array&lt;string&gt;&gt; | Yes | Callback invoked to return the data change. **Array<string>** indicates the IDs of the peer devices whose data in the database is changed.|
**Example**
```
```js
function storeObserver(devices) {
for (let i = 0; i < devices.length; i++) {
console.info(`device= ${devices[i]} data changed`);
......@@ -3349,7 +4016,7 @@ try {
on(event: 'dataChange', type: SubscribeType, observer: Callback&lt;Array&lt;string&gt;&gt;\| Callback&lt;Array&lt;ChangeInfo&gt;&gt;): void
Registers the data change event listener for the RDB store. When the data in the RDB store changes, a callback is invoked to return the data changes.
Registers a data change event listener for the RDB store. When the data in the RDB store changes, a callback is invoked to return the data changes.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
......@@ -3359,7 +4026,7 @@ Registers the data change event listener for the RDB store. When the data in the
| -------- | ----------------------------------- | ---- | ------------------------------------------- |
| event | string | Yes | Event to observe. The value is **dataChange**, which indicates a data change event. |
| type | [SubscribeType](#subscribetype) | Yes | Subscription type to register.|
| observer | Callback&lt;Array&lt;string&gt;&gt; \| Callback&lt;Array&lt;[ChangeInfo](#changeinfo10)&gt;&gt; | Yes | Callback invoked to return the data change event.<br>If **type** is **SUBSCRIBE_TYPE_REMOTE**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the IDs of the peer devices with data changes.<br> If **type** is **SUBSCRIBE_TYPE_CLOUD**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the cloud accounts with data changes.<br> If **type** is **SUBSCRIBE_TYPE_CLOUD_DETAILS**, **observer** must be **Callback&lt;Array&lt;ChangeInfo&gt;&gt;**, where **Array&lt;ChangeInfo&gt;** specifies the details about the device-cloud synchronization.|
| observer | Callback&lt;Array&lt;string&gt;&gt; \| Callback&lt;Array&lt;[ChangeInfo](#changeinfo10)&gt;&gt; | Yes | Callback invoked to return the data change.<br>If **type** is **SUBSCRIBE_TYPE_REMOTE**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the IDs of the peer devices with data changes.<br>If **type** is **SUBSCRIBE_TYPE_CLOUD**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the cloud accounts with data changes.<br>If **type** is **SUBSCRIBE_TYPE_CLOUD_DETAILS**, **observer** must be **Callback&lt;Array&lt;ChangeInfo&gt;&gt;**, where **Array&lt;ChangeInfo&gt;** specifies the details about the device-cloud synchronization.|
**Example**
......@@ -3376,6 +4043,44 @@ try {
}
```
### on<sup>10+</sup>
on(event: string, interProcess: boolean, observer: Callback\<void>): void
Registers an intra-process or inter-process event listener for the RDB store. This callback is invoked by [emit](#emit10).
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | --------------- | ---- | ------------------------------------------------------------ |
| event | string | Yes | Event name to observe. |
| interProcess | boolean | Yes | Type of the event to observe.<br>The value **true** means the inter-process event.<br>The value **false** means the intra-process event. |
| observer | Callback\<void> | Yes | Callback invoked to return the result. |
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | -------------------------------------- |
| 14800000 | Inner error. |
| 14800050 | Failed to obtain subscription service. |
**Example**
```js
function storeObserver() {
console.info(`storeObserver`);
}
try {
store.on('storeObserver', false, storeObserver);
} catch (err) {
console.error(`Register observer failed, code is ${err.code},message is ${err.message}`);
}
```
### off('dataChange')
off(event:'dataChange', type: SubscribeType, observer: Callback&lt;Array&lt;string&gt;&gt;): void
......@@ -3389,7 +4094,7 @@ Unregisters the data change event listener.
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| event | string | Yes | Event type. The value is **dataChange**, which indicates a data change event. |
| type | [SubscribeType](#subscribetype)| Yes | Subscription type to unregister. |
| type | [SubscribeType](#subscribetype) | Yes | Subscription type to unregister. |
| observer | Callback&lt;Array&lt;string&gt;&gt; | Yes | Callback for the data change event. **Array<string>** indicates the IDs of the peer devices whose data in the database is changed.|
**Example**
......@@ -3419,9 +4124,9 @@ Unregisters the data change event listener.
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------- | ---- | ------------------------------------------ |
| event | string | Yes | Event to observe. The value is **dataChange**, which indicates a data change event. |
| type | [SubscribeType](#subscribetype) | Yes | Subscription type to register. |
| observer | Callback&lt;Array&lt;string&gt;&gt;\| Callback&lt;Array&lt;[ChangeInfo](#changeinfo10)&gt;&gt; | No| Callback invoked to return the result.<br>If **type** is **SUBSCRIBE_TYPE_REMOTE**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the IDs of the peer devices with data changes.<br> If **type** is **SUBSCRIBE_TYPE_CLOUD**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the cloud accounts with data changes.<br> If **type** is **SUBSCRIBE_TYPE_CLOUD_DETAILS**, **observer** must be **Callback&lt;Array&lt;ChangeInfo&gt;&gt;**, where **Array&lt;ChangeInfo&gt;** specifies the details about the device-cloud synchronization.<br> If **observer** is not specified, listening for all data change events of the specified **type** will be canceled.|
| event | string | Yes | Event type. The value is **dataChange**, which indicates a data change event. |
| type | [SubscribeType](#subscribetype) | Yes | Subscription type to unregister. |
| observer | Callback&lt;Array&lt;string&gt;&gt;\| Callback&lt;Array&lt;[ChangeInfo](#changeinfo10)&gt;&gt; | No| Callback invoked to return the result.<br>If **type** is **SUBSCRIBE_TYPE_REMOTE**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the IDs of the peer devices with data changes.<br>If **type** is **SUBSCRIBE_TYPE_CLOUD**, **observer** must be **Callback&lt;Array&lt;string&gt;&gt;**, where **Array&lt;string&gt;** specifies the cloud accounts with data changes.<br>If **type** is **SUBSCRIBE_TYPE_CLOUD_DETAILS**, **observer** must be **Callback&lt;Array&lt;ChangeInfo&gt;&gt;**, where **Array&lt;ChangeInfo&gt;** specifies the details about the device-cloud synchronization.<br>If **observer** is not specified, listening for all data change events of the specified **type** will be canceled.|
**Example**
......@@ -3438,6 +4143,73 @@ try {
}
```
### off<sup>10+</sup>
off(event: string, interProcess: boolean, observer?: Callback\<void>): void
Unregisters the data change event listener.
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ | --------------- | ---- | ------------------------------------------------------------ |
| event | string | Yes | Name of the event to unsubscribe from. |
| interProcess | boolean | Yes | Type of the event.<br>The value **true** means the inter-process event.<br>The value **false** means the intra-process event.|
| observer | Callback\<void> | No | Callback for the event to unregister. If this parameter is specified, the specified callback will be unregistered. If this parameter is not specified, all callbacks of the specified event will be unregistered.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | -------------------------------------- |
| 14800000 | Inner error. |
| 14800050 | Failed to obtain subscription service. |
**Example**
```js
function storeObserver() {
console.info(`storeObserver`);
}
try {
store.off('storeObserver', false, storeObserver);
} catch (err) {
console.error(`Register observer failed, code is ${err.code},message is ${err.message}`);
}
```
### emit<sup>10+</sup>
emit(event: string): void
Triggers the inter-process or intra-process event listener registered through [on](#on10).
**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | -------------------- |
| event | string | Yes | Name of the event.|
**Error codes**
For details about the error codes, see [RDB Error Codes](../errorcodes/errorcode-data-rdb.md).
| **ID**| **Error Message** |
| ------------ | -------------------------------------- |
| 14800000 | Inner error. |
| 14800050 | Failed to obtain subscription service. |
**Example**
```js
store.emit('storeObserver');
```
## ResultSet
Provides APIs to access the result set obtained by querying the RDB store. A result set is a set of results returned after **query()** is called.
......@@ -3857,7 +4629,7 @@ Obtains the value of the Long type based on the specified column and the current
| Type | Description |
| ------ | ------------------------------------------------------------ |
| number | Value obtained.<br>The value range supported by API is **Number.MIN_SAFE_INTEGER** to **Number.MAX_SAFE_INTEGER**. If the value is out of this range, use [getDouble](#getdouble).|
| number | Value obtained.<br>The value range supported by this API is **Number.MIN_SAFE_INTEGER** to **Number.MAX_SAFE_INTEGER**. If the value is out of this range, use [getDouble](#getdouble).|
**Error codes**
......
en/application-dev/reference/errorcodes/errorcode-data-rdb.md
浏览文件 @ f1affe03
......@@ -117,4 +117,59 @@ Data is added, deleted, and modified continuously without closing the read trans
**Solution**
1. Check for unclosed result sets or transactions.
2. Closes all result sets or transactions.
## 14800050 Failed to Obtain the Subscription Service
**Error Message**
Failed to obtain subscription service.
**Description**
The error code is returned when the subscription service failed to be obtained.
**Possible Causes**
The platform does not support service subscription.
**Solution**
Deploy the subscription service on the platform.
## 14801001 Stage Model Required
**Error Message**
Only supported in stage mode.
**Description**
This operation can be performed only on the stage model.
**Possible Causes**
The context is not a stage model.
**Solution**
Perform the operation on the stage model.
## 14801002 Invalid dataGroupId in storeConfig
**Error Message**
The data group id is not valid.
**Description**
The **dataGroupId** parameter is invalid.
**Possible Causes**
The **dataGroupId** is not obtained from the AppGallery.
**Solution**
Obtain **dataGroupId** from the AppGallery and pass it to **storeConfig** correctly.
en/application-dev/reference/errorcodes/errorcode-preferences.md
浏览文件 @ f1affe03
......@@ -23,3 +23,57 @@ The possible causes are as follows:
1. Check that the file name is correct.
2. Check that the file path is correct.
## 15500019 Failed to Obtain the Subscription Service
**Error Message**
Failed to obtain subscription service.
**Description**
Failed to obtain the subscription service in inter-process event subscription.
**Possible Causes**
The platform does not support service subscription.
**Solution**
Deploy the subscription service on the platform.
## 14801001 Stage Model Required
**Error Message**
Only supported in stage mode.
**Description**
This operation can be performed only on the stage model.
**Possible Causes**
The context is not a stage model.
**Solution**
Perform the operation on the stage model.
## 15501002 The dataGroupId parameter in Options is invalid.
**Error Message**
The data group id is not valid.
**Description**
The **dataGroupId** parameter is invalid.
**Possible Causes**
The **dataGroupId** is not obtained from the AppGallery.
**Solution**
Obtain **dataGroupId** from the AppGallery and pass it correctly.
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或