鸿蒙5.0开发进阶:NDK代码开发-Node-API使用指南(使用Node-API扩展能力接口)

鸿蒙HarmonyOS应用开发之NDK开发导读 build目录:放置预定义的toolchain脚本文件ohos.toolchain.cmakeCMake编译时需要读取该文件中的默认值,比如编译器架构、C++库链接方式等,因此在编译时会通过CMAKE_TOOLCHAIN_FILE指出该文件的路径,便于CMake在编译时定位到该文件。build-tools文件夹:放置NDK提供的编译工具# 键入下一行命令查看CMake的版本# 结果llvm文件夹:放置NDK提供的编译器。 阅读详情

往期鸿蒙5.0全套实战文章必看:(文中附带全栈鸿蒙5.0学习资料)


使用Node-API扩展能力接口

简介

扩展能力接口进一步扩展了Node-API的功能,提供了一些额外的接口,用于在Node-API模块中与ArkTS进行更灵活的交互和定制,这些接口可以用于创建自定义ArkTS对象等场景。

Node-API接口开发流程参考使用Node-API实现跨语言交互开发流程,本文仅对接口对应C++及ArkTS相关代码进行展示。

模块加载

接口描述

接口描述
napi_load_module用于在Node-API模块中将abc文件作为模块加载,返回模块的命名空间,适用于需要在运行时动态加载模块或资源的应用程序,从而实现灵活的扩展和定制。
napi_load_module_with_info用于在Node-API中进行模块的加载,当模块加载出来之后,可以使用函数napi_get_property获取模块导出的变量,也可以使用napi_get_named_property获取模块导出的函数,该函数可以在新创建的ArkTS基础运行时环境中使用。
napi_module_register有些功能可能需要通过Node-API模块来实现以获得更好的性能,通过将这些功能实现为自定义模块并注册到ArkTS环境中,可以在一定程度上提高整体的性能。

使用示例

napi_load_module

使用Node-API接口在主线程中进行模块加载

napi_load_module_with_info

使用Node-API接口进行模块加载

napi_module_register

在ArkTS代码环境中使用Node-API模块编写的代码来实现特定的功能,可以将这部分功能封装成自定义模块,然后通过napi_module_register将其注册到ArkTS代码环境中,以实现功能的扩展和复用。

cpp部分代码

#include "napi/native_api.h"

// 此模块是一个Node-API的回调函数
static napi_value Add(napi_env env, napi_callback_info info)
{
    // 接受传入两个参数
    size_t requireArgc = 2;
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);

    // 将传入的napi_value类型的参数转化为double类型
    double valueLeft;
    double valueRight;
    napi_get_value_double(env, args[0], &valueLeft);
    napi_get_value_double(env, args[1], &valueRight);

    // 将转化后的double值相加并转成napi_value返回给ArkTS代码使用
    napi_value sum;
    napi_create_double(env, valueLeft + valueRight, &sum);

    return sum;
}

// C++函数Init用于初始化插件,用于将ArkTS层的函数或属性与C++层的函数进行关联
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    // 通过napi_property_descriptor结构体,可以定义需要导出的属性,并在Node-API模块中使用。napi_define_properties将属性与实际的C++函数进行关联,使其可以被ArkTS层访问和调用
    napi_property_descriptor desc[] = {
        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }
    };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

// 插件的初始化被定义在一个名为demoModule的结构体中,其中包含了模块的基本信息,比如模块的版本号、注册函数等
static napi_module demoModule = {
    .nm_version =1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

// 在RegisterEntryModule函数中,使用napi_module_register函数注册并导出了这个插件
extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
    napi_module_register(&demoModule);
}

接口声明

// index.d.ts
export const add: (a: number, b: number) => number;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

hilog.info(0x0000, 'testTag', 'Test Node-API 2 + 3 = %{public}d', testNapi.add(2, 3));

ArkTS Object相关

接口描述

接口描述
napi_create_object_with_properties用于在Node-API模块中使用给定的napi_property_descriptor创建ArkTS Object。descriptor的键名必须为string,且不可转为number。
napi_create_object_with_named_properties用于在Node-API模块中使用给定的napi_value和键名创建ArkTS Object。键名必须为string,且不可转为number。

使用示例

napi_create_object_with_properties

用给定的napi_property_descriptor作为属性去创建一个ArkTS对象,并且descriptor的键名必须为string,且不可转为number。

cpp部分代码

#include "napi/native_api.h"

static napi_value CreateObjectWithProperties(napi_env env, napi_callback_info info)
{
    size_t argc = 1;
    napi_value argv[1] = {nullptr};
    // 获取解析传递的参数
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    // 声明了一个napi_property_descriptor数组desc,其中包含了一个名为"name"的属性,其值为传入的第一个参数argv[0]。
    napi_property_descriptor desc[] = {
        {"name", nullptr, nullptr, nullptr, nullptr, argv[0], napi_default_jsproperty, nullptr}};
    napi_value object = nullptr;
    // 调用napi_create_object_with_properties来创建一个新的ArkTS对象,并将属性值添加到该对象中。
    napi_create_object_with_properties(env, &object, sizeof(desc) / sizeof(desc[0]), desc);
    napi_valuetype valueType;
    napi_typeof(env, object, &valueType);
    if (valueType == napi_object) {
        return object;
    }
}

