NAPI是什么？

简单点理解就是在Openharmony里，实现上层js或ets应用与底层C/C++之间交互的框架。

Openharmony里的官方解释：NAPI（Native API）组件是一套对外接口基于Node.js N-API规范开发的原生模块扩展开发框架。还有NAPI适合封装IO、CPU密集型、OS底层等能力并对外暴露JS接口，通过NAPI可以实现JS与C/C++代码互相访问。我们可以通过NAPI接口构建例如网络通信、串口访问、多媒体解码、传感器数据收集等模块。

now,以Openharmon V3.1-Release版本为例，抽取代码实例，分为两部份进行分析。

面向上层js或ets接口

1.定义接口

接口描述文件在Openharmony里.d.ts后缀结束。

在分布式文件服务(//foundation/filemanagement/dfs_service)的@ohos.sendfile.d.ts文件中

import {AsyncCallback, Callback} from "./basic";declare namespace SendFile {  // 异步接口----回调方式  function sendFile(deviceId: string, sourPath: Array, destPath: Array, fileCount: number, callback: AsyncCallback);  // 异步接口----Promise方式  function sendFile(deviceId: string, sourPath: Array, destPath: Array, fileCount: number): Promise;  // 异步接口----回调方式  function on(type: 'sendFinished' | 'receiveFinished', callback: AsyncCallback): void;  // 同步接口  function off(type: 'sendFinished' | 'receiveFinished'): void;}export default SendFile;

以上为应用开发者提供了四个的JS接口,分为同步接口与异步接口两类，异步接口又分为回调方式与Promise。

2.App应用开发者的JS代码简单导入一下模块就可以直接调用了。

// 同步调用import myapp1 from "@ohos.SendFile"var result = myapp1.off(/* 参数自填*/);// 异步调用/** call back 方式的异步调用 */myapp1.sendFile("xxxx", sourPath, destPath, 4, function (err, ret) {    ......});/** Promise 方式的异步调用 */var  promiseObj = myapp1.sendFile("xxxx", sourPath, destPath, 4).then(data => {    ......}).catch(error => {    ......});

3.关于d.ts的注意事项

1.自定义d.ts接口文件时，在应用开发工具(DevEco Studio)里需要将此文件放入Openharmony sdk所在目录中，例如，在作者的本机为D:\Program\Huawei\OpenHarmony3.1\Sdk\ets\3.1.5.5\api与D:\Program\Huawei\OpenHarmony3.1\Sdk\js\3.1.5.5\api，根据应用调用者(js或ets)的不同放入不同的目录。

2.Openharmony已有d.ts接口文件，根据文件中注释里说的@since 9对应相应的导入sdk版本后，不需要另做导入dts。

面向C++的接口实现

1.模块注册与方法名映射

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cppnapi_value SendFileExport(napi_env env, napi_value exports){    const char className[] = "SendFile";    static napi_property_descriptor desc[] = { DECLARE_NAPI_FUNCTION("sendFile", JsSendFile), DECLARE_NAPI_FUNCTION("on", JsOn), DECLARE_NAPI_FUNCTION("off", JsOff),    };    napi_value sendFileClass = nullptr;    napi_define_class(env, className, sizeof(className), JsConstructor, nullptr, sizeof(desc) / sizeof(desc[0]), desc, &sendFileClass);    napi_set_named_property(env, exports, "SendFile", sendFileClass);    SendFile::RegisterCallback();    return exports;}// 模块注册NAPI_MODULE(sendfile, SendFileExport)

• 通过NAPI_MODULE与DECLARE_NAPI_FUNCTION两个宏分别完成模块注册与方法名映射。

• 这里dts定义了两个sendFile接口，为何只需要定义映射一个？

因为对js或ets来说sendFile对外接口名相同，在C++实现时根据传入的参数个数或者参数类型来判断js或ets调用哪个函数。

2.同步接口

根据映射，同步接口off对应C++的实现是JsOff。

• 函数声明

每一个映射后的函数，必须是参数napi_env env, napi_callback_info cbinfo，返回值为napi_value。

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cppnapi_value JsOff(napi_env env, napi_callback_info cbinfo){......}

为了实现js或ets调用，NAPI框架需要解决以下问题:数据传递与转换

js/ets传入的入参、得到的返回结果，需要转换成C/C++代码可以操作的数据类型,NAPI框架引入了一个中间的数据类型，来分别对应上层js/ets与C/C++的类型，以及数据类型的操作方法。

• 获取入参

napi_get_cb_info从cbinfo参数中js传入参数，以下为函数说明

// napi_get_cb_info从napi_callback_info类型的参数中得到回调的参数等数据napi_status napi_get_cb_info(  napi_env env,  napi_callback_info cbinfo, // 传入回调函数的回调信息  size_t *argc,      // 作为入参传入`argv`数组的大小，并将接收实际的参数个数  napi_value *argv,  // 存放参数的buffer  napi_value *this_arg,     // Javascript中的`this`  void** data // 接收数据指针);

argc为传入参数个数，argv为传入参数数组，此时参数的类型都为napi_value。

通过napi_typeof方法获取入参的实际类型

// napi_typeof获取指定对象的类型napi_status napi_typeof(  napi_env env,  napi_value value,  // 将要获取类型的Javascript值  napi_valuetype *result    // Javascript值的类型);

根据d.ts的描述，off传入的只有一个参数，参数类型为字符串。

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cppnapi_value JsOff(napi_env env, napi_callback_info cbinfo){    size_t requireArgc = 1;...    NAPI_ASSERT(env, argc == requireArgc, "requires 1 parameter"); //参数个数为1     napi_valuetype eventValueType = napi_undefined;napi_typeof(env, argv[0], &eventValueType);NAPI_ASSERT(env, eventValueType == napi_string, "type mismatch for parameter 1");//参数类型为napi_string，即为NAPI中定义一种字符串...}

• 类型转换为C/C++可识别的类型

napi_get_value_string_utf8方法将napi_string转换char*

napi_status napi_get_value_string_utf8(napi_env env,  napi_value value,  char* buf,  size_t bufsize,  size_t* result);

// foundation/filemanagement/dfs_service/frameworks/js/napi/src/sendfile_napi.cppnapi_value JsOff(napi_env env, napi_callback_info cbinfo){...    char* type = nullptr;    size_t typeLen = 0;    napi_get_value_string_utf8(env, argv[0], nullptr, 0, &typeLen);    NAPI_ASSERT(env, typeLen > 0, "typeLen == 0");    type = new char[typeLen + 1];    napi_get_value_string_utf8(env, argv[0], type, typeLen + 1, &typeLen);...}

• 返回值

C++没有返回值，此时JsOff将nullptr返回。

NAPI框架没有nullptr，通过napi_get_undefined将nullptr转换成napi_undefined。

napi_value JsOff(napi_env env, napi_callback_info cbinfo){...    napi_value result = nullptr;    napi_get_undefined(env, &result);    return result;}

后续更精彩

1.Openharmony应用NAPI详解--进阶篇