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<string>, destPath: Array<string>, fileCount: number, callback: AsyncCallback<number>);// 异步接口----Promise方式function sendFile(deviceId: string, sourPath: Array<string>, destPath: Array<string>, fileCount: number): Promise<number>;// 异步接口----回调方式function on(type: 'sendFinished' | 'receiveFinished', callback: AsyncCallback<TransResult>): 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.cpp
napi_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.cpp
napi_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,         // 存放参数的buffernapi_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.cpp
napi_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.cpp
napi_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详解--进阶篇