• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# C API用户指导
2
3## 基础知识
4了解C API基础知识，请参考《[Native API入门](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/native-api-intro.md)》。
5
6
7## 接口开放策略
8
9### 不开放原则
10
111. 应用生态提供的核心特性只开放ArkTS API，不开发C API。
122. 不开发ArkUI的C API。
133. 不开发硬件底层接口（HDI）C API。
144. 不开放命令行接口C API。
15### 开放原则
165. 高性能、密集计算业务场景主动开放C API，例如：需要高性能的IO、CPU密集计算等场景；音视频编解码、图形计算等场景。
176. 应用生态业务依赖的场景，主动开放高阶C API。例如：对标竞品，媒体高阶C API。
187. 应用生态框架以来的场景，按需开放C API。例如：按需开放Unity/electron/CFE框架中依赖的C API。
198. 行业约定或者标准要求的场景按需开放C API。此类C API独立发布，不放入OpenHarmony C API中。例如：金融或者安全行业高密加密算法等，按需独立发布。
20
21### 前向兼容性原则
229. C API的前向兼容性原则与ArkTS API策略保持一致。CI流程中会使用自动化工具进行看护。
23
24
25## C API接口设计规范
26本规范是在《[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接口设计上同时满足此三份规范。
27
28### 设计规则
29* 【规则】C API相关的接口文件，包含接口列表文件ndk.json，头文件，编译构建脚本三部分；这些内容必须放置在interface_sdk_c仓中，不能对外产生依赖。三方库接口暴露规则同自研仓，接口是处理过的接口文件，不是三方库原生文件。
30* 【规则】接口命名必须符合《[C API接口编码规范](./capi_naming.md)》。
31* 【规则】需要发布的接口需要明确在ndk.json文件中声明列出，不允许直接发布镜像中的动态库，都采用stub动态库的方式发布。
32  * json文件是一个符号描述数组，举例如下：
33  ```
34  [
35      {
36          "name": "__progname",
37          "type": "variable"
38      },
39      {
40          "name": "pthread_cond_clockwait"
41      }
42  ]
43  ```
44  name表示符号的名字，type表示符号类型，不写type，默认认为是函数；varible表示这个符号是变量。
45* 【规则】C API中头文件中不允许包含不发布的接口声明，类型定义；三方库的接口文件，可
46以备案保留。
47* 【规则】接口必须是C语言接口，不允许出现C++元素，保证引用方是C代码也能使用；提供头文件中的接口需要用C declare声明。
48
49  * C declare声明
50  ```
51  #ifdef __cplusplus
52  extern "C" {
53  #endif
54  ...
55  #ifdef __cplusplus
56  }
57  #endif
58  ```
59  * __反例__
60  struct/enum声明的类型，如果没有声明typedef类型，在使用时必须加上struct、enum关键字。
61
62  * __例外__  直接提供实现库，嵌入到应用包中的接口可以使用C++元素。
63
64* 【规则】包含C API的实现动态库放到/system/{lib}/ndk目录下。
65* 【规则】每个接口都需要与syscap相关联；一个头文件中的接口只能属于一个syscap，不能包含多个syscap能力；多个文件可以关联相同的syscap。
66* 【规则】自研接口按照如下文档注释写作规范进行注释，三方库接口有修改的，注释规则按照注释规范进行注释。
67* 【规则】对外提供的接口，采用对外封闭，依赖倒置原则；结构体的具体实现不对外暴露，方便后续扩展修改
68
69> 此条是《[OpenHarmony API社区规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-quality.md)》规则16：注意封装：不暴露实现细节的C API补充解释。
70
71### 兼容性规则
72* 【规则】不允许进行接口原型变更，可以通过新增接口，废弃老接口的方式进行。
73* 【规则】接口语义不允许变更，语义通过xts用例保持兼容性。接口涉及的结构体，枚举值变更也会影响语义，建议在设计的时候保留一些字段供扩展使用。
74* 【规则】结构体成员，枚举值可以标明废弃，不建议删除。
75
76## 文档注释写作规范
77本章在OpenHarmony API社区规范[API设计概述](https://gitee.com/openharmony/docs/blob/master/zh-cn/design/OpenHarmony-API-quality.md#api设计概述)基础上，对C API的注释流程做了补充。
78
79自研接口注释书写规范步骤：
801. 每个头文件都需要书写注释。
812. 注释书写参考 [Native接口注释规范](https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/template/native-template.md)，注释命令必须按照@开头。
823. 提交注释头文件到 https://gitee.com/openharmony-sig/interface_native_header/tree/master/zh-cn/native_sdk 这个仓。
834. 等待资料审核，合入；同时翻译一份英文注释头文件到en目录。
845. 下载这个头文件，覆盖到对应头文件。
85