!20923 RDB模块新增接口及错误码补充

Merge pull request !20923 from lihuihui/master

zh-cn/application-dev/database/data-persistence-by-rdb-store.md

@@ -252,6 +252,10 @@
 
    调用deleteRdbStore()方法，删除数据库及数据库相关文件。示例代码如下：
 
+   > **说明：**
+   >
+   > 删除成功后，建议将数据库对象置为null。
+   
    Stage模型示例：
 
      
@@ -265,6 +269,7 @@
            console.error(`Failed to delete RdbStore. Code:${err.code}, message:${err.message}`);
            return;
          }
+         store = null;
          console.info('Succeeded in deleting RdbStore.');
        });
      }
@@ -285,6 +290,7 @@
        console.error(`Failed to delete RdbStore. Code:${err.code}, message:${err.message}`);
        return;
      }
+     store = null;
      console.info('Succeeded in deleting RdbStore.');
    });
    ```

zh-cn/application-dev/reference/apis/js-apis-data-relationalStore.md

@@ -43,6 +43,8 @@ getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback<Rd
 | 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.                             |
 
 **示例：**
 
@@ -127,6 +129,8 @@ getRdbStore(context: Context, config: StoreConfig): Promise<RdbStore>
 | 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.                             |
 
 **示例：**
 
@@ -182,7 +186,9 @@ class EntryAbility extends UIAbility {
 
 deleteRdbStore(context: Context, name: string, callback: AsyncCallback<void>): void
 
-删除数据库，使用callback异步回调。
+删除数据库文件，使用callback异步回调。
+
+删除成功后，建议将数据库对象置为null。
 
 **系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
 
@@ -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<void>
 
 使用指定的数据库文件配置删除数据库，使用Promise异步回调。
 
+删除成功后，建议将数据库对象置为null。
+
 **系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
 
 **参数**
@@ -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
+
+使用指定的数据库文件配置删除数据库，使用callback异步回调。
+
+删除成功后，建议将数据库对象置为null。若数据库文件处于公共沙箱目录下，则删除数据库时必须使用该接口，当存在多个进程操作同一个数据库的情况，建议向其他进程发送数据库删除通知使其感知并处理。
+
+**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
+
+**参数：**
+
+| 参数名   | 类型                        | 必填 | 说明                                                         |
+| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
+| context  | Context                     | 是   | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-uiAbilityContext.md)。 |
+| config   | [StoreConfig](#storeconfig) | 是   | 与此RDB存储相关的数据库配置。                                |
+| callback | AsyncCallback&lt;void&gt;   | 是   | 指定callback回调函数。                                       |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[关系型数据库错误码](../errorcodes/errorcode-data-rdb.md)。
+
+| **错误码ID** | **错误信息**                                                |
+| ------------ | ----------------------------------------------------------- |
+| 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.                             |
+
+**示例：**
+
+FA模型示例：
+
+```js
+import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取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模型示例：
+
+```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>
+
+使用指定的数据库文件配置删除数据库，使用Promise异步回调。
+
+删除成功后，建议将数据库对象置为null。若数据库文件处于公共沙箱目录下，则删除数据库时必须使用该接口，当存在多个进程操作同一个数据库的情况，建议向其他进程发送数据库删除通知使其感知并处理。
+
+**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
+
+**参数**
+
+| 参数名  | 类型                        | 必填 | 说明                                                         |
+| ------- | --------------------------- | ---- | ------------------------------------------------------------ |
+| context | Context                     | 是   | 应用的上下文。 <br>FA模型的应用Context定义见[Context](js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](js-apis-inner-application-uiAbilityContext.md)。 |
+| config  | [StoreConfig](#storeconfig) | 是   | 与此RDB存储相关的数据库配置。                                |
+
+**返回值**：
+
+| 类型                | 说明                      |
+| ------------------- | ------------------------- |
+| Promise&lt;void&gt; | 无返回结果的Promise对象。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[关系型数据库错误码](../errorcodes/errorcode-data-rdb.md)。
+
+| **错误码ID** | **错误信息**                                                |
+| ------------ | ----------------------------------------------------------- |
+| 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.                             |
+
+**示例：**
+
+FA模型示例：
+
+```js
+import featureAbility from '@ohos.ability.featureAbility'
+
+// 获取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模型示例：
+
+```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}`);
@@ -316,6 +483,7 @@ class EntryAbility extends UIAbility {
 | name          | string        | 是   | 数据库文件名。                                            |
 | securityLevel | [SecurityLevel](#securitylevel) | 是   | 设置数据库安全级别                                        |
 | encrypt       | boolean       | 否   | 指定数据库是否加密，默认不加密。<br/> true:加密。<br/> false:非加密。 |
+| dataGroupId<sup>10+</sup> | string | 否 | 应用组ID，需要向应用市场获取。<br/>**模型约束：** 此属性仅在Stage模型下可用。<br/>从API version 10开始，支持此可选参数。指定在此dataGroupId对应的沙箱路径下创建relationalStore实例，当此参数不填时，默认在本应用沙箱目录下创建relationalStore实例。 |
 
 ## SecurityLevel
 
@@ -3775,6 +3943,44 @@ try {
 }
 ```
 
+### on<sup>10+</sup>
+
+on(event: string, interProcess: boolean, observer: Callback\<void>): void
+
+注册数据库的进程内或者进程间事件监听。当调用[emit](#emit10)接口时，将调用回调。
+
+**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
+
+**参数：**
+
+| 参数名       | 类型            | 必填 | 说明                                                         |
+| ------------ | --------------- | ---- | ------------------------------------------------------------ |
+| event        | string          | 是   | 订阅事件名称。                                               |
+| interProcess | boolean         | 是   | 指定是进程间还是本进程订阅。<br/> true：进程间。<br/> false：本进程。 |
+| observer     | Callback\<void> | 是   | 回调函数。                                                   |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[关系型数据库错误码](../errorcodes/errorcode-data-rdb.md)。
+
+| **错误码ID** | **错误信息**                           |
+| ------------ | -------------------------------------- |
+| 14800000     | Inner error.                           |
+| 14800050     | Failed to obtain subscription service. |
+
+**示例：**
+
+```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
@@ -3837,6 +4043,73 @@ try {
 }
 ```
 
+### off<sup>10+</sup>
+
+off(event: string, interProcess: boolean, observer?: Callback\<void>): void
+
+取消数据变更的事件监听。
+
+**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
+
+**参数：**
+
+| 参数名       | 类型            | 必填 | 说明                                                         |
+| ------------ | --------------- | ---- | ------------------------------------------------------------ |
+| event        | string          | 是   | 取消订阅事件名称。                                           |
+| interProcess | boolean         | 是   | 指定是进程间还是本进程取消订阅。<br/> true：进程间。<br/> false：本进程。 |
+| observer     | Callback\<void> | 否   | 该参数存在，则取消指定Callback监听回调，否则取消该event事件的所有监听回调。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[关系型数据库错误码](../errorcodes/errorcode-data-rdb.md)。
+
+| **错误码ID** | **错误信息**                           |
+| ------------ | -------------------------------------- |
+| 14800000     | Inner error.                           |
+| 14800050     | Failed to obtain subscription service. |
+
+**示例：**
+
+```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
+
+通知通过[on](#on10)注册的进程间或者进程内监听事件。
+
+**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core
+
+**参数：**
+
+| 参数名 | 类型   | 必填 | 说明                 |
+| ------ | ------ | ---- | -------------------- |
+| event  | string | 是   | 通知订阅事件的名称。 |
+
+**错误码：**
+
+以下错误码的详细介绍请参见[关系型数据库错误码](../errorcodes/errorcode-data-rdb.md)。
+
+| **错误码ID** | **错误信息**                           |
+| ------------ | -------------------------------------- |
+| 14800000     | Inner error.                           |
+| 14800050     | Failed to obtain subscription service. |
+
+**示例：**
+
+```js
+store.emit('storeObserver');
+```
+
 ## ResultSet
 
 提供通过查询数据库生成的数据库结果集的访问方法。结果集是指用户调用关系型数据库查询接口之后返回的结果集合，提供了多种灵活的数据访问方式，以便用户获取各项数据。

zh-cn/application-dev/reference/errorcodes/errorcode-data-rdb.md

@@ -116,5 +116,61 @@ WAL文件大小超过默认上限（200M）。
 
 **处理步骤**
 
-1. 检查结果集或者事务是否未关闭。
-2. 关闭所有的结果集或者事务。
+检查结果集或者事务是否未关闭。
+
+关闭所有的结果集或者事务。
+
+## 14800050 获取订阅服务失败
+
+**错误信息**
+
+Failed to obtain subscription service.
+
+**错误描述**
+
+获取订阅服务失败。
+
+**可能原因**
+
+当前平台不支持订阅服务。
+
+**处理步骤**
+
+需要在当前平台部署订阅服务。
+
+## 14801001 上下文环境非Stage模型
+
+**错误信息**
+
+ Only supported in stage mode.
+
+**错误描述**
+
+该操作仅支持Stage模型。
+
+**可能原因**
+
+当前上下文环境非Stage模型。
+
+**处理步骤**
+
+切换当前上下文环境，使用Stage模型。
+
+## 14801002 storeConfig中传入的dataGroupId参数非法
+
+**错误信息**
+
+The data group id is not valid.
+
+**错误描述**
+
+使用非法dataGroupId参数。
+
+**可能原因**
+
+使用的dataGroupId不是从应用市场正常申请的。
+
+**处理步骤**
+
+从应用市场申请dataGroupId，并正确传入该参数。
+