北向应用集成三方库——NAPI数据类型转换与同步调用

napi的数据类型

在 通过IDE创建工程 的示例代码中，我们使用napi_create_string_utf8函数将C/C++ string转换成NAPI类型——napi_value 。OpenHarmony NAPI将ECMAScript标准中定义的Boolean、Null、Undefined、Number、BigInt、String、Symbol和Object八种数据类型，以及函数对应的Function类型，统一封装成napi_value类型 (也称为JS类型)。该类型用于接收应用传递过来的数据以及返回数据给应用。 本文将讲述JS类型和C/C++数据类型之间的转换 。

napi的数据类型转换接口

OpenHarmony NAPI提供了很多接口用来napi的数据类型与C/C++数据类型之间的转换。以下列出常用的几种接口

C/C++数据类型转napi类型

• napi_create_double(napi_env env, double value, napi_value* result);
• napi_create_int32(napi_env env, int32_t value, napi_value* result);
• napi_create_uint32(napi_env env, uint32_t value, napi_value* result);
• napi_create_int64(napi_env env, int64_t value, napi_value* result);
• napi_create_string_utf8(napi_env env, const char* str, size_t length, napi_value* result);

napi类型转C/C++数据类型

• napi_get_value_double(napi_env env, napi_value value, double* result);
• napi_get_value_int32(napi_env env, napi_value value, int32_t* result);
• napi_get_value_uint32(napi_env env, napi_value value, uint32_t* result);
• napi_get_value_int64(napi_env env, napi_value value, int64_t* result);
• napi_get_value_string_utf8(napi_env env, napi_value value, char* buf, size_t bufsize, size_t* result);
• napi_get_value_bool(napi_env env, napi_value value, bool* result);

同步调用

我们在 通过IDE创建工程 示例中添加一个简单的接口——add(num1, num2)来讲述具体细节，以及接口同步方式的实现。

NAPI的同步方式调用的扩展API代码处理流程如下图。

添加NAPI扩展API

• NAPI定义并注册接口

  static napi_value add(napi_env env, napi_callback_info info) {
      napi_value reuslt;
      return reuslt;
  }
  static napi_value registerFunc(napi_env env, napi_value exports)
  {
      static napi_property_descriptor desc[] = {
           { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
      };
  }
  

• eTs定义接口

  function add(num1: number, num2: number): number;
  

获取JS参数

NAPI定义API方法时的接收参数为(napi_env, napi_callback_info)，其中napi_callback_info为上下文的信息。通过NAPI提供了napi_get_cb_info()方法可从napi_callback_info中获取参数列表、this及其他数据。
napi_get_cb_info函数说明如下：

napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* thisArg,
                             void** data)

参数说明：

• [in] env: 传入接口调用者的环境，包含js引擎等，由框架提供，默认情况下直接传入即可.
• [in] value: napi_callback_info对象，上下文的信息
• [in-out] argc: argv数组的长度。若napi_callback_info中实际包含的参数的个数大于请求的数量argc，将只复制argc的值所指定数量的参数只argv中。若实际的参数个数小于请求的数量，将复制全部的参数，数组多余的空间用空值填充，并将参数实际长度写入argc。
• [out] argv: 用于接收参数列表
• [out] thisArg: 用于接收this对象
• [out] data: NAPI的上下文数据 返回值：返回napi_ok表示转换成功，其他值失败。下面的返回napi_status方法一样。

在add方法中，调用napi_get_cb_info函数：

// env、info 参数由NAPI框架传入
static napi_value add(napi_env env, napi_callback_info info) {
  size_t argc = 2;
  napi_value args[2];
  napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
  napi_value reuslt;
  return reuslt;
}

JS类型值转换为C/C++类型的值

因传入的参数是Javascript值类型，并被框架封装成统一的唯一类型——napi_value类型，为了能够进行计算，我们需要获取其对应在C/C++中的类型的值。我们可以用napi类型转C/C++数据类型中的相关接口进行转换。此示例中我们用 napi_get_value_double方式：

static napi_value add(napi_env env, napi_callback_info info) {
  // 获取2个参数，值的类型是js类型（napi_value）
  size_t argc = 2;
  napi_value args[2];
  napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
  // 将js类型（napi_value）的参数值转换成C++类型double
  double value0;
  napi_get_value_double(env, args[0], &value0);
  double value1;
  napi_get_value_double(env, args[1], &value1);
  napi_value reuslt;
  return reuslt;
}

业务逻辑计算

使用Native代码（C/C++代码）完成业务场景逻辑计算。本示例中就简化为2个数字简单相加，代码如下：

static napi_value add(napi_env env, napi_callback_info info) {
  ...
  // 业务逻辑运算
  double sum = value0 + value1;
  ...
}

计算结果转换为JS类型并返回

计算的结果是C/C++ double类型，不能直接返回给JS，需要转换成NAPI node_value类型 。本示例中我们用到
C/C++数据类型转napi类型 中的napi_create_double接口：

static napi_value add(napi_env env, napi_callback_info info) {
  ...
  //  将结果由C++类型（double）转换成js类型（napi_value）
  napi_value reuslt;
  napi_create_double(env, sum, &reuslt)
  // 将结果返回到JS
  return result;
}

完整的示例代码参照完整源码。

应用调用

本示例程序也是在DevEco Studio开发，应用调用可参照通过IDE创建工程

import testNapi from "libentry.so"
let num1 = 123
let num2 = 456
let result = testNapi.add(num1, num2)

参考资料

• Hello napi完整源码工程
• 深入浅出 OpenHarmony NAPI 之数据类型转换
• OpenHarmony 知识体系。

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开发技术，这边特意整理了《鸿蒙开发学习手册》（共计890页），希望对大家有所帮助：https://qr21.cn/FV7h05

《鸿蒙开发学习手册》：

如何快速入门：https://qr21.cn/FV7h05

1. 基本概念
2. 构建第一个ArkTS应用
3. ……

开发基础知识：https://qr21.cn/FV7h05

1. 应用基础知识
2. 配置文件
3. 应用数据管理
4. 应用安全管理
5. 应用隐私保护
6. 三方应用调用管控机制
7. 资源分类与访问
8. 学习ArkTS语言
9. ……

基于ArkTS 开发：https://qr21.cn/FV7h05

1. Ability开发
2. UI开发
3. 公共事件与通知
4. 窗口管理
5. 媒体
6. 安全
7. 网络与链接
8. 电话服务
9. 数据管理
10. 后台任务(Background Task)管理
11. 设备管理
12. 设备使用信息统计
13. DFX
14. 国际化开发
15. 折叠屏系列
16. ……

鸿蒙开发面试真题（含参考答案）：https://qr18.cn/F781PH

鸿蒙开发面试大盘集篇（共计319页）：https://qr18.cn/F781PH

1.项目开发必备面试题
2.性能优化方向
3.架构方向
4.鸿蒙开发系统底层方向
5.鸿蒙音视频开发方向
6.鸿蒙车载开发方向
7.鸿蒙南向开发方向