OpenHarmony 入门——初识JS/ArkTS 侧的“JNI” NAPI基本开发步骤（三）

引言

前面文章OpenHarmony 入门——初识JS/ArkTS 侧的“JNI” NAPI（一）和 OpenHarmony 入门——初识JS/ArkTS 侧的“JNI” NAPI 常见的函数详解（二）介绍了NAPI的基础理论知识，今天重点介绍下如何去开发一个自己的NAPI 接口。

一、引入 #include "napi/native_api.h"实现C/C++ 的函数体

首先是在C/C++文件中引入 #include “napi/native_api.h”，然后就是按照普通逻辑实现C/C++ 的函数体。

#include "napi/native_api.h"

二、定义要开放的NAPI 接口函数与Native 函数的映射关系

即通过napi_define_properties、DECLARE_NAPI_PROPERTY、DECLARE_NAPI_STATIC_PROPERTY 将C/C++ 中的Native 函数或者属性开放给JavaScript 使用，通常是在框架自带的函数static napi_value Init(napi_env env, napi_value exports) 中完成映射的

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        {"Init", nullptr, ObjectDectionInit, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"Process", nullptr, ObjectDectionProcess, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"DeInit", nullptr, ObjectDectionDeInit, nullptr, nullptr, nullptr, napi_default, nullptr}};
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

也可以换成宏的形式

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        DECLARE_NAPI_FUNCTION("Init", ObjectDectionInit),
        DECLARE_NAPI_FUNCTION("Process", ObjectDectionProcess),
        DECLARE_NAPI_FUNCTION("DeInit", ObjectDectionDeInit)
         };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

这样子就建立完成了相关的映射关系，其中Init为ETS 侧调用的接口，而ObjectDectionInit则为Native 侧函数的真正实现，其他的类似。

三、建立接口与Module 的映射关系

1、定义一个napi_module 对象

主要就是定义一个napi_module 对象，把对应的so 绑定到nm_modname属性中，并且绑定了注册Module的入口函数。

/*
 * Napi Module define
 */
static napi_module msLiteModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "mslite_napi",
    .nm_priv = ((void *)0),
    .reserved = {0},
};

这样子绑定后就可以在ETS侧通过 import mslite_napi from ‘libmslite_napi.so’; 后

import mslite_napi from 'libmslite_napi.so';

let resourceManager = context.resourceManager;
mslite_napi.Init(resourceManager );
mslite_napi.Process(this.modelId, picDesc, buffer).then((value: InferResult) => {
                callback(value.objects);
              }).catch((err: BusinessError) => {
               
              });
mslite_napi.DeInit();

2、napi_module 对象绑定到系统函数RegisterModule中

然后再把napi_module 对象传入到系统函数RegisterModule中

/*
 * module register
 */
extern "C" __attribute__((constructor)) void RegisterModule(void) {
  MS_LOG(INFO) << "RegisterModule() is called";
  napi_module_register(&g_module);
}

3、执行napi_module 的入口函数nm_register_func

一般来说在OH系统中内置的NAPI 的注册入口函数是由Framework自动去执行，所以呢我们自己开发NAPI的话需要自己去调用触发才行。

四、定义ETS 接口描述文件.d.ts

在这里插入图片描述
假如dts文件里定义了两个同名接口，也只需要定义映射一个即可，因为对js或ets来说sendFile对外接口名相同，在C++实现时根据传入的参数个数或者参数类型来判断js或ets调用哪个函数

export const Init: (path:Object) => number;
export const Process: (modeid:number, picDesc:Object, buffer: ArrayBuffer) => number;
export const DeInit: () => number;

五、在Native侧实现接收和处理ETS的传参及反馈结果

因为在ETS侧你可以认为数据类型是弱类型的，具体的类型是什么，需要由Native侧自己去解析，对了Native侧接收ETS侧传递过来的函数的形参列表及返回值都是固定类型的。再以为例@ohos.myapp.d.ts

declare namespace myapp {
    // 同步方法
    function getVisitCountSync(key: string, defaultValue?: string): string;
    // 异步方法
    function getVisitCountAsync(key: string, callback: AsyncCallback<string>): void; // callback回调方式
    function getVisitCountAsync(key: string, defaultValue?: string): Promise<string>; // Promise方式
 }

#define GET_PARAMS(env, info, num)    \
    size_t argc = num;                \
    napi_value argv[num] = {nullptr}; \
    napi_value thisVar = nullptr;     \
    void *data = nullptr;             \
    napi_get_cb_info(env, info, &argc, argv, &thisVar, &data)

static napi_value ObjectDectionInit(napi_env env, napi_callback_info info) {
    int32_t ret;
    int32_t modelId;
    napi_value error_ret;
    napi_create_int32(env, -1, &error_ret);
    napi_value success_ret;

    napi_value result = nullptr;
    napi_get_undefined(env, &result);

    GET_PARAMS(env, info, 1);
    const std::string modelName = "yolov5s_pruned.ms"; 
    size_t modelSize;
    auto resourcesManager = OH_ResourceManager_InitNativeResourceManager(env, argv[0]);
    auto modelBuffer = ReadModelFile(resourcesManager, modelName, &modelSize);
    modelms = CreateMSLiteModel(modelBuffer, modelSize);

    napi_create_int32(env, modelId, &success_ret);
    return success_ret;
}

