tu-xiaohang修改napi_wrap及napi_wrap_sendable相关文档

Native与ArkTS对象绑定

场景介绍

通过napi_wrap将ArkTS对象与Native的C++对象绑定，后续操作时再通过napi_unwrap将ArkTS对象绑定的C++对象取出，并对其进行操作。

使用示例

接口声明、编译配置以及模块注册

接口声明

// index.d.ts
export class MyObject {
  constructor(arg: number);
  plusOne: () => number;

  public get value();
  public set value(newVal: number);
}

编译配置

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(napi_wrap_demo)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

if(DEFINED PACKAGE_FIND_FILE)
    include(${PACKAGE_FIND_FILE})
endif()

include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)

add_definitions("-DLOG_DOMAIN=0x0000")
add_definitions("-DLOG_TAG=\"testTag\"")

add_library(entry SHARED napi_init.cpp)
target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)

模块注册

// napi_init.cpp
#include "napi/native_api.h"
#include "hilog/log.h"

class MyObject {
public:
    static napi_value Init(napi_env env, napi_value exports);
    static void Destructor(napi_env env, void* nativeObject, void* finalize_hint);

private:
    explicit MyObject(double value_ = 0);
    ~MyObject();

    static napi_value New(napi_env env, napi_callback_info info);
    static napi_value GetValue(napi_env env, napi_callback_info info);
    static napi_value SetValue(napi_env env, napi_callback_info info);
    static napi_value PlusOne(napi_env env, napi_callback_info info);

    double value_;
    napi_env env_;
    napi_ref wrapper_;
};

MyObject::MyObject(double value) : value_(value), env_(nullptr), wrapper_(nullptr) {}

MyObject::~MyObject()
{
    napi_status status = napi_delete_reference(env_, wrapper_);
    if (status != napi_ok) {
        OH_LOG_INFO(LOG_APP, "Failed to delete reference, return code: %{public}d", status);
    }
}

void MyObject::Destructor(napi_env env, void* nativeObject, [[maybe_unused]] void* finalize_hint)
{
    OH_LOG_INFO(LOG_APP, "MyObject::Destructor called");
    delete reinterpret_cast<MyObject*>(nativeObject);
}

napi_value MyObject::Init(napi_env env, napi_value exports)
{
    napi_property_descriptor properties[] = {
        { "value", nullptr, nullptr, GetValue, SetValue, nullptr, napi_default, nullptr },
        { "plusOne", nullptr, PlusOne, nullptr, nullptr, nullptr, napi_default, nullptr }
    };

    napi_value cons = nullptr;
    napi_status status = napi_define_class(env, "MyObject", NAPI_AUTO_LENGTH, New, nullptr, 2, properties, &cons);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_define_class fail");
        return nullptr;
    }

    status = napi_set_named_property(env, exports, "MyObject", cons);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_set_named_property fail");
        return nullptr;
    }
    return exports;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    MyObject::Init(env, exports);
    return exports;
}
EXTERN_C_END

static napi_module nativeModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = nullptr,
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterObjectWrapModule()
{
    napi_module_register(&nativeModule);
}

在构造函数中绑定ArkTS与C++对象

