开发指南提交

Signed-off-by: Nsongruirui <songruirui1@huawei.com>

zh-cn/application-dev/database/database-datashare-guildlines.md

+# DataShare开发指导
+## 场景介绍
+DataShare，用于应用管理其自身数据，并支持同个设备上不同应用间的数据共享。
+
+DataShare可分为数据的提供方和访问方两部分，提供方可以选择性实现数据的增、删、改、查，以及文件打开等功能，并对外提供这些接口。访问方利用工具类，便可以访问提供方提供的各种功能。
+
+## 接口说明
+
+**表1** DataShare提供方需要实现的API
+
+|接口名|描述|
+|:------|:------|
+|onCreate?(want: Want, callback: AsyncCallback<void>): void|DataShareExtensionAbility生命周期回调，在数据提供方应用创建时回调，执行初始化业务逻辑操作，如创建数据库。|
+|insert?(uri: string, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数，在访问方向数据库中插入数据时回调。|
+|update?(uri: string, predicates: DataSharePredicates, valueBucket: ValuesBucket, callback: AsyncCallback<number>): void|业务函数，在访问方更新数据时回调。|
+|query?(uri: string, predicates: DataSharePredicates, columns: Array<string>, callback: AsyncCallback<Object>): void|业务函数，在访问方查询数据时回调。|
+|delete?(uri: string, predicates: DataSharePredicates, callback: AsyncCallback<number>): void|业务函数，在访问方删除数据时回调。|
+|batchInsert?(uri: string, valueBuckets: Array<ValuesBucket>, callback: AsyncCallback<number>): void|业务函数，在访问方调用批量插入数据接口时回调。|
+|getType?(uri: string, callback: AsyncCallback<string>): void|业务函数，返回URI所指定数据的MIME类型。|
+|getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void|业务函数，返回支持的文件的MIME类型。|
+|normalizeUri?(uri: string, callback: AsyncCallback<string>): void|业务函数，实现对URI进行规范化。一个规范化的URI可以支持跨设备使用、持久化、备份和还原等，当上下文改变时仍然可以引用到相同的数据项。|
+|denormalizeUri?(uri: string, callback: AsyncCallback<string>): void|业务函数，实现将规范化URI转换成非规范化的URI。|
+|openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void|业务函数，在访问方调用打开文件时回调。提供方需要实现按mode所指定的方式打开uri所指定的文件，并返回其文件描述符。|
+
+
+## 开发步骤
+### 数据提供方应用的开发（仅限系统应用）
+
+1. 数据提供方（也称服务端）应用的开发者可继承于DataShareExtensionAbility，并根据自己的需求或目标选择性实现Insert、Query、Update、Delete等接口的业务内容，例如数据提供方只提供查询服务，则可只重写查询接口。业务的实现可由开发者自定义，例如数据存储实现可以选择OpenHarmony支持的数据库，也可以直接使用文件进行读写，甚至可以访问网络数据。由此可见，DataShare并不产生或存储数据，它只是“数据的搬运工”。
+
+   创建数据提供方的代码示例如下：
+
+   ```ets
+   import Extension from '@ohos.application.DataShareExtensionAbility'
+   import rdb from '@ohos.data.rdb';
+   import fileIo from '@ohos.fileio'
+   import dataSharePredicates from '@ohos.data.dataSharePredicates'
+   
+   
+   let DB_NAME = "DB00.db";
+   let TBL_NAME = "TBL00";
+   let DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS "
+   + TBL_NAME
+   + " (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, isStudent BOOLEAN, Binary BINARY)";
+   
+   let rdbStore;
+   let result;
+   
+   export default class DataShareExtAbility extends Extension {
+       private rdbStore_;
+   
+       onCreate(want, callback) {
+           result = this.context.cacheDir + '/datashare.txt'
+           rdb.getRdbStore(this.context, {
+               name: DB_NAME
+           }, 1, function (err, data) {
+               rdbStore = data;
+               rdbStore.executeSql(DDL_TBL_CREATE, [], function (err) {
+                   console.log('DataShareExtAbility onCreate, executeSql done err:' + JSON.stringify(err));
+               });
+               callback();
+           });
+       }
+   
+       insert(uri, value, callback) {
+           if (value == null) {
+               console.info('invalid valueBuckets');
+               return;
+           }
+           rdbStore.insert(TBL_NAME, value, function (err, ret) {
+               console.info('callback ret:' + ret);
+               if (callback != undefined) {
+                   callback(err, ret);
+               }
+           });
+       }
+   
+       update(uri, predicates, value, callback) {
+           if (predicates == null || predicates == undefined) {
+               console.info('invalid predicates');
+               return;
+           }
+           try {
+               rdbStore.update(TBL_NAME,value, predicates, function (err, ret) {
+                   console.info('callback ret:' + ret);
+                   console.info('callback err:' + err);
+                   if (callback != undefined) {
+                       callback(err, ret);
+                   }
+               });
+           } catch (err) {
+               console.error('error' + err);
+           }
+       }
+   
+       delete(uri, predicates, callback) {
+           if (predicates == null || predicates == undefined) {
+               console.info('invalid predicates');
+               return;
+           }
+           try {
+               rdbStore.delete(TBL_NAME,predicates, function (err, ret) {
+                   console.info('ret:' + ret);
+                   if (callback != undefined) {
+                       callback(err, ret);
+                   }
+               });
+           } catch (err) {
+               console.error('error' + err);
+           }
+       }
+   
+       query(uri, predicates, columns,  callback) {
+           if (predicates == null || predicates == undefined) {
+               console.info('invalid predicates');
+           }
+           try {
+               rdbStore.query(TBL_NAME, predicates, columns, function (err, resultSet) {
+                   if (resultSet != undefined) {
+                       console.info('resultSet.rowCount: ' + resultSet.rowCount);
+                   }
+                   if (callback != undefined) {
+                       callback(err, resultSet);
+                   }
+               });
+           } catch (err) {
+               console.error('error' + err);
+           }
+       }
+   
+       batchInsert(uri: string, valueBuckets, callback) {
+           if (valueBuckets == null || valueBuckets.length == undefined) {
+               console.info('invalid valueBuckets');
+               return;
+           }
+           let resultNum = valueBuckets.length
+           valueBuckets.forEach(vb => {
+               console.info('valueBuckets:' + JSON.stringify(vb));
+               rdbStore.insert(TBL_NAME, vb, function (err, ret) {
+                   console.info('callback ret:' + ret);
+                   if (callback != undefined) {
+                       callback(err, resultNum);
+                   }
+               });
+           });
+       }
+   
+       getType(uri: string,callback) {
+           let ret = "image";
+           console.info('ret:' + ret);
+           let err = {"code":0};
+           callback(err,ret);
+           return ret;
+       }
+   
+       getFileTypes(uri: string, mimeTypeFilter: string, callback) {
+           let ret = new Array("type01", "type02", "type03");
+           console.info('ret:' + ret);
+           let err = {"code":2};
+           callback(err,ret);
+           return ret;
+       }
+   
+       openFile(uri: string, mode: string, callback) {
+           fileIo.open(result, 0o2 | 0o100, 0o666, function(err, fd) {
+               if(err) {
+                   console.info('OpenFile err = ' + err);
+               }
+               let num = fileIo.writeSync(fd, "this is a interesting test of DataShare");
+               callback(err,fd);
+           })
+       }
+   
+       normalizeUri(uri: string,callback) {
+           let ret = "normalize+" + uri;
+           console.info('ret:' + ret);
+           let err = {"code":2};
+           callback(err,ret);
+       }
+   
+       denormalizeUri(uri: string,callback) {
+           let ret = "denormalize+" + uri;
+           console.info('ret:' + ret);
+           let err = {"code":2};
+           callback(err,ret);
+           return ret;
+       }
+   };
+   ```
+
+2. 子模块配置
+
+   | Json重要字段 | 备注说明                                                     |
+   | ------------ | ------------------------------------------------------------ |
+   | "name"       | Ability名称，对应Ability派生的Data类名。                     |
+   | "type"       | Ability类型，Data对应的Ability类型为”data“。                 |
+   | "uri"        | 通信使用的URI。                                              |
+   | "visible"    | 对其他应用是否可见，设置为true时，Data才能与其他应用进行通信传输数据。 |
+
+   **module.json5配置样例**
+
+   ```ets
+   "extensionAbilities": [
+     {
+       "srcEntrance": "./ets/DataShareExtAbility/DataShareExtAbility.ts",
+       "name": "DataShareExtAbility",
+       "icon": "$media:icon",
+       "description": "$string:description_datashareextability",
+       "type": "dataShare",
+       "uri": "datashare://com.samples.datasharetest.DataShare",
+       "visible": true
+     }
+   ]
+   ```
+
+### 数据访问方应用的开发
+#### 数据访问方应用开发指导
+
+
+1. 导入基础依赖包，以及获取与数据提供方通信的URI字符串。
+
+   其中，基础依赖包包括：
+
+   - @ohos.application.Ability
+   - @ohos.data.dataShare
+   - @ohos.data.dataSharePredicates
+
+   ```ets
+   // 作为参数传递的URI，与module.json5中定义的URI的区别是多了一个"/"，是因为作为参数传递的URI中，在第二个与第三个"/"中间，存在一个DeviceID的参数
+   import Ability from '@ohos.application.Ability'
+   import dataShare from '@ohos.data.dataShare'
+   import dataSharePredicates from '@ohos.data.dataSharePredicates'
+   
+   let dsHelper;
+   let abilityContext;
+   let dseUri = ("datashare:///com.samples.datasharetest.DataShare");
+   ```
+
+2. 创建工具接口类对象。
+
+   工具接口类对象DataShareHelper相关接口可参考[DataShareHelper](../reference/apis/js-apis-dataShareHelper.md)文档。
+   ```ets
+   export default class MainAbility extends Ability {
+   	onWindowStageCreate(windowStage) {
+   		abilityContext = this.context;
+   		dataShare.createDataShareHelper(abilityContext, dseUri, (err,data)=>{
+   			dsHelper = data;
+   		});
+   	}
+   }
+   ```
+
+3. 获取到接口类对象后，便可利用其提供的接口访问提供方提供的服务，如进行数据的增删改查等。
+
+   ```ets
+   // 构建一条数据
+   var valuesBucket = {"name": "ZhangSan", "age": 21, "isStudent": false, "Binary": new Uint8Array([1,2,3])};
+   var updateBucket = {"name": "LiSi", "age": 18, "isStudent": true, "Binary": new Uint8Array([1,2,3])};
+   let da =  new dataSharePredicates.DataSharePredicates();
+   var valArray =new Array("*");
+   let people = new Array(
+   	{"name": "LiSi", "age": 41, "Binary": ar},
+   	{"name": "WangWu", "age": 21, "Binary": arr},
+   	{"name": "ZhaoLiu", "age": 61, "Binary": arr});
+   ```
+
+   ```ets
+   // 插入一条数据，callback方式调用:
+   dsHelper.insert(dseUri, valuesBucket, (err,data) => {
+       console.log("dsHelper insert result: " + data);
+   });
+   ```
+
+   ```ets
+   // 插入一条数据，promise方式调用:
+   let ret = await dsHelper.insert(dseUri, valuesBucket);
+   ```
+
+   ```ets
+   // 删除指定的数据，callback方式调用:
+   dsHelper.delete(dseUri, da, (err,data) => {
+       console.log("dsHelper delete result: " + data);
+   });
+   ```
+
+   ```ets
+   // 删除指定的数据，promise方式调用:
+   let ret = await dsHelper.delete(dseUri, da);
+   ```
+
+   ```ets
+   // 更新数据，callback方式调用:
+   dsHelper.update(dseUri, da, updateBucket, (err,data) => {
+       console.log("dsHelper update result: " + data);
+   });
+   ```
+
+   ```ets
+   // 更新数据，promise方式调用:
+   let ret = await dsHelper.update(dseUri, da, updateBucket);
+   ```
+
+   ```ets
+   // 查询数据，callback方式调用:
+   dsHelper.query(dseUri, da, valArray, (err,data) => {
+       console.log("dsHelper query result: " + data);
+   });
+   ```
+
+   ```ets
+   // 查询数据，promise方式调用:
+   let result = await dsHelper.query(dseUri, da, valArray);
+   ```
+
+## 相关实例
+
+针对DataShare开发，有以下相关实例可供参考：
+
+待补充。
+
+- [`DataShare`：DataShare的创建与访问（eTS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/ability/DataAbility)

zh-cn/application-dev/database/database-datashare-overview.md

+# 数据共享开发概述
+
+## 数据共享简介
+
+DataShare即数据共享模块用于应用管理其自身数据，也提供了向其他应用共享以及管理其数据的方法，目前仅支持同个设备上应用之间的数据共享。
+
+在许多应用场景中都需要将我们程序中的数据共享给其他程序，例如电话簿、短信、媒体库等等，当然并不是所有的数据都是允许其他应用去访问的，例如账号、密码，有些数据只允许其他应用查询不允许其增删改，例如短信，这就要求我们要对访问者进行权限的检查和限制。
+
+OpenHarmony提供的持久化存储方案如文件、分布式数据库，要么有隐私泄漏的风险，要么只能在当前应用中访问，要么需要开发者自己去封装，一个安全、便捷的可以跨设备跨应用的数据共享机制是必需的，DataShare便应运而生。
+
+对于数据提供者来说，可以使用DataShare提供的框架轻松的实现向其他应用共享数据，而不需要自己进行繁琐的封装；对于数据访问方来说，因DataShare的访问方式不会因数据提供的方式而不同，所以只需要学习和使用一套接口，既减小了开发难度又节省了学习多种接口的时间。
+
+## 基本概念
+
+
+在进行应用的开发前，开发者应了解以下基本概念：
+
+
+- 数据提供方
+
+  提供数据及实现相关业务的应用程序，也称为生产者或服务端。
+
+- 数据访问方
+
+  访问数据提供方所提供的数据或业务的应用程序，也称为消费者或客户端。
+
+- 数据集
+
+  只用户要插入的数据集合，可以是一条或多条数据。数据集以键值对的形式存在，值支持多种数据类型。
+
+- 结果集
+  指用户查询之后的结果集合，可以对数据进行访问。结果集提供了灵活的数据访问方式，可以更方便的拿到用户想要的数据。
+
+- 谓词
+  描述筛选条件的集合。既可以是查询的条件也可以是删除的条件也可以是更新的条件。
+
+## 运作机制
+
+**图 1**  DataShare运作机制<a name="fig3330103712254"></a>
+
+
+![](figures/zh-cn_DataShare.png)
+
+DataShareExtAbility模块即为数据提供方，实现跨应用数据共享的相关业务。DataShareHelper模块为数据访问方提供操作DataShareExtAbility即数据提供方的接口。数据访问方与提供方通过IPC进行通信，数据提供方实现可以是数据库，也可以是其他数据存储方式。
+
+ResultSet模块提供跨应用操作或访问查询出的结果集的接口，结果集使用共享内存实现。
+
+## 约束与限制
+
+**数据共享的约束与限制**：
+
+- DataShare受到数据提供方所使用数据库，例如支持的数据模型，Key的长度、Value的长度、每个应用程序最多支持同时打开数据库数量都受到数据库的限制。
+
+- 因DataShare内部实现依赖于IPC通信，所以支持数据量的大小受到IPC通信的约束与限制。