Node-API Data Types and APIs

Data Types

napi_status

Enum indicating the execution status of a Node-API call.

Each time a Node-API function is called, a value of napi_status is returned indicating the execution result.

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

Struct that holds detailed error information when a Node-API call fails.

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

napi_value

A C struct pointer acting as a reference to a JS object. A napi_value holds a JS object. handle_scope is used to manage the lifetime of napi_value handles. The JS object held by a napi_value in the scope will not be released. If the napi_value is out of the scope, it becomes invalid and will no longer hold the JS object.

napi_env

• Context used by the underlying Node-API implementation. It is passed to the native functions when they are invoked, and must be passed back when Node-API calls are made.

• napi_env becomes invalid when the JS thread bound with napi_env exits.

• Avoid caching napi_env or passing napi_env between instances of the same addon running on different worker threads.

napi_threadsafe_function

Pointer that represents a JS function that can be called asynchronously from multiple threads. It can be used to pass the asynchronous (async for short) operation result to the JS environment, such as reading data from another thread or performing compute-intensive operations. In addition, it can be used to call functions in C++ code from a JS environment for execution in another thread. By using napi_threadsafe_function, you can implement efficient interaction between JS and C++ code while maintaining thread safety.

napi_threadsafe_function_release_mode

Enum that indicates when to release the thread-safe function.

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;

Its value is passed to napi_release_threadsafe_function.

napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);

• If the value is napi_tsfn_release, the current thread will not call this thread-safe function.

• If the value is napi_tsfn_abort, this thread-safe function is disabled and cannot be called. In this case, using napi_call_threadsafe_function to call this function will return napi_closing, and this function will not be placed in the queue.

napi_threadsafe_function_call_mode

Enum that indicates whether the call should be blocked when the queue associated with the thread-safe function is full.

The data struct is as follows:

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;

• napi_tsfn_nonblocking: Leave napi_call_threadsafe_function unblocked. If the queue is full, napi_queue_full is returned to prevent data from being added to the queue.

• napi_tsfn_blocking: Block napi_call_threadsafe_function until there is available space in the queue.

Memory Management Types

Node-API provides the following memory management types:

napi_handle_scope

Data used to manage the lifecycle of JS objects. It allows JS objects to remain active within a certain range for use in JS code. When napi_handle_scope is created, all JS objects created in this range remain active until the end. This minimizes their lifecycles and prevents memory leaks. For details about napi_handle_scope, see Precautions for Lifecycle Issues.

napi_escapable_handle_scope

• It is created by napi_open_escapable_handle_scope and closed by napi_close_escapable_handle_scope.

• It is a special type of handle range used to return values created within the scope of escapable_handle_scope to a parent scope.

• You can use napi_escape_handle to promote escape_handle_scope to a JS object so that it is valid for the lifetime of the outer scope.

napi_ref

Reference to napi_value, which allows you to manage the lifecycle of JS values.

napi_type_tag

Struct containing two unsigned 64-bit integers to identify the type of a Node-API value.

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

• It is a 128-bit value stored as two unsigned 64-bit integers. It is used to tag JS objects to ensure that they are of a certain type.

• This is a stronger check than napi_instanceof because napi_instanceof may report a false positive if the object’s prototype is manipulated.

• The combination of type_tag and napi_wrap is useful because it ensures that the pointer retrieved from a wrapped object can be safely converted to the native type corresponding to the type tag that had been previously applied to the JS object.

napi_async_cleanup_hook_handle

Value used to add a callback for an async operation. It is mainly used to perform a cleanup operation when an async operation is complete or canceled, for example, releasing a resource or canceling an operation. Using napi_async_cleanup_hook_handle ensures that related resources are correctly released and cleaned up when an async operation is complete or canceled, thereby avoiding problems such as memory leaks.

Callback Types

Node-API provides the following callback types:

napi_callback_info

Data type passed to napi_get_cb_info to obtain JS input parameters.