napi_value MyObject::New(napi_env env, napi_callback_info info)
{
    OH_LOG_INFO(LOG_APP, "MyObject::New called");

    napi_value newTarget = nullptr;
    napi_status status = napi_get_new_target(env, info, &newTarget);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_get_new_target fail");
        return nullptr;
    }
    if (newTarget != nullptr) {
        // 使用`new MyObject(...)`调用方式
        size_t argc = 1;
        napi_value args[1] = { nullptr };
        napi_value jsThis = nullptr;
        status = napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr);
        if (status != napi_ok) {
            napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
            return nullptr;
        }

        double value = 0.0;
        napi_valuetype valuetype = napi_undefined;
        status = napi_typeof(env, args[0], &valuetype);
        if (status != napi_ok) {
            napi_throw_error(env, nullptr, "Node-API napi_typeof fail");
            return nullptr;
        }
        if (valuetype != napi_undefined) {
            status = napi_get_value_double(env, args[0], &value);
            if (status != napi_ok) {
                napi_throw_error(env, nullptr, "Node-API napi_get_value_double fail");
                return nullptr;
            }
        }

        MyObject* obj = new MyObject(value);

        obj->env_ = env;
        // 通过napi_wrap将ArkTS对象jsThis)与C++对象obj绑定
        status = napi_wrap(env,
                           jsThis,
                           reinterpret_cast<void*>(obj),
                           MyObject::Destructor,
                           nullptr,  // finalize_hint
                           &obj->wrapper_);
        // napi_wrap失败时，必须手动释放已分配的内存，以防止内存泄漏
        if (status != napi_ok) {
            delete obj;
            napi_throw_error(env, nullptr, "Node-API napi_wrap fail");
            return jsThis;
        }
        // 从napi_wrap接口的result获取napi_ref的行为，将会为jsThis创建强引用，
        // 若开发者不需要主动管理jsThis的生命周期，可直接在napi_wrap最后一个参数中传入nullptr，
        // 或者使用napi_reference_unref方法将napi_ref转为弱引用。
        uint32_t refCount = 0;
        napi_reference_unref(env, obj->wrapper_, &refCount);

        return jsThis;
    } else {
        // 使用`MyObject(...)`调用方式
        size_t argc = 1;
        napi_value args[1] = { nullptr };
        napi_value jsThis = nullptr;
        status = napi_get_cb_info(env, info, &argc, args, &jsThis, nullptr);
        if (status != napi_ok) {
            napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
            return nullptr;
        }

        napi_value cons = nullptr;
        const char* constructorName = "MyObject";
        status = napi_get_named_property(env, jsThis, constructorName, &cons);
        if (status != napi_ok) {
            napi_throw_error(env, nullptr, "Node-API napi_get_named_property fail");
            return nullptr;
        }
        napi_value instance = nullptr;
        status = napi_new_instance(env, cons, argc, args, &instance);
        if (status != napi_ok) {
            napi_throw_error(env, nullptr, "Node-API napi_new_instance fail");
            return nullptr;
        }

        return instance;
    }
}

将ArkTS对象之前绑定的C++对象取出，并对其进行操作

napi_value MyObject::GetValue(napi_env env, napi_callback_info info)
{
    OH_LOG_INFO(LOG_APP, "MyObject::GetValue called");

    napi_value jsThis = nullptr;
    napi_status status = napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
        return nullptr;
    }

    MyObject* obj = nullptr;
    // 通过napi_unwrap将jsThis之前绑定的C++对象取出，并对其进行操作
    status = napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_unwrap fail");
        return nullptr;
    }
    napi_value num = nullptr;
    status = napi_create_double(env, obj->value_, &num);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_create_double fail");
        return nullptr;
    }

    return num;
}

napi_value MyObject::SetValue(napi_env env, napi_callback_info info)
{
    OH_LOG_INFO(LOG_APP, "MyObject::SetValue called");

    size_t argc = 1;
    napi_value value = nullptr;
    napi_value jsThis = nullptr;

    napi_status status = napi_get_cb_info(env, info, &argc, &value, &jsThis, nullptr);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
        return nullptr;
    }

    MyObject* obj = nullptr;
    // 通过napi_unwrap将jsThis之前绑定的C++对象取出，并对其进行操作
    status = napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_unwrap fail");
        return nullptr;
    }
    status = napi_get_value_double(env, value, &obj->value_);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_get_value_double fail");
        return nullptr;
    }

    return nullptr;
}

napi_value MyObject::PlusOne(napi_env env, napi_callback_info info)
{
    OH_LOG_INFO(LOG_APP, "MyObject::PlusOne called");

    napi_value jsThis = nullptr;
    napi_status status = napi_get_cb_info(env, info, nullptr, nullptr, &jsThis, nullptr);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_get_cb_info fail");
        return nullptr;
    }

    MyObject* obj = nullptr;
    // 通过napi_unwrap将jsThis之前绑定的C++对象取出，并对其进行操作
    status = napi_unwrap(env, jsThis, reinterpret_cast<void**>(&obj));
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_unwrap fail");
        return nullptr;
    }
    obj->value_ += 1;
    napi_value num = nullptr;
    status = napi_create_double(env, obj->value_, &num);
    if (status != napi_ok) {
        napi_throw_error(env, nullptr, "Node-API napi_create_double fail");
        return nullptr;
    }

    return num;
}

ArkTS侧示例代码

import { hilog } from '@kit.PerformanceAnalysisKit';
import { MyObject } from 'libentry.so';

try {
    let object : MyObject = new MyObject(0);
    object.value = 1023.1;
    hilog.info(0x0000, 'testTag', 'MyObject value after set: %{public}s', object.value.toString());
    hilog.info(0x0000, 'testTag', 'MyObject plusOne: %{public}s', object.plusOne().toString());
} catch (error) {
    hilog.error(0x0000, 'testTag', 'Test Node-API error: %{public}s', error.message);
}