接口声明

// index.d.ts
export const createObjectWithProperties: (data: string) => Object;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.createObjectWithProperties('createObject');
hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_properties:%{public}s', JSON.stringify(value));

napi_create_object_with_named_properties

用于使用给定的napi_value和键名创建一个ArkTS对象,并且给定的键名必须为string,且不可转为number。

cpp部分代码

#include "napi/native_api.h"

static napi_value CreateObjectWithNameProperties(napi_env env, napi_callback_info info)
{
    size_t argc = 1;
    napi_value argv[1] = {nullptr};
    // 获取解析传递的参数
    napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
    napi_value obj = nullptr;
    const char *key[] = {
        "name",
    };
    const napi_value values[] = {
        argv[0],
    };
    napi_property_descriptor desc[] = {{"name", nullptr, nullptr,
                                        nullptr, nullptr, nullptr, napi_default, nullptr}};
    napi_status status;
    status = napi_create_object_with_named_properties(env, &obj, sizeof(desc) / sizeof(desc[0]), key, values);
    if (status != napi_ok) {
        return argv[0];
    }
    return obj;
}

接口声明

// index.d.ts
export const createObjectWithNameProperties: (data: string) => string | { name: string };

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.createObjectWithNameProperties('ls');
hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_named_properties:%{public}s', JSON.stringify(value));

运行指定abc文件

接口描述

接口描述
napi_run_script_path用于在Node-API模块中运行指定abc文件。

使用示例

napi_run_script_path

在Node-API模块中运行abc文件。

cpp部分代码

#include "napi/native_api.h"

static napi_value RunScriptPath(napi_env env, napi_callback_info info)
{
    napi_value value = nullptr;
    // 注意:记得在应用rawfile目录下放置.abc文件
    const char *scriptPath = "/entry/resources/rawfile/test.abc";
    // 使用napi_run_script_path函数执行指定路径中的文件
    napi_status status = napi_run_script_path(env, scriptPath, &value);
    // 检查是否执行成功,如果失败,返回false
    napi_value returnValue = nullptr;
    if (value == nullptr || status != napi_ok) {
        napi_get_boolean(env, false, &returnValue);
    } else {
        napi_get_boolean(env, true, &returnValue);
    }
    return returnValue;
}

接口声明

// index.d.ts
export const runScriptPath: () => boolean;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

try {
  // 在此处执行错误返回false,成功就返回true
  hilog.info(0x0000, 'testTag', 'Test Node-API napi_run_script_path: %{public}s', testNapi.runScriptPath());
} catch (error) {
  hilog.error(0x0000, 'testTag', 'Test Node-API napi_run_script_path errorMessage: %{public}s', error.message);
}

test.js代码,将js代码编成.abc文件,步骤如下:

  1. 在SDK的ets/build-tools/ets-loader/bin/ark/build-win/bin目录下放置test.js文件
  2. 执行命令如es2abc.exe test.js --output test.abc后便可生成test.abc文件

放入指定路径中:/entry/resources/rawfile

function add(a, b) {
  return a+b;
}
add(1, 2);

异步工作对象加入队列并指定优先级

接口描述

接口描述
napi_queue_async_work_with_qos用于将异步工作对象加入队列,让开发者能够根据QoS优先级来管理和调度异步工作的执行,从而更好地满足程序的性能和响应需求。

使用示例

napi_queue_async_work_with_qos

将异步工作对象加到队列,由底层根据传入的qos优先级去调度执行。

给ArkTS对象绑定回调和回调所需的参数

接口描述

接口描述
napi_coerce_to_native_binding_object用于给ArkTS对象绑定回调和回调所需的参数,其作用是为了给ArkTS对象携带Native信息。

使用示例

napi_coerce_to_native_binding_object

用于给ArkTS Object绑定回调和回调所需的参数,给ArkTS Object携带Native信息。

cpp部分代码

#include <bits/alltypes.h>
#include <hilog/log.h>
#include <mutex>
#include <unordered_set>
#include <uv.h>
#include "napi/native_api.h"

class Object {
public:
    Object() = default;
    ~Object() = default;

    static Object* GetInstance()
    {
        Object* instance = new Object();
        return instance;
    }