static napi_value ObjectDectionProcess(napi_env env, napi_callback_info info) {
    napi_value promise = nullptr;
    size_t argc = ARGS_THREE;
    napi_value argv[ARGS_THREE] = {nullptr};
    napi_value thisArg;
    int32_t ret = napi_get_cb_info(env, info, &argc, argv, &thisArg, nullptr);
    int32_t modelId = 0;
    PicDescNapi picDescNapi{};
    std::string data = "";
    napi_value undefinedResult = nullptr;
    napi_get_undefined(env, &undefinedResult);
    std::unique_ptr<MsAIAsyncContext> asyncContext = std::make_unique<MsAIAsyncContext>();

    for (size_t i = PARAM0; i < argc; i++) {
        if (i == PARAM0) {
            napi_status status = napi_get_value_int32(env, argv[i], &modelId);
            if ((status != napi_ok) || (modelId < 0)) {
                return undefinedResult;
            }
        } else if (i == PARAM1) {
            ret = ParsePicDesc(env, argv[i], picDescNapi);
            if (ret != RETCODE_SUCCESS) {
                return undefinedResult;
            }
        } else if (i == PARAM2) {
            char *array_buffer_data;
            size_t array_buffer_total;
            napi_status status = napi_get_arraybuffer_info(env, argv[i], reinterpret_cast<void **>(&array_buffer_data),
                                                           &array_buffer_total);
            if ((status != napi_ok) || (array_buffer_total <= 0)) {
                return undefinedResult;
            }
            data.assign(array_buffer_data, array_buffer_data + array_buffer_total);
        } else {
            LOGE("Invalid input params.");
            return undefinedResult;
        }
    }
    SetData(asyncContext, modelId, picDescNapi, data);
    napi_value resourceName = nullptr;
    napi_create_string_utf8(env, "Process", NAPI_AUTO_LENGTH, &resourceName);
    auto status = napi_create_promise(env, &asyncContext->deferred, &promise);
    if (status != napi_ok) {
        return undefinedResult;
    }
    if (1) {
        status = napi_create_async_work(env, nullptr, resourceName, ExecuteCB, PromiseCompleteCB,
                                        static_cast<void *>(asyncContext.get()), &asyncContext->asyncWork);
        async_creat = 1;
    }
    status = napi_queue_async_work(env, asyncContext->asyncWork);
    if (status == napi_ok) {
        asyncContext.release();
    } else {
        return undefinedResult;
    }
    return promise;
}

static napi_value ObjectDectionDeInit(napi_env env, napi_callback_info info) {
    napi_value success_ret;
    napi_create_int32(env, 0, &success_ret);
    return success_ret;
}

1、开发同步接口

C开发者做好数据的转换工作就可以了。JavaScript调用传递的参数对象、函数对象都是以napi_value这样一个抽象的类型提供给C的，开发者需要将它们转换为C数据类型进行计算，再将计算结果转为napi_value类型返回就可以了。NAPI框架提供了各种api接口为用户完成这些转换，这些转换工作背后是依赖JS引擎去实现的。

static napi_value GetVisitCountSync(napi_env env, napi_callback_info info) {    
  /* 根据环境变量获取参数 */
  size_t argc = 2; //参数个数
  napi_value argv[2] = { 0 }; //参数定义
 
  /* 入参变量获取 */
  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
  // 获取入参的类型
  napi_valuetype valueType = napi_undefined;
  napi_typeof(env, argv[0], &valueType);    
 
  // 入参值转换为C/C++可以操作的数据类型
  char value[VALUE_BUFFER_SIZE] = { 0 };
  size_t valueLen = 0;
  napi_get_value_string_utf8(env, argv[0], value, VALUE_BUFFER_SIZE, &valueLen);
 
  // ...... 省略若干业务流程计算步骤
 
  /* C/C++数据类型转换为JS数据类型并返回 */
  napi_value result = nullptr; // JS字符串对象
  std::string resultStr = "Visit Count = 65535";
  napi_create_string_utf8(env, resultStr.c_str(), resultStr.length(), &result);
 
  return result; //返回JS对象
}

2.1、函数声明

每一个映射后的函数，必须是参数napi_env env, napi_callback_info cbinfo，返回值为napi_value。为了实现js或ets调用，NAPI框架需要解决以下问题，数据传递与转换，js/ets传入的入参、得到的返回结果，需要转换成C/C++代码可以操作的数据类型，因此NAPI框架引入了一个中间的数据类型，来分别对应上层js/ets与C/C++的类型，以及数据类型的操作方法。

2.2、获取入参

