在前两篇文章里笔者简单介绍了 NAPI 工程结构以及生成的 cpp 源码部分,其中 JS 应用层传递过来的数据被封装在了 napi_value 中,使用前先要转换成对应的 C/C++ 数据类型,C/C++ 端的数据也要转换成 napi_value 数据类型传递给 JS 应用层,本节笔者简单介绍一下 NAPI 中提供的数据类型转换相关知识点。
NAPI是什么?
NAPI 类似于 Java 里的 JNI,它是 OpenHarmony 系统提供的一套原生模块扩展开发框架,它遵循了 Node.js 的 NAPI 接口规范并在方舟引擎内(ArkNativeEngine)内部做了自有实现,NAPI 为开发者提供了 JS 与 C/C++ 模块之间相互调用的交互能力,交互流程如下图所示:
napi_value数据类型
OpenHarmony NAPI 将 ECMAScript 标准中定义的 Boolean、Null、Undefined、Number、BigInt、String、Symbol和 Object 这八种数据类型以及函数对应的 Function 类型统一封装成了 napi_value 类型,它是 JS 数据类型和 C/C++ 数据类型之间的桥梁,napi_value (opens new window)官网说明如下:
// This is an opaque pointer that is used to represent a JavaScript value.
napi_value 表示 JS 值的不透明指针,在 C/C++ 端要使用 JS 端传递的数据类型,都是通过 NAPI 提供的相关方法把 napi_value 转换成 C/C++ 类型后再使用,同理当需要把 C/C++的数据传递给 JS 应用层也要通过 NAPI 提供的方法把 C/C++ 端的数据转换成 napi_value 再向上传递。
C/C++转napi_value
NAPI提供了 napi_create_ 开头的方法表示把 C/C++ 类型转换成 napi_value 类型,常见方法如下所示:
- int类型转换
NAPI_EXTERN napi_status napi_create_int32(napi_env env,
int32_t value,
napi_value* result);
NAPI_EXTERN napi_status napi_create_uint32(napi_env env,
uint32_t value,
napi_value* result);
NAPI_EXTERN napi_status napi_create_int64(napi_env env,
int64_t value,
napi_value* result);
把 C/C++ 的 int32_t、uint32_t 以及 int64_t 类型转换成 napi_value 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:C/C++端的 int 类型的值。
* **result**:napi_value,返回给 JS 应用层的数据。
- double类型转换
NAPI_EXTERN napi_status napi_create_double(napi_env env,
double value,
napi_value* result);
把 C/C++ 端的 double 类型转换成 napi_value 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:C/C++ 端的 double 类型的值。
* **result**:napi_value,返回给 JS 应用层的数据。
- string类型转换
NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);
NAPI_EXTERN napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result);
NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);
把 C/C++ 端的 char 类型转换成 napi_value 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **str**:C/C++端的字符串类型的值。
* **size_t**:str 的长度。
* **result**:napi_value,返回给 JS 应用层的数据。
napi_value转C/C++
NAPI提供了 napi_get_value_ 开头的方法表示把 napi_value 转换成 C/C++ 类型,常见方法如下所示:
- int类型转换
NAPI_EXTERN napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result);
NAPI_EXTERN napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result);
NAPI_EXTERN napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result);
把 JS 端的 number 类型转换成 C/C++ 的对应数据类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:JS 端传递进来的数据。
* **result**:接收 value 的值。
- double类型转换
NAPI_EXTERN napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result);
把 JS 端的 **number** 类型转换成 C/C++ 的 **double** 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:JS 端传递进来的数据。
* **result**:接收 value 的值。
- string类型转换
NAPI_EXTERN napi_status napi_get_value_string_latin1(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result);
// Copies UTF-8 encoded bytes from a string into a buffer.
NAPI_EXTERN napi_status napi_get_value_string_utf8(napi_env env,
napi_value value,
char* buf,
size_t bufsize,
size_t* result);
// Copies UTF-16 encoded bytes from a string into a buffer.
NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env,
napi_value value,
char16_t* buf,
size_t bufsize,
size_t* result);
把 JS 端的 string 类型转换成 C/C++ 的 char 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:napi_value,JS 端传递进来的数据。
* **buf**:char数组,用来存放napi_value中的 string 值
* **bufsize**:char数组长度
* **result**:接收 value 的值。
- boolean类型转换
NAPI_EXTERN napi_status napi_get_value_bool(napi_env env,
napi_value value,
bool* result);
把 JS 端的 boolean 类型转换成 C/C++ 的 bool 类型,参数说明如下:
* **env**:方法调用者的运行环境,包含 JS 引擎等。
* **value**:JS 端传递进来的数据。
* **result**:接收 value 的值。
小结
本节笔者简单介绍一下 NAPI 提供的相关 API,读者先对数据转换有个大致的印象,下节笔者将要带领读者通过 NAPI 提供的方法实现一个扩展方法:MD5 加密计算。
如果想更深入的学习 OpenHarmony 开发的内容,可以参考以下学习文档:
OpenHarmony 开发环境搭建:https://qr18.cn/CgxrRy
《OpenHarmony源码解析》:https://qr18.cn/CgxrRy
- 搭建开发环境
- Windows 开发环境的搭建
- Ubuntu 开发环境搭建
- Linux 与 Windows 之间的文件共享
- ……
系统架构分析:https://qr18.cn/CgxrRy
- 构建子系统
- 启动流程
- 子系统
- 分布式任务调度子系统
- 分布式通信子系统
- 驱动子系统
- ……