    static napi_value GetAddress(napi_env env, napi_callback_info info)
    {
        napi_value thisVar = nullptr;
        napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr);
        if (thisVar == nullptr) {
            return nullptr;
        }
        void* object = nullptr;
        napi_unwrap(env, thisVar, &object);
        if (object == nullptr) {
            return nullptr;
        }
        uint64_t addressVal = reinterpret_cast<uint64_t>(object);
        napi_value address = nullptr;
        napi_create_bigint_uint64(env, addressVal, &address);
        return address;
    }

    // 获取数组大小
    static napi_value GetSetSize(napi_env env, napi_callback_info info)
    {
        napi_value thisVar = nullptr;
        napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr);
        if (thisVar == nullptr) {
            return nullptr;
        }
        void* object = nullptr;
        napi_unwrap(env, thisVar, &object);
        if (object == nullptr) {
            return nullptr;
        }
        std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_);
        uint32_t setSize = reinterpret_cast<Object*>(object)->numberSet_.size();
        napi_value napiSize = nullptr;
        napi_create_uint32(env, setSize, &napiSize);
        return napiSize;
    }

    // 往数组里插入元素
    static napi_value Store(napi_env env, napi_callback_info info)
    {
        size_t argc = 1;
        napi_value args[1] = {nullptr};
        napi_value thisVar = nullptr;
        napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr);
        if (argc != 1) {
            napi_throw_error(env, nullptr, "Store args number must be one.");
            return nullptr;
        }
        napi_valuetype type = napi_undefined;
        napi_typeof(env, args[0], &type);
        if (type != napi_number) {
            napi_throw_error(env, nullptr, "Store args is not number.");
            return nullptr;
        }
        if (thisVar == nullptr) {
            return nullptr;
        }
        uint32_t value = 0;
        napi_get_value_uint32(env, args[0], &value);
        void* object = nullptr;
        napi_unwrap(env, thisVar, &object);
        if (object == nullptr) {
            return nullptr;
        }
        std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_);
        reinterpret_cast<Object *>(object)-> numberSet_.insert(value);
        return nullptr;
    }

    // 删除数组元素
    static napi_value Erase(napi_env env, napi_callback_info info)
    {
        size_t argc = 1;
        napi_value args[1] = {nullptr};
        napi_value thisVar = nullptr;
        napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr);
        if (argc != 1) {
            napi_throw_error(env, nullptr, "Erase args number must be one.");
            return nullptr;
        }
        napi_valuetype type = napi_undefined;
        napi_typeof(env, args[0], &type);
        if (type != napi_number) {
            napi_throw_error(env, nullptr, "Erase args is not number.");
            return nullptr;
        }
        if (thisVar == nullptr) {
            return nullptr;
        }
        uint32_t value = 0;
        napi_get_value_uint32(env, args[0], &value);
        void* object = nullptr;
        napi_unwrap(env, thisVar, &object);
        if (object == nullptr) {
            return nullptr;
        }
        std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_);
        reinterpret_cast<Object *>(object)->numberSet_.erase(value);
        return nullptr;
    }

    // 清空数组
    static napi_value Clear(napi_env env, napi_callback_info info)
    {
        napi_value thisVar = nullptr;
        napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr);
        if (thisVar == nullptr) {
            return nullptr;
        }
        void* object = nullptr;
        napi_unwrap(env, thisVar, &object);
        if (object == nullptr) {
            return nullptr;
        }
        std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_);
        reinterpret_cast<Object *>(object)->numberSet_.clear();
        return nullptr;
    }

private:
    Object(const Object &) = delete;
    Object &operator=(const Object &) = delete;

    std::unordered_set<uint32_t> numberSet_{};
    std::mutex numberSetMutex_{};
};

void FinializerCallback(napi_env env, void *data, void *hint)
{
    return;
}

// 解绑回调,在序列化时调用,可在对象解绑时执行一些清理操作
void* DetachCallback(napi_env env, void *value, void *hint)
{
    return value;
}

// 绑定回调,在反序列化时调用
napi_value AttachCallback(napi_env env, void* value, void* hint)
{
    napi_value object = nullptr;
    napi_create_object(env, &object);
    napi_property_descriptor desc[] = {
        {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}};
    napi_define_properties(env, object, sizeof(desc) / sizeof(desc[0]), desc);
    // 将JS对象object和native对象value生命周期进行绑定
    napi_status status = napi_wrap(env, object, value, FinializerCallback, nullptr, nullptr);
    if (status != napi_ok) {
        OH_LOG_INFO(LOG_APP, "Node-API attachCallback is failed.");
    }
    // JS对象携带native信息
    napi_coerce_to_native_binding_object(env, object, DetachCallback, AttachCallback, value, hint);
    return object;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    napi_property_descriptor desc[] = {
        {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}};
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    auto object = Object::GetInstance();
    napi_status status = napi_wrap(env, exports, reinterpret_cast<void*>(object), FinializerCallback, nullptr, nullptr);
    if (status != napi_ok) {
        delete object;
    }
    napi_coerce_to_native_binding_object(env, exports, DetachCallback, AttachCallback, reinterpret_cast<void*>(object),
                                         nullptr);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
    napi_module_register(&demoModule);
}

接口声明

// index.d.ts
export const getAddress: () => number;
export const getSetSize: () => number;
export const store: (a: number) => void;
export const erase: (a: number) => void;
export const clear: () => void;

ArkTS侧示例代码

// index.ets
import testNapi from 'libentry.so';
import taskpool from '@ohos.taskpool';

@Concurrent
function getAddress() {
  let address: number = testNapi.getAddress();
  console.info("taskpool:: address is " + address);
}

@Concurrent
function store(a:number, b:number, c:number) {
  let size:number = testNapi.getSetSize();
  console.info("set size is " + size + " before store");
  testNapi.store(a);
  testNapi.store(b);
  testNapi.store(c);
  size = testNapi.getSetSize();
  console.info("set size is " + size + " after store");
}

@Concurrent
function erase(a:number) {
  let size:number = testNapi.getSetSize();
  console.info("set size is " + size + " before erase");
  testNapi.erase(a);
  size = testNapi.getSetSize();
  console.info("set size is " + size + " after erase");
}