napi_get_cb_info从cbinfo参数中获取JavaScript传入参数，

2.3、把NAPI类型转换为C/C++可识别的类型

napi_value NapiDemo(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);
	...
}

2.4、返回值

当C++没有返回值时NapiDemo将nullptr返回，NAPI框架没有nullptr，通过napi_get_undefined将nullptr转换成

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

2、开发异步接口

C++实现NAPI异步接口需要做到三步：

同步返回结果给JS/ETS调用者
另起线程完成异步操作
通过回调(callback)或Promise将异步操作结果返回

//异步方法需要在不同线程中传递各种业务数据，定义一个结构体保存这些被传递的信息
struct MyAsyncContext {
    napi_env env = nullptr; // napi运行环境
    napi_async_work work = nullptr; // 异步工作对象
    napi_deferred deferred = nullptr; // 延迟执行对象（用于promise方式返回计算结果）
    napi_ref callbackRef = nullptr; // js callback function的引用对象 (用于callback方式返回计算结果)
};

static napi_value GetVisitCountAsync(napi_env env, napi_callback_info info)
{
    ...... // 省略部分前置代码
    // 首先还是读取JS入参
    napi_value argv[2] = { 0 };
    napi_get_cb_info(env, info, &argc, argv, &thisVar, &data);
    
    auto asyncContext = new MyAsyncContext(); //创建结构体用于保存各种需要在异步线程中传递的数据信息
    asyncContext->env = env;

    // callback回调方式和promise回调在ts接口文件中体现为2个独立的接口方法，但它们的接口名称相同，在C++侧是由同一个方法来实现的。
    // 这里通过判断JS传入的第二个参数是不是function类型，来判定用户调用的是callback回调接口，还是promise回调接口。
    napi_valuetype valueType = napi_undefined; 
    napi_typeof(env, argv[1], &valueType);

    // 为异步方法创建临时返回值。根据我们的ts接口文件定义，callback接口返回一个void就行， promise接口返回一个promise对象
    napi_value tmpRet = nullptr;
    if (valueType == napi_function) { // Js调用的是callback接口
        // 为js调用者传入的js fuction创建一个napi引用并保存到asyncContext中，以便后续在C++异步线程中能够回调该js fuction
        napi_create_reference(env, argv[1], 1, &asyncContext->callbackRef);    
        // callback接口返回参数为void，构造一个undefined的返回值即可。
        napi_get_undefined(env, &tmpRet);
    } else { // Js调用的是promise接口
        // 创建promise对象。tmpRet用于返回promise对象给js调用者， asyncContext->deferred用于后续在C++的异步线程中返回正真的计算结果
        napi_create_promise(env, &asyncContext->deferred, &tmpRet);
    }

    napi_value resource = nullptr;
    // 创建异步工作  （内部实际是使用了libuv组件的异步处理能力，需要开发者自定义两个callback方法）
    napi_create_async_work(
        env, nullptr, resource,
        [](napi_env env, void* data) { // 1）execute_callback 方法，该方法会在libuv新开的独立线程中被执行
            MyAsyncContext* innerAsyncContext = (MyAsyncContext*)data;
            // 需要异步处理的业务逻辑都放在这个execute_callback方法中，运算需要的数据可以通过data入参传进来。
            innerAsyncContext->status = 0;
            // ......
        },
        [](napi_env env, napi_status status, void* data) { // 2）complete_callback方法，在js应用的主线程中运行
            MyAsyncContext* innerAsyncContext = (MyAsyncContext*)data;
            napi_value asyncResult;
            // complete_callback回到了主线程，一般用于返回异步计算结果。execute_callback和complete_callback之间可以通过data传递数据信息
            // 计算结果一般是从data中获取的，这里略过直接硬编码
            napi_create_string_utf8(env, "Visit Count = 65535", NAPI_AUTO_LENGTH, &asyncResult);
            if (innerAsyncContext->deferred) {
                // promise 方式的回调
                // innerAsyncContext->deferred是前面步骤中创建的promise延迟执行对象（此时js调用者已经拿到了该promise对象）
                napi_resolve_deferred(env, innerAsyncContext->deferred, asyncResult);
            } else {
                // callback 函数方式的回调
                napi_value callback = nullptr;
                // 通过napi_ref获取之间js调用者传入的js function，并调用它返回计算结果
                napi_get_reference_value(env, innerAsyncContext->callbackRef, &callback);
                napi_call_function(env, nullptr, callback, 1, &asyncResult, nullptr);
                napi_delete_reference(env, innerAsyncContext->callbackRef);
            }
            // 在异步调用的结尾释放async_work和相关业务数据的内存
            napi_delete_async_work(env, innerAsyncContext->work);
            delete innerAsyncContext; 
        },
    (void*)asyncContext, &asyncContext->work);

  // 执行异步工作
  napi_queue_async_work(env, asyncContext->work);
  // 返回临时结果给js调用 （callback接口返回的是undefined, promise接口返回的是promise对象）
  return tmpRet;
}