修改文档

Signed-off-by: huruitao <huruitao@kaihong.com>
This commit is contained in:
huruitao 2024-09-13 17:59:36 +08:00
parent 04a855fca8
commit 9fcd8beaf1
17 changed files with 210 additions and 367 deletions

Binary file not shown.

After

Width:  |  Height:  |  Size: 34 KiB

View File

@ -1,14 +1,14 @@
## Develop guide
## Develop Guide
### Service代码生成工具使用场景
### service代码生成工具使用场景
当开发人员为OpenHarmony系统框架开发某些功能时有时需要将这个功能包装成一个独立的服务进程运行在系统中为了其它应用进程能够调用此服务开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。 Service代码生成工具能够帮助用户生成框架代码提升开发效率。用户只需提供一个定义远程方法的.h头文件工具会自动生成整个Service框架的代码包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。用户可基于框架代码专注于业务功能的编写。
当开发人员为OpenHarmony系统框架开发某些功能时有时需要将这个功能包装成一个独立的服务进程运行在系统中为了其它应用进程能够调用此服务开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。 Service代码生成工具能够帮助用户生成框架代码提升开发效率。用户只需提供一个定义远程方法的.h头文件工具会自动生成整个Service框架的代码包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。用户可基于框架代码专注于业务功能的编写。
![image](../figures/service_frame_structure.png)
![image](../figures/service_file.png)
---
### Service工具代码框架说明
### service工具代码框架说明
~~~
napi_generator\src\cli\h2sa
@ -43,15 +43,15 @@ h2sa
main.js为脚本入口其中使用stdio.getopt获取参数其中,参数详情如下:
-f定义远程服务的.h文件
-f定义远程服务的.h文件
-l, 日志级别0-3默认为1
-l, 日志级别0-3默认为1
-o, 生成框架代码输入到指定路径下;
-o, 生成框架代码输入到指定路径下;
-s, 指定serviceID。 -
-s, 指定serviceID。 -
-v, 指定版本3.2和4.1默认版本为3.2
-v, 指定版本3.2和4.1默认版本为3.2
~~~
let ops = stdio.getopt({
@ -67,7 +67,7 @@ let ops = stdio.getopt({
#### 适配新版本
若当前工具不能满足需要,用户可对工具进行二次开发。例如当前工具适配的源码版本是4.1若用户需要适配其它版本,用户需修改以下文件进行适配:
用户可对工具进行二次开发。例如当前工具适配的源码版本是4.1需要适配其它版本时,可修改以下文件进行适配:
**9月份会进行代码去重整改预估适配方式如下整改后如有出入会进行修改**
@ -77,12 +77,11 @@ let ops = stdio.getopt({
3.在generate.js中在doGenerate方法、genFilesByTemplate方法、genFileNames方法中修改相应代码当rootInfo.version为v5_0时替换对应的BUILD.gn, bundle.json模板路径。
适配新版本需要增加其它配置可在templete目录下增加配置模板并增加配置文件模板的路径在generate.js中生成配置文件。
4.适配新版本需要增加其它配置可在templete目录下增加配置模板并增加配置文件模板的路径在generate.js中生成配置文件。
#### roadMap
| 时间点 | 预期任务 | 验收标准 | 完成情况 |
| :----- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- |
| 9月份 | 1代码去重方案提供不同版本模板proxy-stub框架hidumper框架hitrace<br />2适配5.0release版本增加代码中hidump、hitrace等日志跟踪定位工具的使用 | 1设计文档<br />2适配5.0时,可以编译出对应版本的工具,且编译验证成功 | |
| 10月份 | 增加testapp调用 sa接口包括死亡监听 | testapp | |
#### RoadMap
| 时间点 | 预期任务 | 验收标准 | 完成情况 |
| :----- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------- |
| 9月份 | 1代码去重方案提供不同版本模板proxy-stub框架hidumper框架hitrace<br />2适配5.0release版本增加代码中hidump、hitrace等日志跟踪定位工具的使用 | 1设计文档<br />2适配5.0时,可以编译出对应版本的工具,且编译验证成功 | 预计2024.9.24 |
| 10月份 | 增加testapp调用 sa接口包括死亡监听 | 杀掉服务后,有信息 | |

View File

@ -1,232 +0,0 @@
### h2sa工具
## 简介
h2sa工具即SERVICE框架生成工具当开发者为OpenHarmony系统框架开发某些功能时有时需要将这个功能包装成一个独立的服务进程运行在系统中为了其它应用进程能够调用此服务开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。实现Service远程调用接口需要开发人员熟悉IPC通信框架了解proxy/stub的继承与实现方式掌握C++类型转为MessageParcel数据包的各种API方法有一定的学习成本。而Service代码生成工具能够帮助使用者生成框架代码提升开发效率。用户只需提供一个定义远程方法的.h头文件工具会自动生成整个Service框架的代码包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。
## 约束
系统建议Ubuntu 20.04或者Windows 10
依赖版本VS Code 1.62.0
## 使用方法
#### 命令行
1. 安装python库 CppHeaderParser
~~~
pip install CppHeaderParser
~~~
2. 安装typescript在napi_generator/src/cli/h2sa/src/src目录下执行命令
~~~
npm i typescript
~~~
3. 安装stdio在napi_generator/src/cli/h2sa/src目录下执行命令
~~~
npm i stdio
~~~
4. 将待转换的文件test.h文件拷贝到napi_generator/src/cli/h2sa/src/src/gen目录下
~~~cpp
napi_generator/src/cli/h2sa/examples/test.h
#ifndef TEST_H
#define TEST_H
namespace OHOS {
namespace Example {
/**
* @brief service服务提供IPC调用接口
* @ServiceClass
*/
class test {
public:
int testFunc(int v1, int v2, bool v3);
};
} // namespace Example
} // namespace OHOS
#endif // TEST_H
~~~
注意:.h文件中待生成的主class必须加注释@brief service服务提供IPC调用接口 ,如下所示:
```cpp
/**
* @brief service服务提供IPC调用接口
* @ServiceClass
*/
```
5. 在napi_generator/src/cli/h2sa/src/src/gen目录下执行命令生成service框架代码
~~~
node main.js -f test.h
~~~
其中,参数详情如下: -f定义远程服务的.h文件 -l, 日志级别0-3默认为1 -o,生成框架代码输入到指定路径下; -s,指定serviceID。 -v,指定版本3.2和4.1默认版本为3.2
#### 生成物
1. 输出testservice文件夹其中的文件如下所示
![](../figures/h2sa_outRes.png)
~~~
├── BUILD.gn # 整个服务的编译文件包含2个内容:1)服务端程序动态库编译 2)客户端可执行程序编译
├── bundle.json # 将服务包装成一个OpenHarmoney子系统组件提供相关信息
├── etc # 服务启动配置目录,如果服务不需要开机自动启动,可以删除此目录。
│ ├── BUILD.gn
│ └── test_service.cfg # 服务自启动配置文件,编译烧录后会在/ect/init/下生成xxx_service.cfg启动文件
├── include
│ ├── test_service.h # 服务端头文件
│ ├── test_service_proxy.h # proxy 客户端头文件为开发人员封装remote请求发送的处理
│ └── test_service_stub.h # stub 服务端头文件为开发人员封装remote请求接收的处理
├── interface
│ └── i_test_service.h # 由用户提供的.h文件生成的remote接口文件stub和proxy都基于此文件实现接口。
├── sa_profile
│ ├── 9000.json # 服务配置文件
│ └── BUILD.gn
└── src
├── i_test_service.cpp # 接口实现文件
├── test_client.cpp # 客户端程序
├── test_service.cpp # 服务端程序
├── test_service_proxy.cpp # 客户端代理实现
└── test_service_stub.cpp # 服务端 stub 实现
~~~
#### 生成物的应用和验证
1. 编译步骤生成的testservice文件夹放在对应版本的源码根目录下
2. 修改系统公共文件
##### 基础配置
1. 服务配置
在foundation/systemabilitymgr/samgr/interfaces/innerkits/samgr_proxy/include/
system_ability_definition.h增加以下一行
```
TEST_SERVICE_ID = 9016,
```
其中TEST_SERVICE_ID宏值与用户定义的serviceID一致。
2. 子系统配置
在build/subsystem_config.json中增加以下内容。
```
"testservice": {
"path":"testservice",
"name": "testservice"
}
```
3. 产品配置如rk3568
在vendor/kaihong/rk3568/config.json中增加以下内容
```
{
"subsystem": "testservice",
"components": [
{
"component": "testservice_part",
"features": []
}
]
}
```
4. 权限配置
在相应的产品目录的vendor/kaihong/rk3568/security_config/high_privilege_process_list.json中增加以下内容
```
{
"name": "testservice",
"uid": "system",
"gid": ["root", "system"]
}
```
##### selinux权限配置
上述基础配置时关闭了selinux 权限配置用户新增服务时需根据自身需求配置selinux 权限 。
若要配置selinux权限首先应将vendor/hihope/rk3568/config.json中"build_selinux"属性改为true然后修改以下文件
1. testservice/etc/sample_service.cfg
```
"secon" : "u:r:testservice:s0"
```
2. base/security/selinux_adapter/sepolicy/base/public/service_contexts
```
9016 u:object_r:sa_testservice:s0
```
3. base/security/selinux_adapter/sepolicy/base/public/service.te
```
type sa_testservice, sa_service_attr;
```
4. base/security/selinux_adapter/sepolicy/ohos_policy/startup/init/system/init.te
```
allow init testservice:process { getattr rlimitinh siginh transition };
```
5. base/security/selinux/sepolicy/base/public/type.te
```
type testservice, sadomain, domain;
```
6. /base/security/selinux/sepolicy/base/te目录下增加新service的te文件新增文件名即为服务名例如testservice.te
```
allow testservice init_param:file { map open read };
allow testservice sa_testservice:samgr_class { add get };
```
3. 编码完成后,执行镜像编译命令
~~~
./build.sh --product-name 产品名
若编译Hi3516DV300开发板则执行
./build.sh --product-name Hi3516DV300
若编译rk3568开发板则执行
./build.sh --product-name rk3568
~~~
4. 烧录镜像
5. 运行验证
> 验证一: shell登录开发板。 查看服务端进程是否已正常启动
>
> ~~~
> ps -ef | grep testservice
> system 288 1 0 00:02:13 ? 00:00:00 testservice_sa --- 服务进程已正常运行
> ~~~
>
> 验证二:运行客户端
>
> ~~~
> /system/bin/testclient
> ~~~

View File

@ -0,0 +1,193 @@
### Usage Guide
## 简介
h2sa工具即SERVICE框架生成工具当开发者为OpenHarmony系统框架开发某些功能时有时需要将这个功能包装成一个独立的服务进程运行在系统中为了其它应用进程能够调用此服务开发人员需要基于系统IPC通信框架编写一套远程接口调用实现。实现Service远程调用接口需要开发人员熟悉IPC通信框架了解proxy/stub的继承与实现方式掌握C++类型转为MessageParcel数据包的各种API方法有一定的学习成本。而Service代码生成工具能够帮助使用者生成框架代码提升开发效率。用户只需提供一个定义远程方法的.h头文件工具会自动生成整个Service框架的代码包含Ability注册、proxy/stub类实现、MessageParcel数据包构造、Service子系统编译及开机自启动相关配置文件。
## 约束
系统建议Ubuntu 20.04或者Windows 10
依赖版本VS Code 1.62.0
## 使用方法
#### 命令行
1. 安装python库 CppHeaderParser
~~~
pip install CppHeaderParser
~~~
2. 安装typescript在napi_generator/src/cli/h2sa/src目录下执行命令
~~~
npm i typescript
~~~
3. 安装stdio在napi_generator/src/cli/h2sa目录下执行命令
~~~
npm i stdio
~~~
4. 在napi_generator/src/cli/h2sa/src/gen目录下执行命令生成service框架代码
~~~
node main.js -f test.h
~~~
其中,参数详情如下:
-f定义远程服务的.h文件
-l可选参数日志级别0-3默认为1
-o可选参数生成框架代码输入到指定路径下
-s可选参数指定serviceID。
-v可选参数指定版本3.2和4.1默认版本为3.2
#### 生成物
1. 输出testservice文件夹其中的文件如下所示
![](../figures/h2sa_outRes.png)
~~~
├── BUILD.gn # 整个服务的编译文件包含2个内容:1)服务端程序动态库编译 2)客户端可执行程序编译
├── bundle.json # 将服务包装成一个OpenHarmoney子系统组件提供相关信息
├── etc # 服务启动配置目录,如果服务不需要开机自动启动,可以删除此目录。
│ ├── BUILD.gn
│ └── test_service.cfg # 服务自启动配置文件,编译烧录后会在/ect/init/下生成xxx_service.cfg启动文件
├── include
│ ├── test_service.h # 服务端头文件
│ ├── test_service_proxy.h # proxy 客户端头文件为开发人员封装remote请求发送的处理
│ └── test_service_stub.h # stub 服务端头文件为开发人员封装remote请求接收的处理
├── interface
│ └── i_test_service.h # 由用户提供的.h文件生成的remote接口文件stub和proxy都基于此文件实现接口。
├── sa_profile
│ ├── 9000.json # 服务配置文件
│ └── BUILD.gn
└── src
├── i_test_service.cpp # 接口实现文件
├── test_client.cpp # 客户端程序
├── test_service.cpp # 服务端程序
├── test_service_proxy.cpp # 客户端代理实现
└── test_service_stub.cpp # 服务端 stub 实现
~~~
#### 应用和验证
1. 将生成的testservice文件夹放在对应版本的源码根目录下
2. 修改服务配置文件
在foundation/systemabilitymgr/samgr/interfaces/innerkits/samgr_proxy/include/system_ability_definition.h增加以下一行
```
TEST_SERVICE_ID = {serviceID}, //保证ID没有重复即可例如9016
```
3. 修改子系统配置文件
在build/subsystem_config.json中增加以下内容。
```
"testservice": {
"path":"testservice",
"name": "testservice"
}
```
4. 修改产品配置如rk3568
在vendor/kaihong/rk3568/config.json中增加以下内容
```
{
"subsystem": "testservice",
"components": [
{
"component": "testservice_part",
"features": []
}
]
}
```
5. 修改权限配置
在相应的产品目录的vendor/kaihong/rk3568/security_config/high_privilege_process_list.json中增加以下内容
```
{
"name": "testservice",
"uid": "system",
"gid": ["root", "system"]
}
```
6. selinux权限配置
vendor/hihope/rk3568/config.json中"build_selinux"属性若为true 即要配置selinux权限应修改以下文件若为false无需修改
> 1. testservice/etc/sample_service.cfg
>
> ```
> "secon" : "u:r:testservice:s0"
> ```
>
> 2. base/security/selinux_adapter/sepolicy/base/public/service_contexts
>
> ```
> 9016 u:object_r:sa_testservice:s0
> ```
>
> 3. base/security/selinux_adapter/sepolicy/base/public/service.te
>
> ```
> type sa_testservice, sa_service_attr;
> ```
>
> 4. base/security/selinux_adapter/sepolicy/ohos_policy/startup/init/system/init.te
>
> ```
> allow init testservice:process { getattr rlimitinh siginh transition };
> ```
>
> 5. base/security/selinux/sepolicy/base/public/type.te
>
> ```
> type testservice, sadomain, domain;
> ```
>
> 6. /base/security/selinux/sepolicy/base/te目录下增加新service的te文件新增文件名即为服务名例如testservice.te
>
> ```
> allow testservice init_param:file { map open read };
> allow testservice sa_testservice:samgr_class { add get };
> ```
7. 编码完成后,执行镜像编译命令
~~~
./build.sh --product-name 产品名
若编译rk3568开发板则执行
./build.sh --product-name rk3568
~~~
8. 烧录镜像
9. 运行验证
>验证一: shell登录开发板。 查看服务端进程是否已正常启动
>
>~~~
>ps -ef | grep testservice
>system 288 1 0 00:02:13 ? 00:00:00 testservice_sa --- 服务进程已正常运行
>~~~
>
>验证二:运行客户端
>
>~~~
>/system/bin/testclient
>~~~

View File

@ -1,117 +0,0 @@
/*
* Copyright (c) 2022 Shenzhen Kaihong Digital Industry Development Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef EXAM_H
#define EXAM_H
#include <mutex>
#include <thread>
#include <unordered_map>
#include <string>
using std::string;
namespace OHOS {
namespace Example {
class Basic {
public:
std::string basicName;
int getBasicId()
{
return this->basicId;
}
void setBasicId (int id)
{
this->basicId = id;
}
private:
int basicId;
};
class Human : public Basic {
public:
bool getOpFlag()
{
return this->opFlag;
};
void setOpFlag (bool flag)
{
this->opFlag = flag;
};
std::string getOpDesc()
{
return this->opDesc;
};
void setOpDesc(std::string desc)
{
this->opDesc = desc;
};
int getOpSeqId()
{
return this->opSeqId;
};
void setOpSeqId(int id)
{
opSeqId = id;
};
std::string opName;
int age = 0;
private:
bool opFlag;
std::string opDesc;
int opSeqId;
}
struct Book {
int getCc()
{
return this->cc;
};
void setCc(int cc)
{
this->cc = cc;
};
Basic getBasicObj()
{
return this->basicObj;
};
void setBasicObj(Basic obj)
{
this->basicObj = obj;
};
public:
int aa;
bool bb;
Basic direcObj;
private:
int cc;
Basic basicObj;
}
/**
* @brief service服务IPC调用接口
* @ServiceClass
*/
class Exam2 {
public:
Book getBook(Basic& basic);
int fun1 (Book v1);
int fun2 (Basic& basic, Human& human);
};
} // namespace Example
} // namespace OHOS
#endif // EXAM_H