@Concurrent
function clear() {
  let size:number = testNapi.getSetSize();
  console.info("set size is " + size + " before clear");
  testNapi.clear();
  size = testNapi.getSetSize();
  console.info("set size is " + size + " after clear");
}

async function test01(): Promise<void> {
    let address:number = testNapi.getAddress();
    console.info("host thread address is " + address);

    let task1 = new taskpool.Task(getAddress);
    await taskpool.execute(task1);

    let task2 = new taskpool.Task(store, 1, 2, 3);
    await taskpool.execute(task2);

    let task3 = new taskpool.Task(store, 4, 5, 6);
    await taskpool.execute(task3);

    let task4 = new taskpool.Task(erase, 3);
    await taskpool.execute(task4);

    let task5 = new taskpool.Task(erase, 5);
    await taskpool.execute(task5);

    let task6 = new taskpool.Task(clear);
    await taskpool.execute(task6);
}

test01();

注意事项

对ArkTS对象A调用napi_coerce_to_native_binding_object将开发者实现的detach/attach回调和native对象信息加到A上,再将A跨线程传递。跨线程传递需要对A进行序列化和反序列化,在当前线程thread1序列化A得到数据data,序列化阶段执行detach回调。然后将data传给目标线程thread2,在thread2中反序列化data,执行attach回调,最终得到ArkTS对象A。

事件循环

接口描述

接口描述
napi_run_event_loop触发底层的事件循环。
napi_stop_event_loop停止底层的事件循环。

使用示例

napi_run_event_loop、napi_stop_event_loop

使用扩展的Node-API接口在异步线程中运行和停止事件循环

ArkTS基础运行时环境

接口描述

接口描述
napi_create_ark_runtime创建基础运行时环境。
napi_destroy_ark_runtime销毁基础运行时环境。

使用示例

napi_create_ark_runtime、napi_destroy_ark_runtime

使用Node-API接口创建ArkTS运行时环境

序列化和反序列化

接口描述

接口描述
napi_serialize将ArkTS对象转换为native数据。第一个参数env是接口执行的ArkTS环境;第二个参数object是待序列化的ArkTS对象;第三个参数transfer_list是存放需要以transfer传递的arrayBuffer的array,如不涉及可传undefined;第四个参数clone_list是存放需要克隆传递的Sendable对象的array,如不涉及可传undefined;第五个参数result是序列化结果。
napi_deserialize将native数据转为ArkTS对象。第一个参数env是接口执行的ArkTS环境;第二个参数buffer是序列化数据;第三个参数object是反序列化得到的结果。
napi_delete_serialization_data删除序列化数据。

使用示例

napi_serialize、napi_deserialize、napi_delete_serialization_data

用于将ArkTS对象转换为native数据、将native数据转为ArkTS对象、删除序列化数据等操作。

cpp部分代码

#include "napi/native_api.h"

static napi_value AboutSerialize(napi_env env, napi_callback_info info)
{
    // 获取传入的ts的一个对象作为参数
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
    napi_value undefined = nullptr;
    // 构造napi_serialize方法所需参数
    napi_get_undefined(env, &undefined);
    void *data = nullptr;
    // 调用napi_serialize方法将ts对象转化为native数据
    napi_status status = napi_serialize(env, args[0], undefined, undefined, &data);
    if (status != napi_ok ||data == nullptr) {
        napi_throw_error(env, nullptr, "Node-API napi_serialize fail");
        return nullptr;
    }
    // 构造napi_value类型的数据,用于接收将native数据转化为ts对象后的数据
    napi_value result = nullptr;
    napi_deserialize(env, data, &result);
    napi_value number = nullptr;
    // 获取native数据转化为ts对象后的数据中的numKey属性的值
    napi_get_named_property(env, result, "numKey", &number);
    // 判断获取到的属性值是否为number类型
    napi_valuetype valuetype;
    napi_typeof(env, number, &valuetype);
    if (valuetype != napi_number) {
        napi_throw_error(env, nullptr, "Node-API Wrong type of argument. Expects a number.");
        return nullptr;
    }
    // 调用napi_delete_serialization_data方法删除序列化数据
    napi_delete_serialization_data(env, data);
    // 返回获取到的属性值
    return number;
}

接口声明

// index.d.ts
export const aboutSerialize: (obj: Object) => number;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'
class Obj {
  numKey:number = 0;
}
let obj: Obj = { numKey: 500 };
hilog.info(0x0000, 'testTag', ' Node-API aboutSerialize: %{public}d', testNapi.aboutSerialize(obj));

根据任务指定的优先级和入队方式进行处理异步线程向ArkTS线程投递的任务

接口描述

接口描述
napi_call_threadsafe_function_with_priority将指定优先级和入队方式的任务投递到ArkTS主线程。

使用示例

napi_call_threadsafe_function_with_priority

使用Node-API接口从异步线程向ArkTS线程投递指定优先级和入队方式的的任务

Sendable相关

接口描述