napi_callback

User-defined native function, which is exposed to JS via Node-API. Generally, no handle or callback scope is created inside this callback.

The basic usage is as follows:

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

napi_finalize

Function pointer passed to napi_create_threadsafe_function and napi_set_instance_data. napi_finalize is called when an object is reclaimed.

napi_async_execute_callback

Function pointer used in napi_create_async_work.

• An async native function is called from a worker pool thread and can be executed in parallel with the main event loop thread.

• Avoid making Node-API calls that execute JS code or interact with JS objects when implementing this callback.

• Node-API calls should be executed in napi_async_complete_callback.

napi_async_complete_callback

Function pointer used when an async operation is complete. When an async operation is required, you can use napi_create_async_work to create an async work and specify napi_async_complete_callback. When the async work is complete, the callback will be automatically invoked for subsequent processing. Parameters of the callback include the status of the async operation and a return value, based on which corresponding processing can be performed.

napi_threadsafe_function_call_js

Function pointer used in the main thread to interact with the JS code in an independent thread to implement more complex scenarios. It is used in napi_create_threadsafe_function(napi_env env, …, napi_threadsafe_function_call_js call_js_cb, …).

napi_cleanup_hook

Function pointer used with napi_add_env_cleanup_hook. It will be called when the environment is destroyed.

napi_async_cleanup_hook

Function pointer used with napi_add_async_cleanup_hook. It will be called when the environment is destroyed.

QoS

Enum indicating the thread scheduling priority.

typedef enum {
  napi_qos_background = 0,
  napi_qos_utility = 1,
  napi_qos_default = 2,
  napi_qos_user_initiated = 3,
} napi_qos_t;

Event Loop Modes

Node-API provides two modes for running the underlying event loop. The two modes are defined as follows:

typedef enum {
    napi_event_mode_default = 0,
    napi_event_mode_nowait = 1,
} napi_event_mode;

Thread-safe Task Priority

Node-API defines the priorities of thread-safe tasks, as listed below. The tasks in the underlying task queue are executed in sequence based on their priorities.

typedef enum {
    napi_priority_immediate = 0,
    napi_priority_high = 1,
    napi_priority_low = 2,
    napi_priority_idle = 3,
} napi_task_priority;

APIs

Node-API is extended based on the native modules provided by Node.js. The following lists the APIs supported currently.

Async Thread-Safe APIs

Buffer

String

Date

ArrayBuffer

Module

Lifecycle Management

Promise

Array

Primitives

Class

Object

Basic Data Types

BigInt

Exceptions and Errors

Property

Async Works

Custom Async Operations

UV

Function Invocation

Environment Lifecycle

Object Lifetime Management

Extended Capabilities

Node-API Extended Symbols

napi_queue_async_work_with_qos

napi_status napi_queue_async_work_with_qos(napi_env env,
                                           napi_async_work work,
                                           napi_qos_t qos);

This API has the same usage as napi_queue_async_work. The difference is you can specify the QoS for the work to run. For details about how to use napi_queue_async_work_with_qos, see “Prioritizing Asynchronous Tasks”. For details about QoS, see QoS Development.

napi_run_script_path

napi_status napi_run_script_path(napi_env env,
                                 const char* abcPath,
                                 napi_value* result);

napi_load_module

napi_status napi_load_module(napi_env env,
                             const char* path,
                             napi_value* result);

napi_create_object_with_properties

napi_status napi_create_object_with_properties(napi_env env,
                                               napi_value* result,
                                               size_t property_count,
                                               const napi_property_descriptor* properties);

napi_create_object_with_named_properties

napi_status napi_create_object_with_named_properties(napi_env env,
                                                     napi_value* result,
                                                     size_t property_count,
                                                     const char** keys,
                                                     const napi_value* values);

napi_coerce_to_native_binding_object

