未验证 提交 19679f4b 编写于 作者: O openharmony_ci 提交者: Gitee

!13749 Complete related documents of commonlibrary/c_utils.

Merge pull request !13749 from huangyuchen/docsDEV
# Utils FAQ<a name="EN-US_TOPIC_0000001058735275"></a>
## 1. Failed to run the KV store on the LiteOS Cortex-A kernel \(Hi3516 or Hi3518\) due to incorrect path setting for the KV store<a name="section2041345718513"></a>
**Symptom**
When the LiteOS Cortex-A kernel \(Hi3516 or Hi3518 platform\) directly calls the API provided by the KV store, the compiled executable program fails to run.
**Possible Causes**
The compiled executable program is run directly without being converted to an application using **AbilityKit** APIs. In this case, the Bundle Manager Service \(BMS\) cannot correctly set the path for storing application data during application installation. As a result, the KV store fails to run.
**Solution**
Call the **UtilsSetEnv** function of the KV store to set the data storage path.
```
UtilsSetEnv("/storage/com.example.kv");
```
# Utils Development<a name="EN-US_TOPIC_0000001059307279"></a>
## Available APIs<a name="section1633115419401"></a>
**Table 1** APIs for file operations
| Function | Description |
| ---------- | ------------- |
| int UtilsFileOpen(const char* path, int oflag, int mode) | Opens or creates a file. |
| int UtilsFileClose(int fd) | Closes a file with a specified file descriptor. |
| int UtilsFileRead(int fd, char *buf, unsigned int len) | Reads a specified length of data from a file with the specified file descriptor and writes the data into the buffer. |
| int UtilsFileWrite(int fd, const char *buf, unsigned int len) | Writes a specified length of data into a file with the specified file descriptor. |
| int UtilsFileDelete(const char *path) | Deletes a specified file. |
| int UtilsFileStat(const char *path, unsigned int *fileSize) | Obtains the file size. |
| int UtilsFileSeek(int fd, int offset, unsigned int whence) | Adjusts the read and write position offset in a file. |
| int UtilsFileCopy(const char* src, const char* dest) | Copies the source file to a target file. |
| int UtilsFileMove(const char* src, const char* dest) | Moves the source file into a target file. |
Sample code for file operations:
# Commonlibrary Development Guidelines<a name="EN-US_TOPIC_0000001059307279"></a>
## Overview
The **commonlibrary** subsystem stores basic OpenHarmony components which provides common enhanced APIs for development in C, C++ and JS that are commonly used by OpenHarmony service subsystems and upper-layer applications. Including repositories:
```
// Open a file and write data.
char fileName[] = "testfile";
static const char def[] = "utils_file_operation implement.";
int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0);
printf("file handle = %d\n", fd);
int ret = UtilsFileWrite(fd, def, strlen(def));
printf("write ret = %d\n", ret);
// Adjust the position offset in the file.
ret = UtilsFileSeek(fd, 5, SEEK_SET_FS);
printf("lseek ret = %d\n", ret);
// Read data and close the file.
char buf[64] = {0};
int readLen = UtilsFileRead(fd, buf, 64);
ret = UtilsFileClose(fd);
printf("read len = %d : buf = %s\n", readLen, buf);
// Obtain the file size.
int fileLen = 0;
ret = UtilsFileStat(fileName, &fileLen);
printf("file size = %d\n", fileLen);
// Delete the file.
ret = UtilsFileDelete(fileName);
printf("delete ret = %d\n", ret);
```
**Table 2** APIs for KV store operations
| Function | Description |
| ----------- | ---------------- |
| int UtilsGetValue(const char* key, char* value, unsigned int len) | Obtains the value matching a specified key from the file system or cache. |
| int UtilsSetValue(const char* key, const char* value) | Adds or updates the value matching a specified key in the file system or cache. |
| int UtilsDeleteValue(const char* key) | Deletes the value matching a specified key from the file system or cache. |
Sample code for the KV store:
```
// Set the value matching the specified key.
char key[] = "rw.sys.version_100";
char value[] = "Hello kv operation implement!";
int ret = UtilsSetValue(key, value);
printf("UtilsSetValue set ret = %d\n", ret);
// Obtain the value matching the specified key.
char temp[128] = {0};
ret = UtilsGetValue(key, temp, 128);
printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp);
// Delete the value matching the specified key.
ret = UtilsDeleteValue(key);
printf("UtilsDeleteValue delete ret = %d\n", ret);
/commonlibrary
├── c_utils # Enhanced basic C/C++ library for developers
├── ets_utils # Enhanced basic JS library for developers
└── utils_lite # Basic tools for liteOS, including C and JS.
```
Features provided by every repositories are listed here:
## How to Develop<a name="section17450172710292"></a>
### Developing a Native Application for the KV Store That Uses the LiteOS Cortex-A Kernel \(Hi3516 or Hi3518\)<a name="section258354119295"></a>
1. Develop the native application for the KV store using **AbilityKit** APIs.
- Write the user program by calling the APIs provided by the KV store and compile the **libLauncher.so** file.
```
// Set the value matching the specified key.
char key[] = "rw.sys.version_100";
char value[] = "Hello kv operation implement!";
int ret = UtilsSetValue(key, value);
printf("UtilsSetValue set ret = %d\n", ret);
// Obtain the value matching the specified key.
char temp[128] = {0};
ret = UtilsGetValue(key, temp, 128);
printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp);
// Delete the value matching the specified key.
ret = UtilsDeleteValue(key);
printf("UtilsDeleteValue delete ret = %d\n", ret);
```
- Edit the **config.json** file as follows:
```
{
"app": {
"bundleName": "com.example.launcher",
"vendor": "example,
"version": {
"code": 1,
"name": "1.0"
}
},
"deviceConfig": {
"default": {
"reqSdk": {
"compatible": "zsdk 1.0.0",
"target": "zsdk 1.0.1"
},
"keepAlive": false
},
"smartCamera": {
"reqSdk": {
"compatible": "zsdk 1.0.0",
"target": "zsdk 1.0.1"
},
"keepAlive": false
}
},
"module": {
"package": "com.example.launcher",
"name": ".MyHarmonyAbilityPackage",
"deviceType": [
"phone", "tv","tablet", "pc","car","smartWatch","sportsWatch","smartCamera"
],
"distro": {
"deliveryWithInstall": true,
"moduleName": "Launcher",
"moduleType": "entry"
},
"abilities": [{
"name": "MainAbility",
"icon": "res/drawable/phone.png",
"label": "test app 1",
"launchType": "standard",
"type": "page"
},
{
"name": "SecondAbility",
"icon": "res/drawable/phone.png",
"label": "test app 2",
"launchType": "standard",
"type": "page"
},
{
"name": "ServiceAbility",
"icon": "res/drawable/phone.png",
"label": "test app 2",
"launchType": "standard",
"type": "service"
}
]
}
}
```
- Generate a HAP file.
- Add resource files in the **res/drawable** directory based on the following directory structure.
![](figure/unnaming.png)
- Compress the **libLauncher.so**, **config.json**, and resource files into a ZIP package and change the file name extension to **.hap**, for example, **Launcher.hap**.
2. Connect the development board and send the command for installing the native KV store application to the board through the serial port.
```
./nfs/dev_tools/bin/bm install -p /nfs/Launcher.hap
```
3. Send the command for running the native KV store application to the board through the serial port.
```
./nfs/dev_tools/bin/aa start -p com.example.launcher -n ServiceAbility
```
### Dumping System Attributes on the Platform That Uses the LiteOS Cortex-M Kernel<a name="section9179161863014"></a>
1. Connect the development board and send the **AT+SYSPARA** command to the board through the serial port.
```
AT+SYSPARA
```
**Figure 1** Output of the system attribute dumping command for the LiteOS Cortex-M kernel<a name="fig15179161863016"></a>
![](figure/output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-m-kernel.png "output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-m-kernel")
**c_utils**
- Enhanced APIs for operations related to files, paths, and strings
- APIs related to the read-write lock, semaphore, timer, thread, and thread pool
- APIs related to the security data container and data serialization
- Error codes for each subsystem
- Safe functions in C
### Dumping System Attributes on the Platform That Uses the LiteOS Cortex-A Kernel<a name="section3179121853017"></a>
**ets_utils**
1. Connect the development board and run the **os\_dump --help** command in the **bin** directory to view the **os\_dump** help information.
- JSAPIs for operation of URI, URL and xml
- JSAPIs for character encoder and decoder
- JSAPIs for operation of process
- Multithreading ability in JS
```
./bin/os_dump --help
```
**utils_lite**
2. Run the **os\_dump -l** command in the **bin** directory to view system modules that support attribute dumping.
- Hardware Abstraction Layer (HAL) APIs for performing operations on standard files
- APIs for internal functions, such as the timer
```
./bin/os_dump -l
```
## Development Guidelines<a name="section1633115419401"></a>
3. Run the **os\_dump syspara** command in the **bin** directory to dump the current system attributes.
[Development Guidelines for c_utils](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/en/c-utils-guide.md)
```
./bin/os_dump syspara
```
**Figure 2** Output of the system attribute dumping command for the LiteOS Cortex-A kernel<a name="fig2179718143018"></a>
![](figure/output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-a-kernel.png "output-of-the-system-attribute-dumping-command-for-the-liteos-cortex-a-kernel")
# Commonlibrary Subsystem FAQ
## c_utils FAQ
See [Development Guidelines for c_utils](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/en/c-utils-guide.md), including FAQs for several scenarios.
\ No newline at end of file
# Utils Overview<a name="EN-US_TOPIC_0000001060172974"></a>
The Utils library stores basic OpenHarmony components that are commonly used by OpenHarmony service subsystems and upper-layer applications.
This library provides the following capabilities on different platforms:
- LiteOS Cortex-M \(Hi3861 platform\): KV store, file operations, IoT peripheral control, and system attribute dumping
- LiteOS Cortex-A \(Hi3516 or Hi3518 platform\): KV store, timer, JavaScript APIs for data and file storage, and system attribute dumping
......@@ -3,7 +3,14 @@
## Introduction<a name="section11660541593"></a>
The **commonlibrary** subsystem provides common enhanced APIs for development in C, C++ and JS.
The **commonlibrary** subsystem stores basic OpenHarmony components which provides common enhanced APIs for development in C, C++ and JS that are commonly used by OpenHarmony service subsystems and upper-layer applications. Including repositories:
```
/commonlibrary
├── c_utils # Enhanced basic C/C++ library for developers
├── ets_utils # Enhanced basic JS library for developers
└── utils_lite # Basic tools for liteOS, including C and JS.
```
Features provided by every repositories are listed here:
**c_utils**
......@@ -24,15 +31,8 @@ The **commonlibrary** subsystem provides common enhanced APIs for development in
- Hardware Abstraction Layer (HAL) APIs for performing operations on standard files
- APIs for internal functions, such as the timer
## Directory Structure<a name="section17271017133915"></a>
```
/commonlibrary
├── c_utils # Enhanced basic C/C++ library for developers
├── ets_utils # Enhanced basic JS library for developers
└── utils_lite # Basic tools for liteOS, including C and JS.
```
## Related Documents<a name="section17271017133915"></a>
[Commonlibrary Development Guidelines](https://gitee.com/openharmony/docs/blob/master/en/device-dev/subsystems/subsys-utils-guide.md)
## Repositories Involved<a name="section1249817110914"></a>
......
# 公共基础库常见问题
## LiteOS-A内核(Hi3516、Hi3518平台)KV存储路径设置错误,导致KV存储运行失败
**现象描述**
LiteOS-A内核(Hi3516、Hi3518平台)直接调用KV存储提供的接口,各参数正常的情况下,编译可执行程序运行失败。
**可能原因**
直接运行编译出的可执行文件,没有将程序基于AbilityKit转换成应用,不能由BMS在应用安装时正确设置应用数据存储路径,导致KV存储运行失败。
**解决办法**
显示调用KV存储的UtilsSetEnv接口,设置数据存储路径。
```
UtilsSetEnv("/storage/com.example.kv");
```
# 公共基础库开发指导
## 接口说明
**表1** 文件操作接口说明
| 接口名 | 描述 |
| -------- | -------- |
| int&nbsp;UtilsFileOpen(const&nbsp;char\*&nbsp;path,&nbsp;int&nbsp;oflag,&nbsp;int&nbsp;mode) | 打开或创建文件 |
| int&nbsp;UtilsFileClose(int&nbsp;fd) | 关闭文件 |
| int&nbsp;UtilsFileRead(int&nbsp;fd,&nbsp;char&nbsp;\*buf,&nbsp;unsigned&nbsp;int&nbsp;len) | 读取特定长度的文件数据 |
| int&nbsp;UtilsFileWrite(int&nbsp;fd,&nbsp;const&nbsp;char&nbsp;\*buf,&nbsp;unsigned&nbsp;int&nbsp;len) | 向文件写入特定大小的数据 |
| int&nbsp;UtilsFileDelete(const&nbsp;char&nbsp;\*path) | 删除指定文件 |
| int&nbsp;UtilsFileStat(const&nbsp;char&nbsp;\*path,&nbsp;unsigned&nbsp;int&nbsp;\*fileSize) | 获取文件大小 |
| int&nbsp;UtilsFileSeek(int&nbsp;fd,&nbsp;int&nbsp;offset,&nbsp;unsigned&nbsp;int&nbsp;whence) | 重新定位文件读/写偏移量 |
| int&nbsp;UtilsFileCopy(const&nbsp;char\*&nbsp;src,&nbsp;const&nbsp;char\*&nbsp;dest) | 将源文件复制一份并存储到目标文件 |
| int&nbsp;UtilsFileMove(const&nbsp;char\*&nbsp;src,&nbsp;const&nbsp;char\*&nbsp;dest) | 将源文件移动到指定目标文件 |
文件操作使用示例:
```
// open && write
char fileName[] = "testfile";
static const char def[] = "utils_file_operation implement.";
int fd = UtilsFileOpen(fileName, O_RDWR_FS | O_CREAT_FS | O_TRUNC_FS, 0);
printf("file handle = %d\n", fd);
int ret = UtilsFileWrite(fd, def, strlen(def));
printf("write ret = %d\n", ret);
// seek
ret = UtilsFileSeek(fd, 5, SEEK_SET_FS);
printf("lseek ret = %d\n", ret);
// read && close
char buf[64] = {0};
int readLen = UtilsFileRead(fd, buf, 64);
ret = UtilsFileClose(fd);
printf("read len = %d : buf = %s\n", readLen, buf);
// stat
int fileLen = 0;
ret = UtilsFileStat(fileName, &fileLen);
printf("file size = %d\n", fileLen);
// delete
ret = UtilsFileDelete(fileName);
printf("delete ret = %d\n", ret);
# 公共基础类库开发指导
## 概述
公共基础类库存放OpenHarmony通用的基础组件。这些基础组件包括一些常用的C、C++、JS开发增强API,可被OpenHarmony各业务子系统及上层应用所使用。公共基础类库子系统包含如下代码仓库:
```
**表2** KV存储接口说明
| 接口名 | 描述 |
| -------- | -------- |
| int&nbsp;UtilsGetValue(const&nbsp;char\*&nbsp;key,&nbsp;char\*&nbsp;value,&nbsp;unsigned&nbsp;int&nbsp;len) | 提供给上层应用根据key获取对应数据项 |
| int&nbsp;UtilsSetValue(const&nbsp;char\*&nbsp;key,&nbsp;const&nbsp;char\*&nbsp;value) | 提供给上层应用用于存储/更新key对应数据项 |
| int&nbsp;UtilsDeleteValue(const&nbsp;char\*&nbsp;key) | 提供给上层应用删除key对应数据项 |
KV存储使用示例:
```
// set
char key[] = "rw.sys.version_100";
char value[] = "Hello kv operation implement!";
int ret = UtilsSetValue(key, value);
printf("UtilsSetValue set ret = %d\n", ret);
// get
char temp[128] = {0};
ret = UtilsGetValue(key, temp, 128);
printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp);
// delete
ret = UtilsDeleteValue(key);
printf("UtilsDeleteValue delete ret = %d\n", ret);
/commonlibrary
├── c_utils # c/c++标准库之外方便开发者开发的基础工具库
├── ets_utils # js标准库之外的与语言强相关的基础库
└── utils_lite # lite上使用的工具函数,涉及c和js语言
```
各仓库提供的功能列表如下:
**c_utils**
- 文件、路径、字符串相关操作的能力增强接口;
- 读写锁、信号量、定时器、线程增强及线程池等接口;
- 安全数据容器、数据序列化等接口;
- 各子系统的错误码相关定义;
## 开发步骤
### LiteOS-A内核(Hi3516、Hi3518平台)KV存储的native应用开发:
1. 基于AbilityKit开发KV存储的native应用。
- 基于KV存储提供的接口编写用户程序,并编译出so(libLauncher.so)文件。
```
// set
char key[] = "rw.sys.version_100";
char value[] = "Hello kv operation implement!";
int ret = UtilsSetValue(key, value);
printf("UtilsSetValue set ret = %d\n", ret);
// get
char temp[128] = {0};
ret = UtilsGetValue(key, temp, 128);
printf("UtilsGetValue get ret = %d, temp = %s\n", ret, temp);
// delete
ret = UtilsDeleteValue(key);
printf("UtilsDeleteValue delete ret = %d\n", ret);
```
- 编写config.json文件,内容如下:
```
{
"app": {
"bundleName": "com.example.launcher",
"vendor": "example",
"version": {
"code": 1,
"name": "1.0"
}
},
"deviceConfig": {
"default": {
"reqSdk": {
"compatible": "zsdk 1.0.0",
"target": "zsdk 1.0.1"
},
"keepAlive": false
},
"smartCamera": {
"reqSdk": {
"compatible": "zsdk 1.0.0",
"target": "zsdk 1.0.1"
},
"keepAlive": false
}
},
"module": {
"package": "com.example.launcher",
"name": ".MyOpenHarmonyAbilityPackage",
"deviceType": [
"phone", "tv","tablet", "pc","car","smartWatch","sportsWatch","smartCamera"
],
"distro": {
"deliveryWithInstall": true,
"moduleName": "Launcher",
"moduleType": "entry"
},
"abilities": [{
"name": "MainAbility",
"icon": "res/drawable/phone.png",
"label": "test app 1",
"launchType": "standard",
"type": "page"
},
{
"name": "SecondAbility",
"icon": "res/drawable/phone.png",
"label": "test app 2",
"launchType": "standard",
"type": "page"
},
{
"name": "ServiceAbility",
"icon": "res/drawable/phone.png",
"label": "test app 2",
"launchType": "standard",
"type": "service"
}
]
}
}
```
- 生成hap包。
- 按照如下目录结构存放文件,res/drawable下面放置资源文件:
**图1** 资源文件路径图
![zh-cn_image_0000001154153558](figures/zh-cn_image_0000001154153558.png)
- 将上述文件打包生成zip包,修改后缀为.hap,例如Launcher.hap
2. 连接单板,通过串口向单板发送安装KV存储native应用的命令。
```
./nfs/dev_tools/bin/bm install -p /nfs/Launcher.hap
```
3. 通过串口向单板发送运行KV存储native应用的命令。
```
./nfs/dev_tools/bin/aa start -p com.example.launcher -n ServiceAbility
```
### Dump系统属性在LiteOS-M内核平台使用:
1. 连接单板,通过串口向单板发送AT+SYSPARA命令。
```
AT+SYSPARA
```
**图2** LiteOS-M平台dump系统属性输出
![zh-cn_image_0000001115123966](figures/zh-cn_image_0000001115123966.png)
### Dump系统属性在LiteOS-A内核平台使用:
**ets_utils**
1. 连接单板,运行bin路径下的os_dump加参数--help,查看os_dump使用指导。
```
./bin/os_dump --help
```
- JS中URI、URL、xml相关操作接口;
- JS中字符编解码接口;
- JS中进程相关操作接口;
- JS中多线程能力;
2. os_dump加参数-l,查看当前系统有哪些模块支持获取属性。
```
./bin/os_dump -l
```
**utils_lite**
3. os_dump加参数syspara,查看当前系统属性。
```
./bin/os_dump syspara
```
- 标准文件相关操作HAL接口;
- 其它一些内部功能,如定时器等。
**图3** LiteOS-A平台dump系统属性输出
## 各仓库开发指导
[C++公共基础库(c_utils)开发指导](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide.md)
![zh-cn_image_0000001197369959](figures/zh-cn_image_0000001197369959.png)
# 公共基础类库常见问题
## c_utils常见问题
具体各应用场景常见问题,参见[C++公共基础库(c_utils)开发指导](https://gitee.com/openharmony/commonlibrary_c_utils/blob/master/docs/zh-cn/c-utils-guide.md)
\ No newline at end of file
# 公共基础库概述
公共基础库存放OpenHarmony通用的基础组件。这些基础组件可被OpenHarmony各业务子系统及上层应用所使用。
公共基础库在不同平台上提供的能力:
LiteOS-M内核(Hi3861平台):KV存储、文件操作、IoT外设控制、Dump系统属性。
LiteOS-A内核(Hi3516、Hi3518平台):KV存储、定时器、数据和文件存储的JS API、Dump系统属性。
# 公共基础库<a name="ZH-CN_TOPIC_0000001092539399"></a>
- [简介](#section11660541593)
- [目录](#section17271017133915)
- [概述](#section11660541593)
- [相关文档](#section17271017133915)
- [相关仓](#section1249817110914)
## 简介<a name="section11660541593"></a>
## 概述<a name="section11660541593"></a>
公共基础类库提供了一些常用的C、C++、JS开发增强API。包括如下部分:
公共基础类库存放OpenHarmony通用的基础组件。这些基础组件包括一些常用的C、C++、JS开发增强API,可被OpenHarmony各业务子系统及上层应用所使用。公共基础类库子系统包含如下代码仓库:
```
/commonlibrary
├── c_utils # c/c++标准库之外方便开发者开发的基础工具库
├── ets_utils # js标准库之外的与语言强相关的基础库
└── utils_lite # lite上使用的工具函数,涉及c和js语言
```
各仓库提供的功能列表如下:
**c_utils**
......@@ -27,14 +34,8 @@
- 标准文件相关操作HAL接口;
- 其它一些内部功能,如定时器等。
## 目录<a name="section17271017133915"></a>
```
/commonlibrary
├── c_utils # c/c++标准库之外方便开发者开发的基础工具库
├── ets_utils # js标准库之外的与语言强相关的基础库
└── utils_lite # lite上使用的工具函数,涉及c和js语言
```
## 相关文档<a name="section17271017133915"></a>
[公共基础类库开发指导](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-utils-guide.md)
## 相关仓<a name="section1249817110914"></a>
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册