接口描述
napi_is_sendable判断给定ArkTS value是否是Sendable的。
napi_define_sendable_class创建一个sendable类。
napi_create_sendable_object_with_properties使用给定的napi_property_descriptor创建一个sendable对象。
napi_create_sendable_array创建一个sendable数组。
napi_create_sendable_array_with_length创建一个指定长度的sendable数组。
napi_create_sendable_arraybuffer创建一个sendable ArrayBuffer。
napi_create_sendable_typedarray创建一个sendable TypedArray。
napi_wrap_sendable包裹一个native实例到ArkTS对象中。
napi_wrap_sendable_with_size包裹一个native实例到ArkTS对象中并指定大小。
napi_unwrap_sendable获取ArkTS对象包裹的native实例。
napi_remove_wrap_sendable移除并获取ArkTS对象包裹的native实例。

使用示例

napi_is_sendable

判断给定ArkTS value是否是Sendable的。

cpp部分代码

#include "napi/native_api.h"

static napi_value IsSendable(napi_env env, napi_callback_info info) {
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
    bool isSendable = false;
    napi_is_sendable(env, args[0], &isSendable);
    napi_value result;
    napi_get_boolean(env, isSendable, &result);
    return result;
}

接口声明

// index.d.ts
export const isSendable: <T>(a: T) => boolean;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.isSendable('createObject');
hilog.info(0x0000, 'testTag', 'Node-API napi_is_sendable: %{public}s', JSON.stringify(value));

napi_define_sendable_class

创建一个sendable类。

cpp部分代码

#include "napi/native_api.h"

static napi_value func(napi_env env, napi_callback_info info) {
    napi_value val;
    napi_create_string_utf8(env, "func result", NAPI_AUTO_LENGTH, &val);
    return val;
}

static napi_value DefineSendableClass(napi_env env) {
    napi_value str;
    napi_create_string_utf8(env, "str", NAPI_AUTO_LENGTH, &str);

    napi_property_descriptor props[] = {
        {"staticStr", nullptr, nullptr, nullptr, nullptr, str,
         static_cast<napi_property_attributes>(napi_static | napi_writable), nullptr},
        {"staticFunc", nullptr, func, nullptr, nullptr, nullptr, napi_static, nullptr},
        {"str", nullptr, nullptr, nullptr, nullptr, str, static_cast<napi_property_attributes>(1 << 9 | napi_writable),
         nullptr},
        {"func", nullptr, nullptr, nullptr, nullptr, nullptr,
         static_cast<napi_property_attributes>(1 << 11 | napi_writable), nullptr},
    };

    napi_value sendableClass = nullptr;
    napi_define_sendable_class(
        env, "SendableClass", NAPI_AUTO_LENGTH,
        [](napi_env env, napi_callback_info info) -> napi_value {
            napi_value thisVar = nullptr;
            napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr);
            napi_value str;
            napi_create_string_utf8(env, "instance str", NAPI_AUTO_LENGTH, &str);
            napi_property_descriptor props[] = {
                {"str", nullptr, nullptr, nullptr, nullptr, str, napi_default, nullptr},
                {"func", nullptr, func, nullptr, nullptr, nullptr, napi_default, nullptr},
            };
            napi_define_properties(env, thisVar, sizeof(props) / sizeof(props[0]), props);
            return thisVar;
        },
        nullptr, sizeof(props) / sizeof(props[0]), props, nullptr, &sendableClass);

    return sendableClass;
}

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
    napi_property_descriptor desc[] = {};
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    napi_value cons = DefineSendableClass(env);
    napi_set_named_property(env, exports, "SendableClass", cons);
    return exports;
}
EXTERN_C_END

static napi_module demoModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
    napi_module_register(&demoModule);
}

接口声明

// index.d.ts
@Sendable
export class SendableClass {
  static staticStr: string;
  static staticFunc(): string;
  str: string;
  func(): string;
}

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = new testNapi.SendableClass();
hilog.info(0x0000, 'testTag', 'Node-API napi_define_sendable_class: %{public}s', value.str);

napi_create_sendable_object_with_properties

使用给定的napi_property_descriptor创建一个sendable对象。

cpp部分代码

#include "napi/native_api.h"

static napi_value GetSendableObject(napi_env env, napi_callback_info info) {
    napi_value val_true;
    napi_get_boolean(env, true, &val_true);
    napi_property_descriptor desc1[] = {
        {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr},
    };
    napi_value obj;
    napi_create_sendable_object_with_properties(env, 1, desc1, &obj);
    return obj;
}

接口声明

// index.d.ts
export const getSendableObject: () => { x: true };

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.getSendableObject();
hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_object_with_properties: %{public}s', JSON.stringify(value));

napi_create_sendable_array

创建一个sendable数组。

cpp部分代码

#include "napi/native_api.h"

static napi_value GetSendableArray(napi_env env, napi_callback_info info) {
    napi_value result = nullptr;
    napi_create_sendable_array(env, &result);
    return result;
}

接口声明

// index.d.ts
export const getSendableArray: () => [];

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.getSendableArray();
hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array: %{public}s', JSON.stringify(value));

napi_create_sendable_array_with_length

创建一个指定长度的sendable数组。

cpp部分代码

static napi_value GetSendableArrayWithLength(napi_env env, napi_callback_info info) {
    napi_value result = nullptr;
    napi_create_sendable_array_with_length(env, 1, &result);
    return result;
}