napi_status napi_coerce_to_native_binding_object(napi_env env,
                                                 napi_value js_object,
                                                 napi_native_binding_detach_callback detach_cb,
                                                 napi_native_binding_attach_callback attach_cb,
                                                 void* native_object,
                                                 void* hint);

napi_create_ark_runtime

napi_status napi_create_ark_runtime(napi_env *env);

Creating an ArkTS Runtime Environment Using napi_create_ark_runtime and napi_destroy_ark_runtime

napi_destroy_ark_runtime

napi_status napi_destroy_ark_runtime(napi_env *env);

napi_run_event_loop

napi_status napi_run_event_loop(napi_env env, napi_event_mode mode);

You can call the napi_run_event_loop and napi_stop_event_loop APIs only in the ArkTS runtime environment created using napi_create_ark_runtime. For details, see Running or Stopping an Event Loop in an Asynchronous Thread Using Node-API Extension APIs.

napi_stop_event_loop

napi_status napi_stop_event_loop(napi_env env);

napi_serialize

napi_status napi_serialize(napi_env env,
                           napi_value object,
                           napi_value transfer_list,
                           napi_value clone_list,
                           void** result);

napi_deserialize

napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object);

napi_delete_serialization_data

napi_status napi_delete_serialization_data(napi_env env, void* buffer);

napi_call_threadsafe_function_with_priority

napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func,
                                                        void *data,
                                                        napi_task_priority priority,
                                                        bool isTail);

napi_is_sendable

napi_status napi_is_sendable(napi_env env, napi_value value, bool* result);

napi_define_sendable_class

napi_status napi_define_sendable_class(napi_env env,
                                       const char* utf8name,
                                       size_t length,
                                       napi_callback constructor,
                                       void* data,
                                       size_t property_count,
                                       const napi_property_descriptor* properties,
                                       napi_value parent,
                                       napi_value* result);

napi_create_sendable_object_with_properties

napi_status napi_create_sendable_object_with_properties(napi_env env,
                                                        size_t property_count,
                                                        const napi_property_descriptor* properties,
                                                        napi_value* result);

napi_create_sendable_array

napi_status napi_create_sendable_array(napi_env env, napi_value* result);

napi_create_sendable_array_with_length

napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result);

napi_create_sendable_arraybuffer

napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result);

napi_create_sendable_typedarray

napi_status napi_create_sendable_typedarray(napi_env env,
                                            napi_typedarray_type type,
                                            size_t length,
                                            napi_value arraybuffer,
                                            size_t byte_offset,
                                            napi_value* result);

napi_wrap_sendable

napi_status napi_wrap_sendable(napi_env env,
                               napi_value js_object,
                               void* native_object,
                               napi_finalize finalize_cb,
                               void* finalize_hint);

napi_wrap_sendable_with_size

napi_status napi_wrap_sendable_with_size(napi_env env,
                                         napi_value js_object,
                                         void* native_object,
                                         napi_finalize finalize_cb,
                                         void* finalize_hint,
                                         size_t native_binding_size);

napi_unwrap_sendable

napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result);

napi_remove_wrap_sendable

napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result);

napi_wrap_enhance

napi_status napi_wrap_enhance(napi_env env,
                              napi_value js_object,
                              void* native_object,
                              napi_finalize finalize_cb,
                              bool async_finalizer,
                              void* finalize_hint,
                              size_t native_binding_size,
                              napi_ref* result);

Other Utilities

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Node-API

harmony 鸿蒙Building an NDK Project with CMake

harmony 鸿蒙Building an NDK Project with the DevEco Studio Template

harmony 鸿蒙NDK Project Building Overview

harmony 鸿蒙Building an NDK Project with Prebuilt Libraries

harmony 鸿蒙C/C++ Library Mechanisms

harmony 鸿蒙CPU Features

harmony 鸿蒙Creating an NDK Project

harmony 鸿蒙C/C++ Memory Error Detection

harmony 鸿蒙Debugging in DevEco Studio