Node-API provides APIs to encapsulate JavaScript (JS) capabilities as native addons. It is independent of the underlying JS and is maintained as part of Node.js.
Node-API insulates addons from changes in the underlying JS engine and allows the modules compiled for one major version to run on later major versions without recompilation.
The HarmonyOS Node-API component optimizes the Node-API implementation and provides interaction with underlying engines such as ArkJS. Currently, the HarmonyOS Node-API component does not support all Node-API APIs.
To use Node-API, include the following header file:
#include <napi/native_api.h>
Add the following dynamic link library to CMakeLists.txt:
libace_napi.z.so
The APIs exported from the native Node-API library feature usage and behaviors based on Node.js and have incorporated extended capabilities.
| Symbol Type | Symbol | Description | Start API Version |
|---|---|---|---|
| FUNC | napi_module_register | Registers a native module. | 10 |
| FUNC | napi_get_last_error_info | Obtains the napi_extended_error_info struct, which contains the latest error information. | 10 |
| FUNC | napi_throw | Throws a JS value. | 10 |
| FUNC | napi_throw_error | Throws a JS Error with text information. | 10 |
| FUNC | napi_throw_type_error | Throws a JS TypeError with text information. | 10 |
| FUNC | napi_throw_range_error | Throws a JS RangeError with text information. | 10 |
| FUNC | napi_is_error | Checks whether napi_value indicates an error object. | 10 |
| FUNC | napi_create_error | Creates a JS Error with text information. | 10 |
| FUNC | napi_create_type_error | Creates a JS TypeError with text information. | 10 |
| FUNC | napi_create_range_error | Creates a JS RangeError with text information. | 10 |
| FUNC | napi_get_and_clear_last_exception | Obtains and clears the latest exception. | 10 |
| FUNC | napi_is_exception_pending | Checks whether an exception occurs. | 10 |
| FUNC | napi_fatal_error | Raises a fatal error to terminate the process immediately. | 10 |
| FUNC | napi_open_handle_scope | Opens a scope. | 10 |
| FUNC | napi_close_handle_scope | Closes the scope passed in. After the scope is closed, all references declared in it are closed. | 10 |
| FUNC | napi_open_escapable_handle_scope | Opens an escapable handle scope from which the declared values can be returned to the outer scope. | 10 |
| FUNC | napi_close_escapable_handle_scope | Closes the escapable handle scope passed in. | 10 |
| FUNC | napi_escape_handle | Promotes the handle to the input JS object so that it is valid for the lifespan of its outer scope. | 10 |
| FUNC | napi_create_reference | Creates a reference for an Object to extend its lifespan. The caller needs to manage the reference lifespan. | 10 |
| FUNC | napi_delete_reference | Deletes the reference passed in. | 10 |
| FUNC | napi_reference_ref | Increments the reference count for the reference passed in and returns the count. | 10 |
| FUNC | napi_reference_unref | Decrements the reference count for the reference passed in and returns the count. | 10 |
| FUNC | napi_get_reference_value | Obtains the JS Object associated with the reference. | 10 |
| FUNC | napi_create_array | Creates a JS array. | 10 |
| FUNC | napi_create_array_with_length | Creates a JS array of the specified length. | 10 |
| FUNC | napi_create_arraybuffer | Creates a JS ArrayBuffer of the specified size. | 10 |
| FUNC | napi_create_external | Allocates a JS value with external data. | 10 |
| FUNC | napi_create_external_arraybuffer | Allocates a JS ArrayBuffer with external data. | 10 |
| FUNC | napi_create_object | Creates a default JS object. | 10 |
| FUNC | napi_create_symbol | Creates a JS symbol. | 10 |
| FUNC | napi_create_typedarray | Creates a JS TypeArray from an existing ArrayBuffer. | 10 |
| FUNC | napi_create_dataview | Creates a JS DataView from an existing ArrayBuffer. | 10 |
| FUNC | napi_create_int32 | Creates a JS number from C int32_t data. | 10 |
| FUNC | napi_create_uint32 | Creates a JS number from C uint32_t data. | 10 |
| FUNC | napi_create_int64 | Creates a JS number from C int64_t data. | 10 |
| FUNC | napi_create_double | Creates a JS number from C double data. | 10 |
| FUNC | napi_create_string_latin1 | Creates a JS string from an ISO-8859-1-encoded C string. | 10 |
| FUNC | napi_create_string_utf8 | Creates a JS string from a UTF8-encoded C string. | 10 |
| FUNC | napi_create_string_utf16 | Creates a JS string from a UTF16-encoded C string. | 10 |
| FUNC | napi_get_array_length | Obtains the array length. | 10 |
| FUNC | napi_get_arraybuffer_info | Obtains the underlying data buffer of an ArrayBuffer and its length. | 10 |
| FUNC | napi_get_prototype | Obtains the prototype of a JS object. | 10 |
| FUNC | napi_get_typedarray_info | Obtains properties of a TypedArray. | 10 |
| FUNC | napi_get_dataview_info | Obtains properties of a DataView. | 10 |
| FUNC | napi_get_value_bool | Obtains the C Boolean equivalent of a JS Boolean value. | 10 |
| FUNC | napi_get_value_double | Obtains the C double equivalent of a JS number. | 10 |
| FUNC | napi_get_value_external | Obtains the external data pointer previously passed through napi_create_external(). | 10 |
| FUNC | napi_get_value_int32 | Obtains the C int32 equivalent of a JS number. | 10 |
| FUNC | napi_get_value_int64 | Obtains the C int64 equivalent of a JS number. | 10 |
| FUNC | napi_get_value_string_latin1 | Obtains the ISO-8859-1-encoded string corresponding to the given JS value. | 10 |
| FUNC | napi_get_value_string_utf8 | Obtains the UTF8-encoded string corresponding to the given JS value. | 10 |
| FUNC | napi_get_value_string_utf16 | Obtains the UTF16-encoded string corresponding to the given JS value. | 10 |
| FUNC | napi_get_value_uint32 | Obtains the C uint32 equivalent of a JS number. | 10 |
| FUNC | napi_get_boolean | Obtains a JS Boolean object based on a C Boolean value. | 10 |
| FUNC | napi_get_global | Obtains the global object. | 10 |
| FUNC | napi_get_null | Obtains the null object. | 10 |
| FUNC | napi_get_undefined | Obtains the undefined object. | 10 |
| FUNC | napi_coerce_to_bool | Forcibly converts a JS value to a JS Boolean value. | 10 |
| FUNC | napi_coerce_to_number | Forcibly converts a JS value to a JS number. | 10 |
| FUNC | napi_coerce_to_object | Forcibly converts a JS value to a JS object. | 10 |
| FUNC | napi_coerce_to_string | Forcibly converts a JS value to a JS string. | 10 |
| FUNC | napi_typeof | Obtains the JS type of a JS value. | 10 |
| FUNC | napi_instanceof | Checks whether an object is an instance of the specified constructor. | 10 |
| FUNC | napi_is_array | Checks whether a JS value is an array. | 10 |
| FUNC | napi_is_arraybuffer | Checks whether a JS value is an ArrayBuffer. | 10 |
| FUNC | napi_is_typedarray | Checks whether a JS value is a TypedArray. | 10 |
| FUNC | napi_is_dataview | Checks whether a JS value is a DataView. | 10 |
| FUNC | napi_is_date | Checks whether a JS value is a JS Date object. | 10 |
| FUNC | napi_strict_equals | Checks whether two JS values are strictly equal. | 10 |
| FUNC | napi_get_property_names | Obtains the names of the enumerable properties of an object in an array of strings. | 10 |
| FUNC | napi_set_property | Sets a property for an object. | 10 |
| FUNC | napi_get_property | Obtains the requested property of an object. | 10 |
| FUNC | napi_has_property | Checks whether an object has the specified property. | 10 |
| FUNC | napi_delete_property | Deletes the key property from an object. | 10 |
| FUNC | napi_has_own_property | Checks whether an object has the own property named key. | 10 |
| FUNC | napi_set_named_property | Sets a property with the given name for an object. | 10 |
| FUNC | napi_get_named_property | Obtains the property with the given name in an object. | 10 |
| FUNC | napi_has_named_property | Checks whether an object has the property with the given name. | 10 |
| FUNC | napi_set_element | Sets an element at the specified index of an object. | 10 |
| FUNC | napi_get_element | Obtains the element at the specified index of an object. | 10 |
| FUNC | napi_has_element | Obtains the element if the object has an element at the specified index. | 10 |
| FUNC | napi_delete_element | Deletes the element at the specified index of an object. | 10 |
| FUNC | napi_define_properties | Defines multiple properties for an object. | 10 |
| FUNC | napi_type_tag_object | Associates the value of a tag pointer with an object. | 10 |
| FUNC | napi_check_object_type_tag | Checks whether a tag pointer is associated with a JS object. | 10 |
| FUNC | napi_call_function | Calls a JS function object in a native method, that is, native calls JS. | 10 |
| FUNC | napi_create_function | Creates a function object in native code for JS to call. | 10 |
| FUNC | napi_get_cb_info | Obtains detailed information about the call, such as the parameters and this pointer, from the given callback information. | 10 |
| FUNC | napi_get_new_target | Obtains the new.target of the constructor call. | 10 |
| FUNC | napi_new_instance | Creates an instance based on the given constructor. | 10 |
| FUNC | napi_define_class | Defines a JS class corresponding to the C++ class. | 10 |
| FUNC | napi_wrap | Wraps a native instance in a JS object. | 10 |
| FUNC | napi_unwrap | Unwraps the native instance from a JS object. | 10 |
| FUNC | napi_remove_wrap | Removes the native instance from the JS object. | 10 |
| FUNC | napi_create_async_work | Creates a work object that executes logic asynchronously. | 10 |
| FUNC | napi_delete_async_work | Releases an async work object. | 10 |
| FUNC | napi_queue_async_work | Adds an async work object to the queue so that it can be scheduled for execution. | 10 |
| FUNC | napi_cancel_async_work | Cancels the queued async work if it has not been started. | 10 |
| FUNC | napi_async_init | Creates an async context. The capabilities related to async_hook are not supported. | 11 |
| FUNC | napi_make_callback | Allows a JS function to be called in the async context. The capabilities related to async_hook are not supported. | 11 |
| FUNC | napi_async_destroy | Destroys an async context. The capabilities related to async_hook are not supported. | 11 |
| FUNC | napi_open_callback_scope | Opens a callback scope. The capabilities related to async_hook are not supported. | 11 |
| FUNC | napi_close_callback_scope | Closes a callback scope. The capabilities related to async_hook are not supported. | 11 |
| FUNC | napi_get_node_version | Obtains the current Node-API version. | 10 |
| FUNC | napi_get_version | Obtains the latest Node-API version supported when the Node.js runtime. | 10 |
| FUNC | napi_create_promise | Creates a deferred object and a JS promise. | 10 |
| FUNC | napi_resolve_deferred | Resolves a deferred object that is associated with a JS promise. | 10 |
| FUNC | napi_reject_deferred | Rejects a deferred object that is associated with a JS promise. | 10 |
| FUNC | napi_is_promise | Checks whether the given JS value is a promise object. | 10 |
| FUNC | napi_get_uv_event_loop | Obtains the current libuv loop instance. | 10 |
| FUNC | napi_create_threadsafe_function | Creates a thread-safe function. | 10 |
| FUNC | napi_get_threadsafe_function_context | Obtains the context of a thread-safe function. | 10 |
| FUNC | napi_call_threadsafe_function | Calls a thread-safe function. | 10 |
| FUNC | napi_acquire_threadsafe_function | Acquires a thread-safe function. | 10 |
| FUNC | napi_release_threadsafe_function | Releases a thread-safe function. | 10 |
| FUNC | napi_ref_threadsafe_function | Creates a reference to a thread-safe function. The event loop running on the main thread should not exit until the thread-safe function is destroyed. | 10 |
| FUNC | napi_unref_threadsafe_function | Releases the reference to a thread-safe function. The event loop running on the main thread may exit before the thread-safe function is destroyed. | 10 |
| FUNC | napi_create_date | Creates a JS Date object from C double data. | 10 |
| FUNC | napi_get_date_value | Obtains the C double equivalent of the given JS Date. | 10 |
| FUNC | napi_create_bigint_int64 | Creates a JS BigInt from C int64 data. | 10 |
| FUNC | napi_create_bigint_uint64 | Creates a JS BigInt from C uint64 data. | 10 |
| FUNC | napi_create_bigint_words | Creates a single JS BigInt from a C uint64 array. | 10 |
| FUNC | napi_get_value_bigint_int64 | Obtains the C int64 equivalent of the given JS BigInt. | 10 |
| FUNC | napi_get_value_bigint_uint64 | Obtains the C uint64 equivalent of the given JS BigInt. | 10 |
| FUNC | napi_get_value_bigint_words | Obtains information from the given JS BigInt, including the sign bit, 64-bit little-endian array, and number of elements in the array. | 10 |
| FUNC | napi_create_buffer | Creates a JS Buffer instance of the specified size. | 10 |
| FUNC | napi_create_buffer_copy | Creates a JS Buffer instance of the specified size, and initializes it with data copied from the passed-in buffer. | 10 |
| FUNC | napi_create_external_buffer | Creates a JS Buffer instance of the specified size, and initializes it with the given data. The Buffer instance created can include extra. | 10 |
| FUNC | napi_get_buffer_info | Obtains the underlying data of Buffer and its length. | 10 |
| FUNC | napi_is_buffer | Checks whether the given JS value is a Buffer object. | 10 |
| FUNC | napi_object_freeze | Freezes the given object. | 10 |
| FUNC | napi_object_seal | Seals the given object. | 10 |
| FUNC | napi_get_all_property_names | Obtains an array containing the names of all the available properties of this object. | 10 |
| FUNC | napi_detach_arraybuffer | Detaches the underlying data of the given ArrayBuffer. | 10 |
| FUNC | napi_is_detached_arraybuffer | Checks whether the given ArrayBuffer has been detached. | 10 |
| FUNC | napi_run_script | Runs an object as JS code. Currently, this API is an empty implementation. For security purposes, you are advised to use napi_run_script_path. | 10 |
| FUNC | napi_set_instance_data | Associates data with the currently running environment. | 11 |
| FUNC | napi_get_instance_data | Retrieves the data that was previously associated with the currently running environment. | 11 |
| FUNC | napi_add_env_cleanup_hook | Registers a clean-up hook for releasing resources when the environment exits. | 11 |
| FUNC | napi_remove_env_cleanup_hook | Unregisters the clean-up hook. | 11 |
| FUNC | napi_add_async_cleanup_hook | Registers an async clean-up hook for releasing resources when the environment exits. | 11 |
| FUNC | napi_remove_async_cleanup_hook | Unregisters the async clean-up hook. | 11 |
| FUNC | node_api_get_module_file_name | Obtains the absolute path of the location, from which the addon is loaded. | 11 |
| FUNC | napi_add_finalizer | Adds a napi_finalize callback, which will be called when the JS object in js_Object is garbage-collected. | 11 |
| FUNC | napi_fatal_exception | Throws UncaughtException to JS. | 12 |
For ease of description, the symbol exported to HarmonyOS is referred to as "exported symbol" and the symbol in the native library is referred to as "native symbol".
Return value
If code is a null pointer, the native symbol returns napi_invalid_arg, whereas the exported symbol does not check the validity of code.
The exported symbol permits a failure in setting code.
Return value
If code is a null pointer, the native symbol returns napi_invalid_arg, whereas the exported symbol does not check the validity of code.
The exported symbol permits a failure in setting code.
Return value
If code is a null pointer, the native symbol returns napi_invalid_arg, whereas the exported symbol does not check the validity of code.
The exported symbol permits a failure in setting code.
Parameters
Return value
If the code type is incorrect, the exported symbol returns napi_invalid_arg.
The exported symbol permits a failure in setting code.
Parameters
Return value
If the code type is incorrect, the exported symbol returns napi_invalid_arg.
The exported symbol permits a failure in setting code.
The error type created in HarmonyOS is Error.
Parameters
Return value
If the code type is incorrect, the exported symbol returns napi_invalid_arg.
The exported symbol permits a failure in setting code.
The error type created in HarmonyOS is Error.
Parameters
NOTE
Return value
Return value
Return value
The exported symbol returns napi_arraybuffer_expected if arraybuffer is not empty and is not an ArrayBuffer object.
If the sum of byte_offset and byte_length is greater than the size of arraybuffer, the export API throws a RangeError exception and returns napi_pending_exception.
Parameters
Return value
Return value
If object is not an object, the exported symbol returns napi_object_expected with result unprocessed.
If constructor is not a function object, the exported symbol returns napi_function_expected without throwing any exception.
Parameters
Return value
Return value
Return value
Return value
Return value
Return value
Return value
Return value
Return value
Return value
If object is not an object or a function, the exported symbol returns napi_object_expected.
If the index value is too large, the native symbol throws an exception and interrupts the process. HarmonyOS attempts to allocate memory. If the memory allocation fails, object will not be modified.
Return value
Return value
Return value
Return value
If object is not an object or a function, the exported symbol returns napi_object_expected.
If an exception is triggered during property traversal, the native symbol throws the exception, whereas the exported symbol clears the exception and continues the execution.
Return value
Return value
Return value
The export symbol does not check whether the recv parameter is nullptr.
If func is not a function, the export symbol returns napi_function_expected.
Return value
Return value
Parameters
Return value
Return value
Return value
NOTE
Parameters
The exported symbol does not support async_hooks.
The exported symbol does not check whether the input parameter async_resource_name is a string.
The exported symbol does not process the input parameter async_resource because it does not support async_hooks.
Return value
NOTE
NOTE
NOTE
NOTE
NOTE
NOTE
Parameters
initial_thread_count: The maximum value is 128 in the exported symbol.
async_resource: There is no type restriction for this parameter in the exported symbol.
async_resource_name: There is no type restriction for this parameter in the exported symbol.
func: There is no type restriction for this parameter in the exported symbol.
NOTE
NOTE
Before uv_async_send is called in HarmonyOS, env is checked.
If uv_async_send fails to be called, the exported symbol returns napi_generic_failure.
NOTE
Before uv_async_send is called in HarmonyOS, env is checked.
If ThreadCount is 0, the exported symbol returns napi_generic_failure.
NOTE
NOTE
Return value
Return value
Return value
Return value
The buffer created in HarmonyOS is of the ArrayBufferLike type.
If size is 0, the exported symbol returns napi_invalid_arg.
If size is greater than 2097152, the exported symbol returns napi_invalid_arg and logs an error.
If data is nullptr, the exported symbol returns napi_invalid_arg.
If an exception occurs before the native symbol is called or exited, napi_pending_exception is returned. There is no such verification in HarmonyOS.
Return value
The buffer created in HarmonyOS is of the ArrayBufferLike type.
If size is 0, the exported symbol returns napi_invalid_arg.
If size is greater than 2097152, the exported symbol returns napi_invalid_arg and logs an error.
If data is nullptr, the exported symbol returns napi_invalid_arg.
If an exception occurs before the native symbol is called or exited, napi_pending_exception is returned. There is no such verification in HarmonyOS.
Return value
The buffer created in HarmonyOS is of the ArrayBufferLike type.
If size is 0, the exported symbol returns napi_invalid_arg.
If size is greater than 2097152, the exported symbol returns napi_invalid_arg and logs an error.
If the buffer fails to be created due to an identified cause, the native symbol returns napi_generic_failure, whereas the exported symbol returns napi_pending_exception.
Return value
Return value
NOTE
Return value
NOTE
In HarmonyOS, when a strong reference is deleted, this callback is directly invoked without waiting for the destruction of the object.
If the callback throws an exception, HarmonyOS triggers JSCrash.
NOTE
Parameters
Return value
Return value
Return value
| Symbol Type | Symbol | Description |
|---|---|---|
| FUNC | napi_adjust_external_memory | Adjusts the external memory held by a JS object. |
| Symbol Type | Symbol | Description | Start API Version |
|---|---|---|---|
| FUNC | napi_queue_async_work_with_qos | Adds an async work object to the queue so that it can be scheduled for execution based on the QoS priority passed in. | 10 |
| FUNC | napi_run_script_path | Runs an ABC file. | 10 |
| FUNC | napi_load_module | Loads an .abc file as a module. This API returns the namespace of the module. | 11 |
| FUNC | napi_create_object_with_properties | Creates a JS object using the given napi_property_descriptor. The key of the descriptor must be a string and cannot be converted into a number. | 11 |
| FUNC | napi_create_object_with_named_properties | Creates a JS object using the given napi_value and key. The key must be a string and cannot be converted into a number. | 11 |
| FUNC | napi_coerce_to_native_binding_object | Forcibly binds a JS object and a native object. | 11 |
| FUNC | napi_create_ark_runtime | Creates an ArkTS runtime environment. | 12 |
| FUNC | napi_destroy_ark_runtime | Destroys the ArkTS runtime environment. | 12 |
| FUNC | napi_run_event_loop | Runs the underlying event loop. | 12 |
| FUNC | napi_stop_event_loop | Stops the underlying event loop. | 12 |
| FUNC | napi_load_module_with_info | Loads an .abc file as a module. This API returns the namespace of the module. It can be used in a newly created ArkTS runtime environment. | 12 |
| FUNC | napi_serialize | Converts an ArkTS object into native data. | 12 |
| FUNC | napi_deserialize | Converts native data into an ArkTS object. | 12 |
| FUNC | napi_delete_serialization_data | Deletes serialized data. | 12 |
| FUNC | napi_call_threadsafe_function_with_priority | Calls a task with the specified priority and enqueuing mode into the ArkTS main thread. | 12 |
| FUNC | napi_is_sendable | Checks whether the given JS value is sendable. | 12 |
| FUNC | napi_define_sendable_class | Creates a sendable class. | 12 |
| FUNC | napi_create_sendable_object_with_properties | Creates a sendable object with the given napi_property_descriptor. | 12 |
| FUNC | napi_create_sendable_array | Creates a sendable array. | 12 |
| FUNC | napi_create_sendable_array_with_length | Creates a sendable array of the specified length. | 12 |
| FUNC | napi_create_sendable_arraybuffer | Creates a sendable ArrayBuffer. | 12 |
| FUNC | napi_create_sendable_typedarray | Creates a sendable TypedArray. | 12 |
| FUNC | napi_wrap_sendable | Wraps a native instance into an ArkTS object. | 12 |
| FUNC | napi_wrap_sendable_with_size | Wraps a native instance into an ArkTS object with the specified size. | 12 |
| FUNC | napi_unwrap_sendable | Unwraps the native instance from an ArkTS object. | 12 |
| FUNC | napi_remove_wrap_sendable | Removes the native instance from an ArkTS object. | 12 |
typedef enum {
napi_qos_background = 0, // Low priority for works invisible to users, such as data synchronization and backup.
napi_qos_utility = 1, // Medium priority for works that do not require immediate response, such as downloading or importing data.
napi_qos_default = 2, // Default priority.
napi_qos_user_initiated = 3, // High priority for user-triggered works with visible progress, for example, opening a file.
} napi_qos_t; Description
Enumerates the QoS levels, which determine the priority of thread scheduling.
typedef enum {
napi_event_mode_default = 0, // Run the underlying event loop while blocking the current thread, and exit the event loop only when there is no task in the loop.
napi_event_mode_nowait = 1, // Run the underlying event loop without blocking the current thread. Process a task and exit the event loop after the task is complete. If there is no task in the event loop, exit the event loop immediately.
} napi_event_mode; Description
Enumerates the modes for running the underlying event loop.
napi_status napi_queue_async_work_with_qos(napi_env env,
napi_async_work work,
napi_qos_t qos); Description
Adds an async work object to the queue so that it can be scheduled for execution based on the QoS priority passed in.
Parameters
env: environment, in which the API is invoked.
work: handle to the async work object to schedule. This object is created by napi_create_async_work.
qos: priority of the task to schedule.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_run_script_path(napi_env env,
const char* abcPath,
napi_value* result); Description
Runs an .abc file.
Parameters
env: environment, in which the API is invoked.
abcPath: JS path of the script to run. The value is a string that specifies the location of the script file to run.
result: pointer to napi_value, which holds the script execution result.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_load_module(napi_env env,
const char* path,
napi_value* result); Description
Loads a system module or a customized module. This API returns the namespace of the module loaded.
Parameters
env: environment, in which the API is invoked.
path: name of the system module to load or path of the customized module to load.
result: pointer to napi_value, which holds the module loading result.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_object_with_properties(napi_env env,
napi_value* result,
size_t property_count,
const napi_property_descriptor* properties); Description
Creates a JS object using the given napi_property_descriptor.
napi_property_descriptor defines a property, including the property attributes and the methods used to obtain and set the property. By passing napi_property_descriptor, you can define the properties when creating an object.
The key in napi_property_descriptor must be a string that cannot be converted into a number.
Parameters
env: environment, in which the API is invoked.
result: pointer to napi_value, which holds the created object.
property_count: number of properties to be added to the object.
properties: pointer to a napi_property_descriptor array containing information about the properties to be added to the object.
Return value
Returns napi_ok if the operation is successful.
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); Description
Creates a JS object using the given napi_values and keys. The key must be a string and cannot be converted into a number.
Parameters
env: environment, in which the API is invoked.
result: pointer to napi_value, which holds the created object.
property_count: number of properties to be added to the object.
keys: pointer to a const char array containing the keys of the properties to add.
values: pointer to a napi_value array containing the properties to add. The keys and properties are in one-to-one mapping.
Return value
Returns napi_ok if the operation is successful.
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); Description
Converts a JS object into an object carrying native information by forcibly binding callbacks and callback data to the JS object.
Parameters
env: environment, in which the API is invoked.
js_object: JS object to convert.
detach_cb: callback to be invoked to perform cleanup operations when the object is detached during serialization.
attach_cb: callback to be invoked when the object is attached during serialization.
native_object: parameters to be passed to the callbacks. This object cannot be empty.
hint: pointer to the additional information to be passed to the callbacks.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_ark_runtime(napi_env *env)
Description
Creates an ArkTS runtime environment.
Parameters
Return value
Returns napi_ok if the operation is successful.
napi_status napi_destroy_ark_runtime(napi_env *env)
Description
Destroys an ArkTS runtime environment.
Parameters
Return value
Returns napi_ok if the operation is successful.
napi_status napi_run_event_loop(napi_env env, napi_event_mode mode)
Description
Runs the underlying event loop.
Parameters
Return value
Returns napi_ok if the operation is successful.
napi_status napi_stop_event_loop(napi_env env)
Description
Stops the underlying event loop.
Parameters
Return value
Returns napi_ok if the operation is successful.
napi_status napi_load_module_with_info(napi_env env,
const char* path,
const char* module_info,
napi_value* result) Description
Loads an .abc file as a module. This API returns the namespace of the module. It can be used in a newly created ArkTS runtime environment.
Parameters
env: environment, in which the API is invoked.
path: path of the module to load.
module_info: module information. The value is a string containing module information. The module information contains detailed module information, such as the version, author, and related description.
result: pointer to napi_value, which holds the module loading result.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_serialize(napi_env env,
napi_value object,
napi_value transfer_list,
napi_value clone_list,
void** result) Description
Converts an ArkTS object into native data.
Parameters
env: environment, in which the API is invoked.
object: JS object to be serialized.
transfer_list: list of JS objects to be passed during serialization.
clone_list: list of JS objects to be cloned during serialization.
result: pointer to the serialization result. After the call is complete, the pointer to the native data converted is stored in this position.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object)
Description
Converts native data into an ArkTS object.
Parameters
env: environment, in which the API is invoked.
buffer: pointer to the binary data, which needs to be deserialized into a JS object.
object: pointer to the deserialized JS object.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_delete_serialization_data(napi_env env, void* buffer)
Description
Deletes serialized data.
Parameters
env: environment, in which the API is invoked.
buffer: pointer to the buffer that contains the serialized data to delete. If the serialized data is not longer required, you can use this API to delete the data and release the memory occupied.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func,
void *data,
napi_task_priority priority,
bool isTail) Description
Calls a task with the specified priority and enqueuing mode into the ArkTS main thread.
Parameters
func: thread-safe function object, which is returned when a thread-safe function is created.
data: pointer to the data to be passed to the JS callback function.
priority: priority of the task that calls the JS callback function.
isTail: whether the task is added to the tail of the task queue. If the value is true, the task will be added to the tail of the event loop. If it is false, the task will be executed immediately.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_is_sendable(napi_env env, napi_value value, bool* result)
Description
Checks whether the given JS value is sendable.
Parameters
env: environment, in which the API is invoked.
value: JS value to check.
result: pointer of the bool type, indicating whether the JS value is sendable.
Return value
Returns napi_ok if the operation is successful.
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)
Description
Creates a sendable class.
Parameters
env: environment, in which the API is invoked.
utf8name: pointer to the name of the class to create. This parameter is of the const char* type.
length: length of the class name, in bytes. This parameter is of the size_t type.
constructor: constructor of the class. This parameter is of the napi_callback type.
data: (optional) pointer to the additional data of the constructor. This parameter is of the void* type.
property_count: number of properties of the class. This parameter is of the size_t type.
properties: (optional) pointer to the descriptors of the properties. This parameter of the const napi_property_descriptor* type.
parent: (optional) parent class of the class to create. This parameter is of the napi_value type.
result: pointer to the sendable class created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_sendable_object_with_properties(napi_env env,
size_t property_count,
const napi_property_descriptor* properties,
napi_value* result) Description
Creates a sendable object with the given napi_property_descriptor.
Parameters
env: environment, in which the API is invoked.
property_count: number of properties of the class. This parameter is of the size_t type.
properties: pointer to the properties of the sendable object to create.
result: pointer to the sendable class created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_sendable_array(napi_env env, napi_value* result)
Description
Creates a sendable array.
Parameters
env: environment, in which the API is invoked.
result: pointer to the sendable array created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result)
Description
Creates a sendable array of the specified length.
Parameters
env: environment, in which the API is invoked.
length: length of the sendable array to create.
result: pointer to the sendable array created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result)
Description
Creates a sendable ArrayBuffer.
Parameters
env: environment, in which the API is invoked.
byte_length: length of the ArrayBuffer to create.
data: pointer to the byte buffer for storing the ArrayBuffer created.
result: pointer to the ArrayBuffer created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
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); Description
Creates a sendable TypedArray.
Parameters
env: environment, in which the API is invoked.
type: type of the TypedArray to create.
length: length of the TypedArray to create.
arraybuffer: ArrayBuffer instance to create.
byte_offset: offset of the ArrayBuffer.
result: pointer to the TypedArray created. This parameter is of the napi_value type.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_wrap_sendable(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint); Description
Wraps a native instance into an ArkTS object.
Parameters
env: environment, in which the API is invoked.
js_object: ArkTS object.
native_object: pointer to the native instance to be wrapped in the ArkTS object.
napi_finalize: (optional) callback to be invoked when the ArkTS object is destroyed.
finalize_hint: (optional) pointer to the callback context, which will be passed to the callback.
Return value
Returns napi_ok if the operation is successful.
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); Description
Wraps a native instance into an ArkTS object with the specified size.
Parameters
env: environment, in which the API is invoked.
js_object: ArkTS object.
native_object: pointer to the native instance to be wrapped in the ArkTS object.
napi_finalize: (optional) callback to be invoked when the ArkTS object is destroyed.
finalize_hint: (optional) pointer to the callback context, which will be passed to the callback.
native_binding_size: (optional) size of the native instance wrapped.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result)
Description
Unwraps the native instance from an ArkTS object.
Parameters
env: environment, in which the API is invoked.
js_object: ArkTS object.
result: double pointer to the native instance unwrapped.
Return value
Returns napi_ok if the operation is successful.
napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result)
Description
Removes the native instance from an ArkTS object.
Parameters
env: environment, in which the API is invoked.
js_object: ArkTS object.
result: double pointer to the native instance unwrapped.
Return value
Returns napi_ok if the operation is successful.