接口声明

// index.d.ts
export const getSendableArrayWithLength: () => [];

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

let value = testNapi.getSendableArrayWithLength();
hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array_with_length: %{public}s', JSON.stringify(value.length));

napi_create_sendable_arraybuffer

创建一个sendable ArrayBuffer。

cpp部分代码

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

static napi_value GetSendableArrayBuffer(napi_env env, napi_callback_info info) {
    static size_t LENGTH = 1024;
    void *data;
    napi_value result = nullptr;
    napi_create_sendable_arraybuffer(env, LENGTH, &data, &result);
    bool isArrayBuffer = false;
    napi_is_arraybuffer(env, result, &isArrayBuffer);
    OH_LOG_INFO(LOG_APP, "isArrayBuffer: %{public}d", isArrayBuffer);
    return result;
}

接口声明

// index.d.ts
export const getSendableArrayBuffer: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.getSendableArrayBuffer();

napi_create_sendable_typedarray

创建一个sendable TypedArray。

cpp部分代码

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

static napi_value GetSendableTypedArray(napi_env env, napi_callback_info info) {
    static size_t LENGTH = 1024;
    static size_t OFFSET = 0;
    void *data;
    napi_value arraybuffer = nullptr;
    napi_create_sendable_arraybuffer(env, LENGTH, &data, &arraybuffer);

    napi_value result = nullptr;
    napi_create_sendable_typedarray(env, napi_uint8_array, LENGTH, arraybuffer, OFFSET, &result);
    bool isTypedArray = false;
    napi_is_typedarray(env, result, &isTypedArray);
    OH_LOG_INFO(LOG_APP, "isTypedArray: %{public}d", isTypedArray);
    return result;
}

接口声明

// index.d.ts
export const getSendableTypedArray: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.getSendableTypedArray();

napi_wrap_sendable

包裹一个native实例到ArkTS对象中。

cpp部分代码

#include "napi/native_api.h"

static napi_value WrapSendable(napi_env env, napi_callback_info info) {
    napi_value val_true;
    napi_get_boolean(env, true, &val_true);
    napi_property_descriptor desc1[] = {
        {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr},
    };
    napi_value obj;
    napi_create_sendable_object_with_properties(env, 1, desc1, &obj);

    const char* testStr = "test";
    napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr);

    return nullptr;
}

接口声明

// index.d.ts
export const wrapSendable: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.wrapSendable();

napi_wrap_sendable_with_size

包裹一个native实例到ArkTS对象中并指定大小。

cpp部分代码

#include "napi/native_api.h"

static napi_value WrapSendableWithSize(napi_env env, napi_callback_info info) {
    napi_value val_true;
    napi_get_boolean(env, true, &val_true);
    napi_property_descriptor desc1[] = {
        {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr},
    };
    napi_value obj;
    napi_create_sendable_object_with_properties(env, 1, desc1, &obj);

    const char* testStr = "test";
    napi_wrap_sendable_with_size(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr, 100);

    return nullptr;
}

接口声明

// index.d.ts
export const wrapSendableWithSize: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.wrapSendableWithSize();

napi_unwrap_sendable

获取ArkTS对象包裹的native实例。

cpp部分代码

#include "napi/native_api.h"

static napi_value UnwrapSendable(napi_env env, napi_callback_info info) {
    napi_value val_true;
    napi_get_boolean(env, true, &val_true);
    napi_property_descriptor desc1[] = {
        {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr},
    };
    napi_value obj;
    napi_create_sendable_object_with_properties(env, 1, desc1, &obj);

    const char* testStr = "test";
    napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr);

    char* tmpTestStr = nullptr;
    napi_unwrap_sendable(env, obj, (void**)&tmpTestStr);
    OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr);

    return nullptr;
}

接口声明

// index.d.ts
export const unwrapSendable: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.unwrapSendable();

napi_remove_wrap_sendable

移除并获取ArkTS对象包裹的native实例。

cpp部分代码

#include "napi/native_api.h"

static napi_value RemoveWrapSendable(napi_env env, napi_callback_info info) {
    napi_value val_true;
    napi_get_boolean(env, true, &val_true);
    napi_property_descriptor desc1[] = {
        {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr},
    };
    napi_value obj;
    napi_create_sendable_object_with_properties(env, 1, desc1, &obj);

    const char* testStr = "test";
    napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr);

    char* tmpTestStr = nullptr;
    napi_remove_wrap_sendable(env, obj, (void**)&tmpTestStr);
    OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr);

    return nullptr;
}

接口声明

// index.d.ts
export const removeWrapSendable: () => void;

ArkTS侧示例代码

import hilog from '@ohos.hilog'
import testNapi from 'libentry.so'

testNapi.removeWrapSendable();

