鸿蒙（HarmonyOS）应用开发之Node-API支持的数据类型和接口

Node-API的数据类型

napi_status

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

每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。

typedef enum {
    napi_ok,
    napi_invalid_arg,
    napi_object_expected,
    napi_string_expected,
    napi_name_expected,
    napi_function_expected,
    napi_number_expected,
    napi_boolean_expected,
    napi_array_expected,
    napi_generic_failure,
    napi_pending_exception,
    napi_cancelled,
    napi_escape_called_twice,
    napi_handle_scope_mismatch,
    napi_callback_scope_mismatch,
    napi_queue_full,
    napi_closing,
    napi_bigint_expected,
    napi_date_expected,
    napi_arraybuffer_expected,
    napi_detachable_arraybuffer_expected,
    napi_would_deadlock, /* unused */
    napi_no_external_buffers_allowed,
    napi_cannot_run_js
} napi_status;

napi_extended_error_info

一个结构体，在调用函数不成功时存储了较为详细的错误信息。

typedef struct {
    const char *error_message;
    void *engine_reserved;
    uint32_t engine_error_code;
    napi_status error_code;
} napi_extended_error_info;

napi_value

在C++代码中，表示一个JavaScript值。

napi_env

• 用于表示Node-API执行时的上下文，Native侧函数入参，并传递给函数中的Node-API接口。

• 退出Native侧插件时，napi_env将失效，该事件通过回调传递给napi_add_env_cleanup_hook和napi_set_instance_data。

• 禁止缓存napi_env，禁止在不同Worker中传递napi_env。

napi_threadsafe_function

napi_threadsafe_function用来创建一个线程安全的JavaScript函数，可以在不同的线程中调用。可以用于将异步操作的结果传递给JavaScript环境，例如从另一个线程中读取数据或执行计算密集型操作。此外，它还可以用于从JavaScript环境中调用C++代码中的函数，以便在另一个线程中执行。通过使用napi_threadsafe_function，可以实现JavaScript和C++之间的高效通信，同时保持线程安全性。

napi_threadsafe_function_release_mode

该枚举类型定义了两个常量，用于指定在何时释放线程安全函数的回调函数。

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

该值会传给napi_release_threadsafe_function。

napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• mode值为napi_tsfn_release时：表示当前线程不再调用此tsfn。

• mode值为napi_tsfn_abort时：表示除了当前线程，其他线程不能再调用此tsfn。 如果设置为napi_tsfn_abort，利用napi_call_threadsafe_function接口调用此tsfn时将返回napi_closing，tsfn函数并不会被放入queue中。

napi_threadsafe_function_call_mode

该枚举类型定义了两个常量，用于指定线程安全函数的调用模式。

数据结构如下所示：

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

• napi_tsfn_nonblocking：napi_call_threadsafe_function是非阻塞的，如果队列已满，则返回napi_queue_full，从而阻止数据添加到队列中。

• napi_tsfn_blocking：napi_call_threadsafe_function是阻塞的，直至队列中有空间可用。

内存管理类型

Node-API包含以下内存管理类型：

napi_handle_scope

napi_handle_scope数据类型是用来管理JavaScript对象的生命周期的。它允许JavaScript对象在一定范围内保持活动状态，以便在JavaScript代码中使用。在创建napi_handle_scope时，所有在该范围内创建的JavaScript对象都会保持活动状态，直到结束。这样可以避免在JavaScript代码中使用已经被释放的对象，从而提高代码的可靠性和性能。

napi_escapable_handle_scope

• 由napi_open_escapable_handle_scope接口创建，由napi_close_escapable_handle_scope接口关闭。

• 表示一种特殊类型的句柄范围，用于将在escapable_handle_scope范围内创建的值返回给父scope。

• 用于napi_escape_handle接口，将escape_handle_scope提升到JS对象，以便在外部作用域使用。

napi_ref

指向napi_value，允许用户管理JavaScript值的生命周期。

napi_type_tag

该结构体定义了一个包含两个无符号64位整数的类型标签，用于标识一个Node-API值的类型信息。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;

• 存储了两个无符号64位整数的128位值，用它来标记JavaScript对象，确保它们属于某种类型。

• 比napi_instanceof更强的类型检查，如果对象的原型被操纵，napi_instanceof可能会报告误报。

• type_tag与napi_wrap结合非常有用，因为它确保从包装对象检索的指针可以安全地转换为与先前应用于JavaScript对象的类型标记相对应的Native类型。

napi_async_cleanup_hook_handle

napi_async_cleanup_hook_handle用于注册异步操作的回调函数。它主要用于在异步操作完成或被取消时执行清理操作，例如释放资源或撤销操作。使用napi_async_cleanup_hook_handle可以确保在异步操作完成或被取消时，相关资源得到正确的释放和清理，从而避免内存泄漏等问题。

回调类型

Node-API包含以下回调类型：

napi_callback_info

Native侧获取JS侧参数信息，传递给napi_get_cb_info，用于获取JS侧入参信息。

napi_callback

表示用户定义的Native函数，暴露给JavaScript，即JS侧调用的接口；一般不在此callback中创建handle或者callback scope。

基本用法如下：

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);

napi_finalize

函数指针，用于传入napi_create_threadsafe_function和napi_set_instan