mirror of
https://gitee.com/openharmony/interface_sdk_c
synced 2024-11-22 22:29:57 +00:00
Fix some duplicate content in docs.
Signed-off-by: hhj <huanghuijin@huawei.com>
This commit is contained in:
hhj
parent
4b33bd822f
commit
6f909d581d
@ -2,7 +2,7 @@ Public Repository for API Declaration Files
|
||||
|
||||
## Overview
|
||||
|
||||
This repository is used to store .h declaration files of C APIs.
|
||||
This repository is used to store .h declaration files of C APIs. The OpenHarmony C API is collection of system C interfaces that the operating system provided for applications using the C/C++ language library.It is the contract between the system and the applications; These interfaces need to be sufficiently stable. Interfaces are currently organized into various directories according to the function, and the directories organized as follows.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
@ -45,3 +45,5 @@ This repository is used to store .h declaration files of C APIs.
|
||||
## Repositories Involved
|
||||
|
||||
[interface_sdk_c](https://gitee.com/openharmony-sig/interface_sdk_c/)
|
||||
[C API编码规范](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/capi_naming.md): A guide that describes how to design and publish an interface.
|
||||
[C API构建指南](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/howto_add.md)：A guide that describes how to add a build target for the C API in the build.gn
|
||||
@ -2,7 +2,8 @@
|
||||
|
||||
## 简介
|
||||
|
||||
[C API](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/user_guide.md)公共仓，用来提交 C API 声明头文件。
|
||||
[C API](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/user_guide.md)公共仓，用来提交 C API 声明头文件。OpenHarmony C API接口是操作系统提供给应用使用C/C++语言生态库的系统C接口，
|
||||
是系统与应用的C能力契约；这些接口需要保持足够的稳定性。C API接口当前按照功能组织放到各个领域目录下，具体目录如下。
|
||||
|
||||
## 目录
|
||||
|
||||
@ -47,5 +48,5 @@
|
||||
## 相关仓
|
||||
|
||||
[interface_sdk_c](https://gitee.com/openharmony-sig/interface_sdk_c/)
|
||||
[C API编码规范](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/capi_naming.md)
|
||||
[C API构建指南](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/howto_add.md)
|
||||
[C API编码规范](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/capi_naming.md): 描述了OpenHarmony C API的设计规范，指导开发者如何设计发布一个接口。
|
||||
[C API构建指南](https://gitee.com/openharmony-sig/interface_sdk_c/blob/master/docs/howto_add.md)：描述了如何在build.gn中添加C API的构建目标。
|
||||
|
||||
@ -19,12 +19,12 @@ OpenHarmony提供了一些C语言系统接口供三方应用开发者使用，
|
||||
|
||||
|
||||
## 2 C API接口命名规则
|
||||
在CAPI中出现的接口，分为两类：
|
||||
在C API中出现的接口，分为两类：
|
||||
1. 业界标准接口或者是生态约定俗成的接口（如libc，opengles）
|
||||
2. OpenHarmony自研接口
|
||||
|
||||
### 2.1 业界标准接口命名规则
|
||||
#### 2.1.1 【规则】已有业界标准的CAPI接口命名规则按照业界标准来命名。
|
||||
#### 2.1.1 【规则】已有业界标准的C API接口命名规则按照业界标准来命名。
|
||||
|
||||
__举例__：
|
||||
1. libc/libc++采用的是unix_like的命名规则；
|
||||
@ -33,7 +33,7 @@ __举例__：
|
||||
__说明__：针对第三方标准中，根据平台要求扩展的接口，也按照此三方库的推荐命名方式。
|
||||
|
||||
### 2.2 自研接口命名规则
|
||||
#### 2.2.1 【规则】CAPI接口函数标识符命名规则，采用OH_<模块前缀>_<方法名>的方式，命名需要精准，模块前缀采用大驼峰，方法名采用大驼峰规则。
|
||||
#### 2.2.1 【规则】C API接口函数标识符命名规则，采用OH_<模块前缀>_<方法名>的方式，命名需要精准，模块前缀采用大驼峰，方法名采用大驼峰规则。
|
||||
|
||||
__说明__：采用C语言接口，符号是全局课件，容易与别的模块符号产生符号冲突，采用模块前缀进行作用域区分。
|
||||
|
||||
@ -62,7 +62,7 @@ __说明__：如果此头文件在sysroot的include目录下的路径中已经
|
||||
__说明__：子系统下的目录组织形式可以采用模块名目录加头文件的形式，或者采用模块名_文件名.h方式；不建议新建太深的目录结构，开发者代码在引用头文件的时候，需要引用长串路径，不友好。
|
||||
```
|
||||
|--include
|
||||
| |--逻辑名(需要上APP SIG评审)
|
||||
| |--领域组名(需要上API SIG评审)
|
||||
| | |--xxx
|
||||
| | | |-- aaa.h
|
||||
| | | |-- bbb.h
|
||||
@ -76,7 +76,7 @@ __说明__：子系统下的目录组织形式可以采用模块名目录加头
|
||||
|
||||
### 2.4 库文件命名规则
|
||||
#### 2.4.1 【建议】库文件放置在sysroot/usr/lib根目录，不用建子目录；文件名采用unix_like的命名规则，不用z.so结尾。
|
||||
__说明__：是否需要给C API接口独立创建一个so库，这个没有强制要求；如果CAPI接口是重新封装，建议独立一个库，因为C API接口实现库在镜像中必须放置到/system/{lib|lib64}/ndk目录，方便接口管控。
|
||||
__说明__：是否需要给C API接口独立创建一个so库，这个没有强制要求；如果C API接口是重新封装，建议独立一个库，因为C API接口实现库在镜像中必须放置到/system/{lib|lib64}/ndk目录，方便接口管控。
|
||||
__说明__：命名采用libxxx.so的命名方式，库名字最好与模块名字相同，如果包含多个模块，建议采用业界常用的名字；如果名字是常用单词，建议前面加oh前缀，如libohxxx.so，避免名字冲突。
|
||||
|
||||
|
||||
|
||||
@ -93,7 +93,7 @@ json描述文件的例子如下：
|
||||
]
|
||||
```
|
||||
|
||||
### ohos_ndk_headers(目标名）
|
||||
### ohos_ndk_headers(目标名)
|
||||
输入参数：
|
||||
**sources** ：想拷贝的文件或目录列表
|
||||
**dest_dir** ：目标目录，默认值为$ndk_headers_out_dir，$ndk_headers_out_dir为$root_out_dir/sdk-native/sysroot/usr/include。
|
||||
@ -115,6 +115,6 @@ sources = [
|
||||
|
||||
|
||||
## 文档
|
||||
CAPI的文档生成在docs目录，需要安装doxygen工具，在ubuntu上使用`sudo apt-get install doxygen`即可安装。如果编译机上没有安装doxygen，文档将无法生成。
|
||||
C API的文档生成在docs目录，需要安装doxygen工具，在ubuntu上使用`sudo apt-get install doxygen`即可安装。如果编译机上没有安装doxygen，文档将无法生成。
|
||||
|
||||
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
# C API用户指导
|
||||
|
||||
## 基础知识
|
||||
了解C API基础知识，请参考《[Native API入门](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/native-api-intro.md)》
|
||||
了解C API基础知识，请参考《[Native API入门](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/native-api-intro.md)》。
|
||||
|
||||
|
||||
## 接口开放策略
|
||||
|
||||
### 不开放原则
|
||||
|
||||
1. 应用生态提供的核心特性只开放ArkTS API，不开发CAPI。
|
||||
2. 不开发ArkUI的CAPI。
|
||||
3. 不开发硬件底层接口（HDI）CAPI。
|
||||
4. 不开放命令行接口CAPI。
|
||||
1. 应用生态提供的核心特性只开放ArkTS API，不开发C API。
|
||||
2. 不开发ArkUI的C API。
|
||||
3. 不开发硬件底层接口（HDI）C API。
|
||||
4. 不开放命令行接口C API。
|
||||
### 开放原则
|
||||
5. 高性能、密集计算业务场景主动开放CAPI。例如：需要高性能的IO、CPU密集计算等场景；音视频编解码、图形计算等场景。
|
||||
6. 应用生态业务依赖的场景，主动开放高阶CAPI。例如：对标竞品，媒体高阶CAPI。
|
||||
7. 应用生态框架以来的场景，按需开放CAPI。例如：按需开放Unity/electron/CFE框架中依赖的CAPI。
|
||||
8. 行业约定或者标准要求的场景按需开放CAPI。此类CAPI独立发布，不放入OpenHarmony CAPI中。例如：金融或者安全行业高密加密算法等，按需独立发布。
|
||||
5. 高性能、密集计算业务场景主动开放C API，例如：需要高性能的IO、CPU密集计算等场景；音视频编解码、图形计算等场景。
|
||||
6. 应用生态业务依赖的场景，主动开放高阶C API。例如：对标竞品，媒体高阶C API。
|
||||
7. 应用生态框架以来的场景，按需开放C API。例如：按需开放Unity/electron/CFE框架中依赖的C API。
|
||||
8. 行业约定或者标准要求的场景按需开放C API。此类C API独立发布，不放入OpenHarmony C API中。例如：金融或者安全行业高密加密算法等，按需独立发布。
|
||||
|
||||
### 前向兼容性原则
|
||||
9. CAPI的前向兼容性原则与ArkTS API策略保持一致。CI流程中会使用自动化工具进行看护。
|
||||
9. C API的前向兼容性原则与ArkTS API策略保持一致。CI流程中会使用自动化工具进行看护。
|
||||
|
||||
|
||||
## CAPI接口设计规范
|
||||
## C API接口设计规范
|
||||
本规范是在《[OpenHarmony API治理章程](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-governance.md)》《[OpenHarmony API社区规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-quality.md)》的基础上，对C API设计进行的一些补充。在C API接口设计上同时满足此三份规范。
|
||||
|
||||
### 设计规则
|
||||
* 【规则】接口新增或者变更需要到APP_SIG会议进行评审，通过后才能修改。
|
||||
* 【规则】接口要考虑OpenHarmony生态的一致性，保证在生态版本设备上的兼容，实现代码需同步发布。
|
||||
* 【规则】CAPI相关的接口文件，包含接口列表文件ndk.json，头文件，编译构建脚本三部分；这些内容必须放置在interface_sdk_c仓中，不能对外产生依赖。三方库接口暴露规则同自研仓，接口是处理过的接口文件，不是三方库原生文件。
|
||||
* 【规则】接口命名必须符合《[CAPI接口编码规范](./capi_naming.md)》。
|
||||
* 【规则】C API相关的接口文件，包含接口列表文件ndk.json，头文件，编译构建脚本三部分；这些内容必须放置在interface_sdk_c仓中，不能对外产生依赖。三方库接口暴露规则同自研仓，接口是处理过的接口文件，不是三方库原生文件。
|
||||
* 【规则】接口命名必须符合《[C API接口编码规范](./capi_naming.md)》。
|
||||
* 【规则】需要发布的接口需要明确在ndk.json文件中声明列出，不允许直接发布镜像中的动态库，都采用stub动态库的方式发布。
|
||||
* json文件是一个符号描述数组，举例如下：
|
||||
```
|
||||
@ -42,7 +42,7 @@
|
||||
]
|
||||
```
|
||||
name表示符号的名字，type表示符号类型，不写type，默认认为是函数；varible表示这个符号是变量。
|
||||
* 【规则】CAPI中头文件中不允许包含不发布的接口声明，类型定义；三方库的接口文件，可
|
||||
* 【规则】C API中头文件中不允许包含不发布的接口声明，类型定义；三方库的接口文件，可
|
||||
以备案保留。
|
||||
* 【规则】接口必须是C语言接口，不允许出现C++元素，保证引用方是C代码也能使用；提供头文件中的接口需要用C declare声明。
|
||||
|
||||
@ -61,24 +61,24 @@
|
||||
|
||||
* __例外__ 直接提供实现库，嵌入到应用包中的接口可以使用C++元素。
|
||||
|
||||
* 【规则】包含CAPI的实现动态库放到/system/{lib}/ndk目录下。
|
||||
* 【规则】包含C API的实现动态库放到/system/{lib}/ndk目录下。
|
||||
* 【规则】每个接口都需要与syscap相关联；一个头文件中的接口只能属于一个syscap，不能包含多个syscap能力；多个文件可以关联相同的syscap。
|
||||
* 【规则】自研接口按照文档注释写作规范进行注释，三方库接口有修改的，注释规则按照注释规范进行注释。
|
||||
* 【建议】对外提供的接口，采用对外封闭，依赖倒置原则；结构体的具体实现不对外暴露，方便后续扩展修改。
|
||||
* 【规则】自研接口按照如下文档注释写作规范进行注释，三方库接口有修改的，注释规则按照注释规范进行注释。
|
||||
* 【规则】对外提供的接口，采用对外封闭，依赖倒置原则；结构体的具体实现不对外暴露，方便后续扩展修改
|
||||
|
||||
> 此条是《[OpenHarmony API社区规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-quality.md)》规则16：注意封装：不暴露实现细节的C API补充解释。
|
||||
|
||||
### 兼容性规则
|
||||
* 【规则】接口发布后，需要保证版本上的兼容性；接口原型，语义，错误处理等都要保持兼容。
|
||||
* 【规则】接口删除需提前五个版本进行预告；在使用这个接口的时候实现时进行告警提示；头文件接口注释标注@deprecated。
|
||||
* 【规则】不允许进行接口原型变更，可以通过新增接口，废弃老接口的方式进行。
|
||||
* 【规则】接口语义不允许变更，语义通过xts用例保持兼容性。接口涉及的结构体，枚举值变更也会影响语义，建议在设计的时候保留一些字段供扩展使用。
|
||||
* 【规则】结构体成员，枚举值可以标明废弃，不建议删除。
|
||||
|
||||
## 文档注释写作规范
|
||||
CAPI中暴露的接口，分为自研接口与三方开源库接口。
|
||||
本章在OpenHarmony API社区规范[API设计概述](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-quality.md#api设计概述)基础上，对C API的注释流程做了补充。
|
||||
|
||||
自研接口注释书写规范步骤：
|
||||
1. 每个头文件都需要书写注释。
|
||||
2. 注释书写参考 [Nativ接口注释规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/template/native-template.md)，注释命令必须按照@开头。
|
||||
2. 注释书写参考 [Native接口注释规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/template/native-template.md)，注释命令必须按照@开头。
|
||||
3. 提交注释头文件到 https://gitee.com/openharmony-sig/interface_native_header/tree/master/zh-cn/native_sdk 这个仓。
|
||||
4. 等待资料审核，合入；同时翻译一份英文注释头文件到en目录。
|
||||
5. 下载这个头文件，覆盖到对应头文件。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user