以上代码如果要在native cpp中打印日志,需在CMakeLists.txt文件中添加以下配置信息(并添加头文件:#include "hilog/log.h"):

// CMakeLists.txt
add_definitions( "-DLOG_DOMAIN=0xd0d0" )
add_definitions( "-DLOG_TAG=\"testTag\"" )
target_link_libraries(entry PUBLIC libhilog_ndk.z.so)

鸿蒙HarmonyOS应用开发之使用DevEco Studio模板构建NDK工程 在很多复杂应用工程中,C++代码工程是通过CMake等构建系统以命令行方式来编译构建的,接下来介绍如何把已有的CMake工程切换到OpenHarmony工具链中,从而使用命令行CMake构建该工程。 阅读详情

相关推荐

鸿蒙HarmonyOS应用开发之NDK开发指南

build目录:放置预定义的toolchain脚本文件ohos.toolchain.cmakeCMake编译时需要读取该文件中的默认值,比如编译器架构、C++库链接方式等,因此在编译时会通过CMAKE_TOOLCHAIN_FILE指出该文件的路径,便于CMake在编译时定位到该文件。build-tools文件夹:放置NDK提供的编译工具# 键入下一行命令查看CMake的版本# 结果llvm文件夹:放置NDK提供的编译器。

YHDMYBY的博客 1939

鸿蒙NDK开发入门

一、NDK简介   NDK(Native Development Kit)是鸿蒙提供的Native API、编译脚本和编译工具链的集合,方便开发者使用C/C++实现应用的关键功能。一般情况下应用开发使用ArkTS,ArkTS已经能满足大部分的功能开发,但有些功能还是需要用C/C++来实现,像音视频、直播、美颜、地图、AI等...

weixin_36348900的博客 881

鸿蒙HarmonyOS开发(5.0 Beta)NDK接口构建UI界面实践

NDK提供的UI组件能力如组件创建、树操作、属性设置、事件注册等是通过函数指针结构体(如ArkUI_NativeNodeAPI_1)进行暴露,该函数指针结构体可以通过模块查询接口获取。

yguyf1235的博客 1013

鸿蒙5.0开发进阶:NDK代码开发-Node-API使用指南(使用Node-API接口进行ArrayBuffer相关开发)

ArrayBuffer是ArkTS中的一种数据类型,用于表示通用的、固定长度的原始二进制数据缓冲区。

Androidbye的博客 1073

Windows电脑如何用MobaXterm连接宇树G1机器人?保姆级SSH配置指南

本文提供了一份详细的保姆级教程,指导Windows用户使用MobaXterm通过SSH连接宇树G1机器人。内容涵盖从物理网络配置、MobaXterm安装与SSH会话创建,到文件传输、X11转发等高级功能,并包含常见问题排查与安全加固建议,帮助开发者快速建立稳定可靠的远程开发连接。

purple的博客 878

手把手教你用GNU Radio和PlutoSDR搭建FM收音机(附完整流程图)

本文提供了一份详细的实践指南,教你如何使用GNU Radio和PlutoSDR搭建一个功能完整的FM收音机。从软硬件环境准备、核心流程图构建,到运行调试与效果优化,手把手带你完成从射频信号接收、下变频、FM解调到音频输出的全过程,是入门软件定义无线电(SDR)的绝佳实践项目。

weixin_29189377的博客 754

鸿蒙NDK开发实战指南:从ArkTS到C/C++的高性能桥梁

HarmonyOS NDK(Native Development Kit)是HarmonyOS SDK中提供的Native API、编译脚本和编译工具链的集合,它让开发者能够使用C或C++语言实现应用的关键功能模块。NDK主要覆盖了HarmonyOS的基础底层能力,包括C运行时基础库libc、图形库、窗口系统、多媒体、压缩库以及实现ArkTS/JS与C跨语言调用的Node-API等。NDK的核心价值在于它为性能敏感型应用提供了原生性能优势。

猫林老师 - 致力优质教程编写 2780

OpenCL编译环境配置

在 Linux 系统上配置 OpenCL 开发环境需要安装适当的驱动、运行时和开发工具。

深之JohnChen的专栏 2005

鸿蒙5.0开发进阶:NDK开发-使用Node-API扩展能力接口

本文仅对接口对应C++及ArkTS相关代码进行展示。

Androidbye的博客 965

Honeywell EPKS 核心功能块组态与执行调度实战解析

本文深入解析Honeywell EPKS系统的核心功能块组态与执行调度技术,涵盖控制模块(CM)、顺序控制模块(SCM)和输入输出模块(IOM)的配置方法。通过实战案例分享执行顺序(ORDERINCM)和CEE执行周期的优化策略,帮助工程师提升工业自动化系统的控制精度和运行效率。

weixin_28724319的博客 414

从无人机到机械臂:深入聊聊LQR和LQG在实际项目里的那些‘坑’与最佳实践

本文深入探讨了LQR和LQG在无人机和机械臂等实际项目中的应用挑战与最佳实践。从系统建模的妥协艺术到调参的系统化方法,再到离散化的细节处理,文章分享了工程实践中的宝贵经验。特别强调了如何应对传感器噪声、未建模动态等现实问题,并提供了实用的调试工具和诊断流程,帮助工程师避免常见陷阱,提升控制系统的稳定性和性能。

weixin_28683391的博客 387

鸿蒙5.0&next开发【使用Node-API扩展能力接口】NDK开发

[扩展能力]接口进一步扩展了Node-API的功能,提供了一些额外的接口,用于在Node-API模块中与ArkTS进行更灵活的交互和定制,这些接口可以用于创建自定义ArkTS对象等场景。

bbq的博客 1052

级联H桥构网型储能SVG系统设计与VSG控制策略研究

随着新能源渗透率不断提高,电力系统惯量和阻尼水平持续下降,传统跟网型控制策略在弱电网条件下的稳定性面临严峻挑战。构网型控制以电压源方式运行,能够为系统提供惯量和频率支撑,成为当前研究热点。本文针对10kV/10Mvar级联H桥构网型储能静止无功发生器(SVG),采用星形连接拓扑结构,设计了基于虚拟同步发电机(VSG)的构网型控制策略。文章从主电路拓扑设计、数学建模、VSG控制策略设计、调制策略、直流电压平衡控制、系统参数设计、仿真建模和硬件实现等八个方面展开系统论述,给出了完整的Simulink仿真模型~~

huanghm88的专栏 356

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口进行ArrayBuffer相关开发

本文仅对接口对应C++及ArkTS相关代码进行展示。

Androidbye的博客 1202

MVSNet (pytorch版) 搭建环境 运行dtu数据集重建 实操教程(图文并茂、超详细)

MVSNet (pytorch版) 代码注释版 下载 (注释非常详细,代码结构有所调整,使用起来更方便) 深度学习三维重建 MVSNet-ECCV-2018 (源码、pytorch版、原文+注释、译文+批注)Meshlab查看三维点云时 ,使用技巧总结。

程序员,他们想的是什么?他们想的永远都是技术,他们崇尚的也永远都是技术。 2938

linux系统下XDMA驱动的安装与测试问题总结

先看两个常见的问题。一个是驱动安装问题,一个是驱动测试错误;error 512 能识别PCIE的设备,但是The kernel modle installed correctly, but no devices were recognized.

whm128的博客 3810

鸿蒙5.0开发进阶:NDK代码开发-Node-API使用指南(使用Node-API接口进行primitive类相关开发)

在使用Node-API接口时.........

Androidbye的博客 1241

迈瑞BS系列全自动生化分析仪LIS协议接口手册(内含HL7和ASTM)

迈瑞BS系列全自动生化分析仪LIS协议接口手册,内含HL7和ASTM)

