• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Node-API
2
3## Introduction
4
5Node-API (NAPI) provides APIs to encapsulate JavaScript (JS) capabilities as a native plug-in. It is independent of the underlying JS and is maintained as part of Node.js.
6
7
8## Supported Capabilities
9
10NAPI eliminates the differences between underlying JS engines and provides a set of stable interfaces.
11
12The OpenHarmony N-API component optimizes the Node-API interface implementation and provides connection to underlying engines such as ArkJS. Currently, some interfaces in the Node-API standard library are supported.
13
14## Symbols Exported from the N-API Component Standard Library
15
16|Type|Symbol|Description|
17| --- | --- | --- |
18|FUNC|napi_module_register|Registers the NAPI native module.|
19|FUNC|napi_get_last_error_info|Obtains the **napi_extended_error_info** structure, which contains the latest error information.|
20|FUNC|napi_throw|Throws a JS value.|
21|FUNC|napi_throw_error|Throws a JS **Error** with text information.|
22|FUNC|napi_throw_type_error|Throws a JS **TypeError** with text information.|
23|FUNC|napi_throw_range_error|Throws a JS **RangeError** with text information.|
24|FUNC|napi_is_error|Checks whether **napi_value** indicates an error object.|
25|FUNC|napi_create_error|Creates a JS **Error** with text information.|
26|FUNC|napi_create_type_error|Creates a JS **TypeError** with text information.|
27|FUNC|napi_create_range_error|Creates a JS **RangeError** with text information.|
28|FUNC|napi_get_and_clear_last_exception|Obtains and clears the latest exception.|
29|FUNC|napi_is_exception_pending|Checks whether an exception occurs.|
30|FUNC|napi_fatal_error|Raises a fatal error to terminate the process immediately.|
31|FUNC|napi_open_handle_scope|Creates a context environment.|
32|FUNC|napi_close_handle_scope|Closes the context environment. After the context environment is closed, all references declared in it are closed.|
33|FUNC|napi_open_escapable_handle_scope|Creates an escapable handle scope from which the declared values can be returned to the parent scope.|
34|FUNC|napi_close_escapable_handle_scope|Closes the escapable handle scope passed in.|
35|FUNC|napi_escape_handle|Promotes the handle to the input JS object so that it is valid for the lifespan of its parent scope.|
36|FUNC|napi_create_reference|Creates a reference for an **Object** to extend its lifespan. The caller needs to manage the reference lifespan.|
37|FUNC|napi_delete_reference|Deletes the reference passed in.|
38|FUNC|napi_reference_ref|Increments the reference count for the reference passed in and returns the count.|
39|FUNC|napi_reference_unref|Decrements the reference count for the reference passed in and returns the count.|
40|FUNC|napi_get_reference_value|Obtains the JS **Object** associated with the reference.|
41|FUNC|napi_create_array|Creates a JS **Array**.|
42|FUNC|napi_create_array_with_length|Creates a JS **Array** of the specified length.|
43|FUNC|napi_create_arraybuffer|Creates a JS **ArrayBuffer** of the specified size.|
44|FUNC|napi_create_external|Allocates a JS value with external data.|
45|FUNC|napi_create_external_arraybuffer|Allocates a JS **ArrayBuffer** with external data.|
46|FUNC|napi_create_object|Creates a default JS **Object**.|
47|FUNC|napi_create_symbol|Create a JS **Symbol**.|
48|FUNC|napi_create_typedarray|Creates a JS **TypeArray** from an existing **ArrayBuffer**.|
49|FUNC|napi_create_dataview|Creates a JS **DataView** from an existing **ArrayBuffer**.|
50|FUNC|napi_create_int32|Creates a JS **Number** from C **int32_t** data.|
51|FUNC|napi_create_uint32|Creates a JS **Number** from C **uint32_t** data.|
52|FUNC|napi_create_int64|Creates a JS **Number** from C **int64_t** data.|
53|FUNC|napi_create_double|Creates a JS **Number** from C **double** data.|
54|FUNC|napi_create_string_latin1|Creates a JS **String** from an ISO-8859-1-encoded C string.|
55|FUNC|napi_create_string_utf8|Creates a JS **String** from a UTF8-encoded C string.|
56|FUNC|napi_create_string_utf16|Creates a JS **String** from a UTF16-encoded C string.|
57|FUNC|napi_get_array_length|Obtains the length of an array.|
58|FUNC|napi_get_arraybuffer_info|Obtains the underlying data buffer of the **ArrayBuffer** and its length.|
59|FUNC|napi_get_prototype|Obtains the prototype of the specified JS **Object**.|
60|FUNC|napi_get_typedarray_info|Obtains properties of the specified **TypedArray**.|
61|FUNC|napi_get_dataview_info|Obtains properties of the specified **DataView**.|
62|FUNC|napi_get_value_bool|Obtains the C Boolean equivalent of the given JS **Boolean**.|
63|FUNC|napi_get_value_double|Obtains the C double equivalent of the given JS **Number**.|
64|FUNC|napi_get_value_external|Obtains the external data pointer previously passed through **napi_create_external()**.|
65|FUNC|napi_get_value_int32|Obtains the C int32 equivalent of the given JS **Number**.|
66|FUNC|napi_get_value_int64|Obtains the C int64 equivalent of the given JS **Number**.|
67|FUNC|napi_get_value_string_latin1|Obtains the ISO-8859-1-encoded string corresponding to the given JS value.|
68|FUNC|napi_get_value_string_utf8|Obtains the UTF8-encoded string corresponding to the given JS value.|
69|FUNC|napi_get_value_string_utf16|Obtains the UTF16-encoded string corresponding to the given JS value.|
70|FUNC|napi_get_value_uint32|Obtains the C uint32 equivalent of the given JS **Number**.|
71|FUNC|napi_get_boolean|Obtains the JS Boolean object based on the given C Boolean value.|
72|FUNC|napi_get_global|Obtains the **global** object.|
73|FUNC|napi_get_null|Obtains the **null** object.|
74|FUNC|napi_get_undefined|Obtains the **undefined** object.|
75|FUNC|napi_coerce_to_bool|Forcibly converts the given JS value to a JS Boolean value.|
76|FUNC|napi_coerce_to_number|Forcibly converts the given JS value to a JS number.|
77|FUNC|napi_coerce_to_object|Forcibly converts the given JS value to a JS object.|
78|FUNC|napi_coerce_to_string|Forcibly converts the given JS value to a JS string.|
79|FUNC|napi_typeof|Obtains the JS type of the given JS value.|
80|FUNC|napi_instanceof|Checks whether the given object is an instance of the specified constructor.|
81|FUNC|napi_is_array|Checks whether the given JS value is an array.|
82|FUNC|napi_is_arraybuffer|Checks whether the given JS value is a **ArrayBuffer**.|
83|FUNC|napi_is_typedarray|Checks whether the given JS value is a **TypedArray**.|
84|FUNC|napi_is_dataview|Checks whether the given JS value is a **DataView**.|
85|FUNC|napi_is_date|Checks whether the given JS value is a JS **Date** object.|
86|FUNC|napi_strict_equals|Checks whether two JS values are strictly equal.|
87|FUNC|napi_get_property_names|Obtains the names of the enumerable properties of **Object** in an array of strings.|
88|FUNC|napi_set_property|Sets a property for the given **Object**.|
89|FUNC|napi_get_property|Obtains the requested property of the given **Object**.|
90|FUNC|napi_has_property|Checks whether the given **Object** has the specified property.|
91|FUNC|napi_delete_property|Deletes the **key** property from the given **Object**.|
92|FUNC|napi_has_own_property|Checks whether the given **Object** has the own property named **key**.|
93|FUNC|napi_set_named_property|Sets a property with the specified name for the given **Object**.|
94|FUNC|napi_get_named_property|Obtains the property with the specified name in the given **Object**.|
95|FUNC|napi_has_named_property|Checks whether the given **Object** has the property with the specified name.|
96|FUNC|napi_set_element|Sets an element at the specified index of the given **Object**.|
97|FUNC|napi_get_element|Obtains the element at the specified index of the given **Object**.|
98|FUNC|napi_has_element|Obtains the element if the given **Object** has an element at the specified index.|
99|FUNC|napi_delete_element|Deletes the element at the specified index of the given **Object**.|
100|FUNC|napi_define_properties|Defines multiple properties for the given **Object**.|
101|FUNC|napi_type_tag_object|Associates the value of the tag pointer with **Object**.|
102|FUNC|napi_check_object_type_tag|Checks whether a tag pointer is associated with the JS **Object**.|
103|FUNC|napi_call_function|Calls a JS function in a native method, that is, native call JS.|
104|FUNC|napi_create_function|Creates a native method for JS to call.|
105|FUNC|napi_get_cb_info|Obtains detailed information about the call, such as the parameters and **this** pointer, from the given callback info.|
106|FUNC|napi_get_new_target|Obtains the **new.target** of the constructor call.|
107|FUNC|napi_new_instance|Creates an instance based on the given constructor.|
108|FUNC|napi_define_class|Defines a JS class corresponding to the C++ class.|
109|FUNC|napi_wrap|Wraps a native instance in a JS object.|
110|FUNC|napi_unwrap|Obtains the native instance that was previously wrapped in a JS object.|
111|FUNC|napi_remove_wrap|Obtains the native instance that was previously wrapped in a JS object and removes the wrapping.|
112|FUNC|napi_create_async_work|Creates a work object that executes logic asynchronously.|
113|FUNC|napi_delete_async_work|Releases an asynchronous work object.|
114|FUNC|napi_queue_async_work|Adds an asynchronous work object to the queue so that it can be scheduled for execution.|
115|FUNC|napi_cancel_async_work|Cancels the queued asynchronous work if it has not been started.|
116|FUNC|napi_get_node_version|Obtains the current Node-API version.|
117|FUNC|napi_get_version|Obtains the latest Node-API version supported when the Node.js runtime.|
118|FUNC|napi_create_promise|Creates a deferred object and a JS promise.|
119|FUNC|napi_resolve_deferred|Resolves a deferred object that is associated with a JS promise.|
120|FUNC|napi_reject_deferred|Rejects a deferred object that is associated with a JS promise.|
121|FUNC|napi_is_promise|Checks whether the given JS value is a promise object.|
122|FUNC|napi_get_uv_event_loop|Obtains the current libuv loop instance.|
123|FUNC|napi_create_threadsafe_function|Creates a thread-safe function.|
124|FUNC|napi_get_threadsafe_function_context|Obtains the context of a thread-safe function.|
125|FUNC|napi_call_threadsafe_function|Calls a thread-safe function.|
126|FUNC|napi_acquire_threadsafe_function|Indicates that a thread starts to use a thread-safe function.|
127|FUNC|napi_release_threadsafe_function|Indicates that a thread releases a thread-safe function.|
128|FUNC|napi_ref_threadsafe_function|Indicates that the event loop running on the main thread should not exit until the thread-safe function is destroyed.|
129|FUNC|napi_unref_threadsafe_function|Indicates that the event loop running on the main thread may exit before the thread-safe function is destroyed.|
130|FUNC|napi_create_date|Creates a JS **Date** from C **double** data.|
131|FUNC|napi_get_date_value|Obtains the C double equivalent of the given JS **Date**.|
132|FUNC|napi_create_bigint_int64|Creates a JS **BigInt** from C **int64** data.|
133|FUNC|napi_create_bigint_uint64|Creates a JS **BigInt** from C **uint64** data.|
134|FUNC|napi_create_bigint_words|Creates a single JS **BigInt** from a C **uint64** array.|
135|FUNC|napi_get_value_bigint_int64|Obtains the C **int64** equivalent of the given JS **BigInt**.|
136|FUNC|napi_get_value_bigint_uint64|Obtains the C **uint64** equivalent of the given JS **BigInt**.|
137|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.|
138|FUNC|napi_create_buffer|Creates a JS **Buffer** instance of the specified size.|
139|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.|
140|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.|
141|FUNC|napi_get_buffer_info|Obtains the underlying data of **Buffer** and its length.|
142|FUNC|napi_is_buffer|Checks whether the given JS value is a **Buffer** object.|
143|FUNC|napi_object_freeze|Freezes the given object.|
144|FUNC|napi_object_seal|Seals the given object.|
145|FUNC|napi_get_all_property_names|Obtains an array containing the names of all the available properties of this object.|
146|FUNC|napi_detach_arraybuffer|Detaches the underlying data of the given **ArrayBuffer**.|
147|FUNC|napi_is_detached_arraybuffer|Checks whether the given **ArrayBuffer** has been detached.|
148
149## Extended Symbols of the N-API Component
150
151|Type|Symbol|Description|
152| --- | --- | --- |
153|FUNC|napi_queue_async_work_with_qos|Adds asynchronously working objects to the queue and schedules them based on the QoS priority.|
154|FUNC|napi_run_script_path|Runs an ABC file.|
155