C API用户指导

基础知识

了解C API基础知识，请参考《Native API入门》。

接口开放策略

不开放原则

应用生态提供的核心特性只开放ArkTS API，不开发C API。
不开发ArkUI的C API。
不开发硬件底层接口（HDI）C API。
不开放命令行接口C API。

开放原则

高性能、密集计算业务场景主动开放C API，例如：需要高性能的IO、CPU密集计算等场景；音视频编解码、图形计算等场景。
应用生态业务依赖的场景，主动开放高阶C API。例如：对标竞品，媒体高阶C API。
应用生态框架以来的场景，按需开放C API。例如：按需开放Unity/electron/CFE框架中依赖的C API。
行业约定或者标准要求的场景按需开放C API。此类C API独立发布，不放入OpenHarmony C API中。例如：金融或者安全行业高密加密算法等，按需独立发布。

前向兼容性原则

C API的前向兼容性原则与ArkTS API策略保持一致。CI流程中会使用自动化工具进行看护。

C API接口设计规范

本规范是在《OpenHarmony API治理章程》《OpenHarmony API社区规范》的基础上，对C API设计进行的一些补充。在C API接口设计上同时满足此三份规范。

设计规则

【规则】C API相关的接口文件，包含接口列表文件ndk.json，头文件，编译构建脚本三部分；这些内容必须放置在interface_sdk_c仓中，不能对外产生依赖。三方库接口暴露规则同自研仓，接口是处理过的接口文件，不是三方库原生文件。
【规则】接口命名必须符合《C API接口编码规范》。
【规则】需要发布的接口需要明确在ndk.json文件中声明列出，不允许直接发布镜像中的动态库，都采用stub动态库的方式发布。
- json文件是一个符号描述数组，举例如下：
```
[
    {
        "name": "__progname",
        "type": "variable"
    },
    {
        "name": "pthread_cond_clockwait"
    }
]
```
name表示符号的名字，type表示符号类型，不写type，默认认为是函数；varible表示这个符号是变量。
【规则】C API中头文件中不允许包含不发布的接口声明，类型定义；三方库的接口文件，可以备案保留。
【规则】接口必须是C语言接口，不允许出现C++元素，保证引用方是C代码也能使用；提供头文件中的接口需要用C declare声明。
- C declare声明
```
#ifdef __cplusplus
extern "C" {
#endif
...
#ifdef __cplusplus
}
#endif
```
- 反例
  struct/enum声明的类型，如果没有声明typedef类型，在使用时必须加上struct、enum关键字。
- 例外直接提供实现库，嵌入到应用包中的接口可以使用C++元素。
【规则】包含C API的实现动态库放到/system/{lib}/ndk目录下。
【规则】每个接口都需要与syscap相关联；一个头文件中的接口只能属于一个syscap，不能包含多个syscap能力；多个文件可以关联相同的syscap。
【规则】自研接口按照如下文档注释写作规范进行注释，三方库接口有修改的，注释规则按照注释规范进行注释。
【规则】对外提供的接口，采用对外封闭，依赖倒置原则；结构体的具体实现不对外暴露，方便后续扩展修改

此条是《OpenHarmony API社区规范》规则16：注意封装：不暴露实现细节的C API补充解释。

兼容性规则

【规则】不允许进行接口原型变更，可以通过新增接口，废弃老接口的方式进行。
【规则】接口语义不允许变更，语义通过xts用例保持兼容性。接口涉及的结构体，枚举值变更也会影响语义，建议在设计的时候保留一些字段供扩展使用。
【规则】结构体成员，枚举值可以标明废弃，不建议删除。

文档注释写作规范

本章在OpenHarmony API社区规范API设计概述基础上，对C API的注释流程做了补充。

自研接口注释书写规范步骤：

每个头文件都需要书写注释。
注释书写参考 Native接口注释规范，注释命令必须按照@开头。
提交注释头文件到 https://gitee.com/openharmony-sig/interface_native_header/tree/master/zh-cn/native_sdk 这个仓。
等待资料审核，合入；同时翻译一份英文注释头文件到en目录。
下载这个头文件，覆盖到对应头文件。