HarmonyOS中调用C/C++代码(NDK)的准备知识

HarmonyOS NDK开发指南摘要:NDK(Native Development Kit)是HarmonyOS提供的原生开发工具集,支持使用C/C++实现关键功能。它包含基础库(如libc、图形库)、跨语言Node-API接口等,适用于高性能计算、已有C/C++库复用等场景,但不推荐用于纯原生开发或需广泛兼容的应用。开发者需掌握Linux C编程、CMake构建、Node-API等知识,NDK目录包含预定义编译脚本和工具链。该工具链支持通过Clang/LLVM优化动态库编译,帮助开发者在游戏、物理模拟等

尽吾所能 分享永久免费知识 2589

文档:亲测可用解决vnc灰屏,黑屏,鼠标大黑叉情况

主要解决vnc-viewer灰屏,黑屏,鼠标大黑叉等现象,详细见文档。

SAP B1中文培訓教材_SDK

公司内部培训资料,对开发工具 ,DIAPI, UIAPI,Add-ON有详细解说

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口进行array相关开发

使用Node-API接口进行数组(array)相关开发时,涉及的基本概念主要包括数组的创建、访问、修改、遍历以及与数组相关的操作。

Androidbye的博客 1384

jdk-8u144-linux-x64.tar.gz.

该资源为搭建Linux系统Java环境用,资源的后缀为tar.gz格式的压缩包

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口处理异步操作

使用Node-API接口处理异步操作。

Androidbye的博客 716

鸿蒙(API 12 Beta2版)NDK开发【使用Node-API扩展能力接口】

[扩展能力接口]进一步扩展了Node-API的功能,提供了一些额外的接口,用于在Node-API模块中与ArkTS进行更灵活的交互和定制,这些接口可以用于创建自定义ArkTS对象等场景。

鸿蒙的技术博客 1326

鸿蒙5.0开发进阶:NDK开发-Node-API支持的数据类型和接口

是一个枚举数据类型,表示Node-API接口返回的状态信息

Androidbye的博客 1035

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口进行模块加载

Node-API中的napi_load_module_with_info接口的功能是进行模块的加载.....

Androidbye的博客 761

鸿蒙5.0开发进阶:NDK代码开发-Node-API使用指南(使用Node-API接口操作bigint类型值)

BigInt是ArkTS中用于表示任意精度整数的数据类型...........

Androidbye的博客 1132

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口操作bigint类型值

BigInt是ArkTS中用于表示任意精度整数的数据类型,它能够处理比Number类型更大范围的整数值。

Androidbye的博客 937

鸿蒙5.0开发进阶:NDK开发-使用Node-API接口进行生命周期相关开发

napi_value的生命周期与其在ArkTS中的对应值的生命周期紧密相关。

Androidbye的博客 995
上一篇: 鸿蒙5.0开发进阶:NDK代码开发-使用Node-API实现跨语言交互(使用Node-API实现跨语言交互开发流程)
下一篇: 鸿蒙5.0开发进阶:NDK代码开发-Node-API使用指南(使用Node-API接口进行array相关开发)
懂你的大海
博客等级 码龄6年 9049粉丝 1381原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值