1# Node-API 2 3## Introduction 4 5Node-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. 6 7## Supported Capabilities 8 9Node-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. 10 11The OpenHarmony Node-API component optimizes the Node-API implementation and provides interaction with underlying engines such as ArkJS. Currently, the OpenHarmony Node-API component does not support all Node-API APIs. 12 13## Including Node-API Capabilities 14 15To use Node-API, include the following header file: 16 17```cpp 18#include <napi/native_api.h> 19``` 20 21Add the following dynamic link library to **CMakeLists.txt**: 22 23``` 24libace_napi.z.so 25``` 26 27## Symbols Exported from the Node-API Library 28 29The APIs exported from the native Node-API library feature usage and behaviors based on [Node.js](https://nodejs.org/docs/latest-v12.x/api/n-api.html) and have incorporated [extended capabilities](#node-api-extended-symbols). 30 31|Symbol Type|Symbol|Description|Start API Version| 32| --- | --- | --- | --- | 33|FUNC|napi_module_register|Registers a native module.|10| 34|FUNC|napi_get_last_error_info|Obtains the **napi_extended_error_info** struct, which contains the latest error information.|10| 35|FUNC|napi_throw|Throws a JS value.|10| 36|FUNC|napi_throw_error|Throws a JS **Error** with text information.|10| 37|FUNC|napi_throw_type_error|Throws a JS **TypeError** with text information.|10| 38|FUNC|napi_throw_range_error|Throws a JS **RangeError** with text information.|10| 39|FUNC|napi_is_error|Checks whether **napi_value** indicates an error object.|10| 40|FUNC|napi_create_error|Creates a JS **Error** with text information.|10| 41|FUNC|napi_create_type_error|Creates a JS **TypeError** with text information.|10| 42|FUNC|napi_create_range_error|Creates a JS **RangeError** with text information.|10| 43|FUNC|napi_get_and_clear_last_exception|Obtains and clears the latest exception.|10| 44|FUNC|napi_is_exception_pending|Checks whether an exception occurs.|10| 45|FUNC|napi_fatal_error|Raises a fatal error to terminate the process immediately.|10| 46|FUNC|napi_open_handle_scope|Opens a scope.|10| 47|FUNC|napi_close_handle_scope|Closes the scope passed in. After the scope is closed, all references declared in it are closed.|10| 48|FUNC|napi_open_escapable_handle_scope|Opens an escapable handle scope, from which the declared values can be returned to the parent scope.|10| 49|FUNC|napi_close_escapable_handle_scope|Closes the escapable handle scope passed in.|10| 50|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| 51|FUNC|napi_create_reference|Creates a reference for an **Object** to extend its lifespan. The caller needs to manage the reference lifespan.|10| 52|FUNC|napi_delete_reference|Deletes the reference passed in.|10| 53|FUNC|napi_reference_ref|Increments the reference count for the reference passed in and returns the count.|10| 54|FUNC|napi_reference_unref|Decrements the reference count for the reference passed in and returns the count.|10| 55|FUNC|napi_get_reference_value|Obtains the JS **Object** associated with the reference.|10| 56|FUNC|napi_create_array|Creates a JS array.|10| 57|FUNC|napi_create_array_with_length|Creates a JS array of the specified length.|10| 58|FUNC|napi_create_arraybuffer|Creates a JS **ArrayBuffer** of the specified size.|10| 59|FUNC|napi_create_external|Allocates a JS value with external data.|10| 60|FUNC|napi_create_external_arraybuffer|Allocates a JS **ArrayBuffer** with external data.|10| 61|FUNC|napi_create_object|Creates a default JS object.|10| 62|FUNC|napi_create_symbol|Creates a JS symbol.|10| 63|FUNC|napi_create_typedarray|Creates a JS **TypeArray** from an existing **ArrayBuffer**.|10| 64|FUNC|napi_create_dataview|Creates a JS **DataView** from an existing **ArrayBuffer**.|10| 65|FUNC|napi_create_int32|Creates a JS number from C int32_t data.|10| 66|FUNC|napi_create_uint32|Creates a JS number from C uint32_t data.|10| 67|FUNC|napi_create_int64|Creates a JS number from C int64_t data.|10| 68|FUNC|napi_create_double|Creates a JS number from C double data.|10| 69|FUNC|napi_create_string_latin1|Creates a JS string from an ISO-8859-1-encoded C string.|10| 70|FUNC|napi_create_string_utf8|Creates a JS string from a UTF8-encoded C string.|10| 71|FUNC|napi_create_string_utf16|Creates a JS string from a UTF16-encoded C string.|10| 72|FUNC|napi_get_array_length|Obtains the array length.|10| 73|FUNC|napi_get_arraybuffer_info|Obtains the underlying data buffer of an **ArrayBuffer** and its length.|10| 74|FUNC|napi_get_prototype|Obtains the prototype of a JS object.|10| 75|FUNC|napi_get_typedarray_info|Obtains properties of a **TypedArray**.|10| 76|FUNC|napi_get_dataview_info|Obtains properties of a **DataView**.|10| 77|FUNC|napi_get_value_bool|Obtains the C Boolean equivalent of a JS Boolean value.|10| 78|FUNC|napi_get_value_double|Obtains the C double equivalent of a JS number.|10| 79|FUNC|napi_get_value_external|Obtains the external data pointer previously passed through **napi_create_external()**.|10| 80|FUNC|napi_get_value_int32|Obtains the C int32 equivalent of a JS number.|10| 81|FUNC|napi_get_value_int64|Obtains the C int64 equivalent of a JS number.|10| 82|FUNC|napi_get_value_string_latin1|Obtains the ISO-8859-1-encoded string corresponding to the given JS value.|10| 83|FUNC|napi_get_value_string_utf8|Obtains the UTF8-encoded string corresponding to the given JS value.|10| 84|FUNC|napi_get_value_string_utf16|Obtains the UTF16-encoded string corresponding to the given JS value.|10| 85|FUNC|napi_get_value_uint32|Obtains the C uint32 equivalent of a JS number.|10| 86|FUNC|napi_get_boolean|Obtains a JS Boolean object based on a C Boolean value.|10| 87|FUNC|napi_get_global|Obtains the **global** object.|10| 88|FUNC|napi_get_null|Obtains the **null** object.|10| 89|FUNC|napi_get_undefined|Obtains the **undefined** object.|10| 90|FUNC|napi_coerce_to_bool|Forcibly converts a JS value to a JS Boolean value.|10| 91|FUNC|napi_coerce_to_number|Forcibly converts a JS value to a JS number.|10| 92|FUNC|napi_coerce_to_object|Forcibly converts a JS value to a JS object.|10| 93|FUNC|napi_coerce_to_string|Forcibly converts a JS value to a JS string.|10| 94|FUNC|napi_typeof|Obtains the JS type of a JS value.|10| 95|FUNC|napi_instanceof|Checks whether an object is an instance of the specified constructor.|10| 96|FUNC|napi_is_array|Checks whether a JS value is an array.|10| 97|FUNC|napi_is_arraybuffer|Checks whether a JS value is an **ArrayBuffer**.|10| 98|FUNC|napi_is_typedarray|Checks whether a JS value is a **TypedArray**.|10| 99|FUNC|napi_is_dataview|Checks whether a JS value is a **DataView**.|10| 100|FUNC|napi_is_date|Checks whether a JS value is a JS **Date** object.|10| 101|FUNC|napi_strict_equals|Checks whether two JS values are strictly equal.|10| 102|FUNC|napi_get_property_names|Obtains the names of the enumerable properties of an object in an array of strings.|10| 103|FUNC|napi_set_property|Sets a property for an object.|10| 104|FUNC|napi_get_property|Obtains the requested property of an object.|10| 105|FUNC|napi_has_property|Checks whether an object has the specified property.|10| 106|FUNC|napi_delete_property|Deletes the **key** property from an object.|10| 107|FUNC|napi_has_own_property|Checks whether an object has the own property named **key**.|10| 108|FUNC|napi_set_named_property|Sets a property with the given name for an object.|10| 109|FUNC|napi_get_named_property|Obtains the property with the given name in an object.|10| 110|FUNC|napi_has_named_property|Checks whether an object has the property with the given name.|10| 111|FUNC|napi_set_element|Sets an element at the specified index of an object.|10| 112|FUNC|napi_get_element|Obtains the element at the specified index of an object.|10| 113|FUNC|napi_has_element|Obtains the element if the object has an element at the specified index.|10| 114|FUNC|napi_delete_element|Deletes the element at the specified index of an object.|10| 115|FUNC|napi_define_properties|Defines multiple properties for an object.|10| 116|FUNC|napi_type_tag_object|Associates the value of a tag pointer with an object.|10| 117|FUNC|napi_check_object_type_tag|Checks whether a tag pointer is associated with a JS object.|10| 118|FUNC|napi_call_function|Calls a JS function object in a native method, that is, native calls JS.|10| 119|FUNC|napi_create_function|Creates a function object in native code for JS to call.|10| 120|FUNC|napi_get_cb_info|Obtains detailed information about the call, such as the parameters and **this** pointer, from the given callback information.|10| 121|FUNC|napi_get_new_target|Obtains the **new.target** of the constructor call.|10| 122|FUNC|napi_new_instance|Creates an instance based on the given constructor.|10| 123|FUNC|napi_define_class|Defines a JS class corresponding to the C++ class.|10| 124|FUNC|napi_wrap|Wraps a native instance in a JS object.|10| 125|FUNC|napi_unwrap|Unwraps the native instance from a JS object.|10| 126|FUNC|napi_remove_wrap|Removes the native instance from the JS object.|10| 127|FUNC|napi_create_async_work|Creates a work object that executes logic asynchronously.|10| 128|FUNC|napi_delete_async_work|Releases an async work object.|10| 129|FUNC|napi_queue_async_work|Adds an async work object to the queue so that it can be scheduled for execution.|10| 130|FUNC|napi_cancel_async_work|Cancels the queued async work if it has not been started.|10| 131|FUNC|napi_async_init|Creates an async context. The capabilities related to **async_hook** are not supported.|11| 132|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| 133|FUNC|napi_async_destroy|Destroys an async context. The capabilities related to **async_hook** are not supported.|11| 134|FUNC|napi_open_callback_scope|Opens a callback scope. The capabilities related to **async_hook** are not supported.|11| 135|FUNC|napi_close_callback_scope|Closes a callback scope. The capabilities related to **async_hook** are not supported.|11| 136|FUNC|napi_get_node_version|Obtains the current Node-API version.|10| 137|FUNC|napi_get_version|Obtains the latest Node-API version supported when the Node.js runtime.|10| 138|FUNC|napi_create_promise|Creates a deferred object and a JS promise.|10| 139|FUNC|napi_resolve_deferred|Resolves a deferred object that is associated with a JS promise.|10| 140|FUNC|napi_reject_deferred|Rejects a deferred object that is associated with a JS promise.|10| 141|FUNC|napi_is_promise|Checks whether the given JS value is a promise object.|10| 142|FUNC|napi_get_uv_event_loop|Obtains the current libuv loop instance.|10| 143|FUNC|napi_create_threadsafe_function|Creates a thread-safe function.|10| 144|FUNC|napi_get_threadsafe_function_context|Obtains the context of a thread-safe function.|10| 145|FUNC|napi_call_threadsafe_function|Calls a thread-safe function.|10| 146|FUNC|napi_acquire_threadsafe_function|Acquires a thread-safe function.|10| 147|FUNC|napi_release_threadsafe_function|Releases a thread-safe function.|10| 148|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| 149|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| 150|FUNC|napi_create_date|Creates a JS **Date** object from C double data.|10| 151|FUNC|napi_get_date_value|Obtains the C double equivalent of the given JS **Date**.|10| 152|FUNC|napi_create_bigint_int64|Creates a JS BigInt from C int64 data.|10| 153|FUNC|napi_create_bigint_uint64|Creates a JS BigInt from C uint64 data.|10| 154|FUNC|napi_create_bigint_words|Creates a single JS BigInt from a C uint64 array.|10| 155|FUNC|napi_get_value_bigint_int64|Obtains the C int64 equivalent of the given JS BigInt.|10| 156|FUNC|napi_get_value_bigint_uint64|Obtains the C uint64 equivalent of the given JS BigInt.|10| 157|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| 158|FUNC|napi_create_buffer|Creates a JS **Buffer** instance of the specified size.|10| 159|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| 160|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| 161|FUNC|napi_get_buffer_info|Obtains the underlying data of **Buffer** and its length.|10| 162|FUNC|napi_is_buffer|Checks whether the given JS value is a **Buffer** object.|10| 163|FUNC|napi_object_freeze|Freezes the given object.|10| 164|FUNC|napi_object_seal|Seals the given object.|10| 165|FUNC|napi_get_all_property_names|Obtains an array containing the names of all the available properties of this object.|10| 166|FUNC|napi_detach_arraybuffer|Detaches the underlying data of the given ArrayBuffer.|10| 167|FUNC|napi_is_detached_arraybuffer|Checks whether the given ArrayBuffer has been detached.|10| 168|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| 169|FUNC|napi_set_instance_data|Associates data with the currently running environment.|11| 170|FUNC|napi_get_instance_data|Retrieves the data that was previously associated with the currently running environment.|11| 171|FUNC|napi_add_env_cleanup_hook|Registers a clean-up hook for releasing resources when the environment exits.|11| 172|FUNC|napi_remove_env_cleanup_hook|Unregisters the clean-up hook.|11| 173|FUNC|napi_add_async_cleanup_hook|Registers an async clean-up hook for releasing resources when the environment exits.|11| 174|FUNC|napi_remove_async_cleanup_hook|Unregisters the async clean-up hook.|11| 175|FUNC|node_api_get_module_file_name|Obtains the absolute path of the location, from which the addon is loaded.|11| 176|FUNC|napi_add_finalizer|Adds a **napi_finalize** callback, which will be called when the JS object in **js_Object** is garbage-collected.|11| 177|FUNC|napi_fatal_exception|Throws **UncaughtException** to JS.|12| 178 179## Differences Between the Exported Symbols and the Symbols in the Native Library 180 181> **NOTE** 182> 183> For ease of description, the symbol exported to OpenHarmony is referred to as "exported symbol" and the symbol in the native library is referred to as "native symbol". 184 185### napi_throw_error 186 187**Return value** 188 189- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 190 191- The exported symbol permits a failure in setting **code**. 192 193### napi_throw_type_error 194 195**Return value** 196 197- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 198 199- The exported symbol permits a failure in setting **code**. 200 201### napi_throw_range_error 202 203**Return value** 204 205- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 206 207- The exported symbol permits a failure in setting **code**. 208 209### napi_create_error 210 211**Parameters** 212 213- **code**: The value type can be string or number in the exported symbol. 214 215**Return value** 216 217- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 218 219- The exported symbol permits a failure in setting **code**. 220 221### napi_create_type_error 222 223**Parameters** 224 225- **code**: The value type can be string or number in the exported symbol. 226 227**Return value** 228 229- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 230 231- The exported symbol permits a failure in setting **code**. 232 233- The error type created in OpenHarmony is **Error**. 234 235### napi_create_range_error 236 237**Parameters** 238 239- **code**: The value type can be string or number in the exported symbol. 240 241**Return value** 242 243- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 244 245- The exported symbol permits a failure in setting **code**. 246 247- The error type created in OpenHarmony is **Error**. 248 249### napi_create_reference 250 251**Parameters** 252 253- **value**: The value type can be object, function, or symbol in the native symbol, whereas there are no restrictions on the value type in the exported symbol. 254 255### napi_delete_reference 256 257**NOTE** 258 259- In OpenHarmony, if the **napi_finalize** callback is registered when a strong reference is created, calling this API will trigger the **napi_finalize** callback. 260 261### napi_create_symbol 262 263**Return value** 264 265- The exported symbol returns **napi_invalid_arg** if **description** is not empty and is not a string. 266 267### napi_create_typedarray 268 269**Return value** 270 271- The exported symbol returns **napi_arraybuffer_expected** if **arraybuffer** is not empty and is not an **ArrayBuffer** object. 272 273### napi_create_dataview 274 275**Return value** 276 277- The exported symbol returns **napi_arraybuffer_expected** if **arraybuffer** is not empty and is not an **ArrayBuffer** object. 278 279- 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**. 280 281### napi_get_typedarray_info 282 283**Parameters** 284 285- **object**: The value type can be TypedArray or [Sendable TypedArray](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) in the exported symbol. 286 287**Return value** 288 289- The native symbol returns the number of elements in TypedArray via the **length** parameter; while the exported symbol returns length of the elements in TypedArray, in bytes. 290 291### napi_coerce_to_object 292 293**Return value** 294 295- If **value** is **undefined** or null, the exported symbol returns **napi_ok** and **undefined** in **result**. 296 297### napi_instanceof 298 299**Return value** 300 301- If **object** is not an object, the exported symbol returns **napi_object_expected** with **result** unprocessed. 302 303- If **constructor** is not a function object, the exported symbol returns **napi_function_expected** without throwing any exception. 304 305### napi_is_typedarray 306 307**Parameters** 308 309- **value**: The exported symbol also supports the [Sendable TypedArray](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) type for **value**. 310 311### napi_get_property_names 312 313**Return value** 314 315- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 316 317### napi_set_property 318 319**Return value** 320 321- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 322 323### napi_get_property 324 325**Return value** 326 327- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 328 329### napi_has_property 330 331**Return value** 332 333- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 334 335### napi_delete_property 336 337**Return value** 338 339- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 340 341### napi_has_own_property 342 343**Return value** 344 345- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 346 347### napi_set_named_property 348 349**Return value** 350 351- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 352 353### napi_get_named_property 354 355**Return value** 356 357- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 358 359### napi_has_named_property 360 361**Return value** 362 363- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 364 365### napi_set_element 366 367**Return value** 368 369- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 370 371- If the **index** value is too large, the native symbol throws an exception and interrupts the process. OpenHarmony attempts to allocate memory. If the memory allocation fails, **object** will not be modified. 372 373### napi_get_element 374 375**Return value** 376 377- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 378 379### napi_has_element 380 381**Return value** 382 383- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 384 385### napi_delete_element 386 387**Return value** 388 389- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 390 391### napi_define_properties 392 393**Return value** 394 395- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 396 397- 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. 398 399### napi_type_tag_object 400 401**Return value** 402 403- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 404 405### napi_check_object_type_tag 406 407**Return value** 408 409- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 410 411### napi_call_function 412 413**Return value** 414 415- The export symbol does not check whether the **recv** parameter is **nullptr**. 416 417- If **func** is not a function, the export symbol returns **napi_function_expected**. 418 419### napi_new_instance 420 421**Return value** 422 423- If **constructor** is not a function, the export symbol returns **napi_function_expected**. 424 425### napi_define_class 426 427**Return value** 428 429- If **length** is not **NAPI_AUTO_LENGTH** and is greater than **INT_MAX**, the exported symbol returns **napi_object_expected**. 430 431### napi_wrap 432 433**Parameters** 434 435- **finalize_cb**: It can be empty in the native symbol. If this parameter is empty, the exported symbol returns **napi_invalid_arg**. 436- **result**: The native symbol returns a weak reference, whereas the exported symbol returns a strong reference if **result** is not empty. 437 438**Return value** 439 440- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 441 442### napi_unwrap 443 444**Return value** 445 446- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 447 448### napi_remove_wrap 449 450**Return value** 451 452- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 453 454**NOTE** 455 456- If the wrap is associated with the **finalize** callback, the export symbol will call **finalize()** before removing the wrap. 457 458### napi_create_async_work 459 460**Parameters** 461 462- The exported symbol does not support **async_hooks**. 463 464- The exported symbol does not verify whether the input parameter **async_resource_name** is of the string type. A value of string type is recommended. If **async_resource_name** is of the string type, the trace information contains the string. Otherwise, the trace information does not contain it. 465 466- The exported symbol does not process the input parameter **async_resource** because it does not support **async_hooks**. 467 468### napi_delete_async_work 469 470**Parameters** 471 472- The exported symbol does not support **async_hooks**. 473 474### napi_queue_async_work 475 476**Parameters** 477 478- The exported symbol does not support **async_hooks**. 479 480### napi_cancel_async_work 481 482**Return value** 483 484- If the task fails to be canceled due to the underlying UV, the native symbol returns **napi_generic_failure**, **napi_invalid_arg**, or **napi_cancelled** based on the failure cause. The exported symbol does not verify the UV return value. You can check whether the task fails to be canceled based on log information. 485 486### napi_async_init 487 488**NOTE** 489 490- Currently, OpenHarmony does not support **async_hooks**. After the exported symbol is called, operations related to **async_hooks** will not be performed. 491 492### napi_make_callback 493 494**NOTE** 495 496- Currently, OpenHarmony does not support **async_hooks**. After the exported symbol is called, operations related to **async_hooks** will not be performed. 497 498### napi_async_destroy 499 500**NOTE** 501 502- Currently, OpenHarmony does not support **async_hooks**. After the exported symbol is called, operations related to **async_hooks** will not be performed. 503 504### napi_get_node_version 505 506**NOTE** 507 508- OpenHarmony does not need to obtain the node version. Therefore, the export symbol is an empty implementation. 509 510### napi_resolve_deferred 511 512**NOTE** 513 514- When an exception occurs in the **resolve** or **reject** callback of the **then()** method of the promise, if the promise does not have a catch block, the code execution continues. If the promise has a catch block, the exception will be captured by the catch block. 515 516### napi_reject_deferred 517 518**NOTE** 519 520- When an exception occurs in the **resolve** or **reject** callback of the **then()** method of the promise, if the promise does not have a catch block, the code execution continues. If the promise has a catch block, the exception will be captured by the catch block. 521 522### napi_create_threadsafe_function 523 524**Parameters** 525 526- **initial_thread_count**: The maximum value is **128** in the exported symbol. 527 528- **async_resource**: There is no type restriction for this parameter in the exported symbol. 529 530- **async_resource_name**: There is no type restriction for this parameter in the exported symbol. 531 532- **func**: There is no type restriction for this parameter in the exported symbol. 533 534**NOTE** 535 536- In OpenHarmony, the **cleanup hook** method is not registered when a thread-safe function is created. You can call **napi_add_env_cleanup_hook** if required. 537 538### napi_call_threadsafe_function 539 540**NOTE** 541 542- Before **uv_async_send** is called in OpenHarmony, **env** is checked. 543 544- If **uv_async_send** fails to be called, the exported symbol returns **napi_generic_failure**. 545 546### napi_release_threadsafe_function 547 548**NOTE** 549 550- Before **uv_async_send** is called in OpenHarmony, **env** is checked. 551 552- If **ThreadCount** is **0**, the exported symbol returns **napi_generic_failure**. 553 554### napi_ref_threadsafe_function 555 556**NOTE** 557 558- The exported symbol checks whether **func** and **env** belong to the same ArkTS thread. If not, **napi_generic_failure** is returned. 559 560### napi_unref_threadsafe_function 561 562**NOTE** 563 564- The exported symbol checks whether **func** and **env** belong to the same ArkTS thread. If not, **napi_generic_failure** is returned. 565 566### napi_create_date 567 568**Return value** 569 570- If the input parameters are correct but **date** fails to be created, the native symbol returns **napi_generic_failure**. In OpenHarmony, an exception is thrown, and the exported symbol returns **napi_pending_exception**. 571 572### napi_create_bigint_words 573 574**Return value** 575 576- If the input parameters are correct but bigInt fails to be created, the native symbol returns **napi_generic_failure**. In OpenHarmony, an exception is thrown, and the exported symbol returns **napi_pending_exception**. 577 578### napi_get_value_bigint_words 579 580**Return value** 581 582- If **value** is not a BigInt object, the exported symbol returns **napi_object_expected**. 583 584### napi_create_buffer 585 586**Return value** 587 588- The buffer created in OpenHarmony is of the ArrayBufferLike type. 589 590- If **size** is less than or equal to **0**, the exported symbol returns **napi_invalid_arg**. 591 592- If **size** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 593 594- If **data** is **nullptr**, the exported symbol returns **napi_invalid_arg**. 595 596- If an exception occurs before the native symbol is called or exited, **napi_pending_exception** is returned. There is no such verification in OpenHarmony. 597 598### napi_create_buffer_copy 599 600**Return value** 601 602- The buffer created in OpenHarmony is of the ArrayBufferLike type. 603 604- If **length** is less than or equal to **0**, the exported symbol returns **napi_invalid_arg**. 605 606- If **length** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 607 608- If **data** is **nullptr**, the exported symbol returns **napi_invalid_arg**. 609 610- If an exception occurs before the native symbol is called or exited, **napi_pending_exception** is returned. There is no such verification in OpenHarmony. 611 612### napi_create_external_buffer 613 614**Return value** 615 616- The buffer created in OpenHarmony is of the ArrayBufferLike type. 617 618- If **length** is less than or equal to **0**, the exported symbol returns **napi_invalid_arg**. 619 620- If **length** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 621 622- 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**. 623 624### napi_get_buffer_info 625 626**Return value** 627 628- OpenHarmony checks whether the value belongs to **buffer**. If not, **napi_arraybuffer_expected** is returned. 629 630### napi_detach_arraybuffer 631 632**Return value** 633 634- If **arraybuffer** is not an object, the exported symbol returns **napi_object_expected**. If **arraybuffer** is an object but not an **ArrayBuffer** object, it returns **napi_invalid_arg**. 635 636### napi_add_env_cleanup_hook 637 638**NOTE** 639 640- If data is registered with **env**, OpenHarmony prints only error logs. 641 642### napi_add_finalizer 643 644**Return value** 645 646- If **js_object** is not an object, the exported symbol returns **napi_object_expected**. 647 648**NOTE** 649 650- In OpenHarmony, when a strong reference is deleted, this callback is directly invoked without waiting for the destruction of the object. 651 652- If the callback throws an exception, OpenHarmony triggers JSCrash. 653 654**NOTE** 655 656- The native symbol returns a weak reference, whereas the exported symbol returns a strong reference if **result** is not empty. 657 658### napi_fatal_exception 659 660**Parameters** 661 662- **err**: The exported symbol supports only the **Error** type. If the type does not match, **napi_invalid_arg** is returned. 663 664### napi_get_uv_event_loop 665 666**Return value** 667 668- If **env** is not a valid **napi_env** (for example, it is a released **env**), the exported symbol returns **napi_generic_failure**. 669 670### napi_create_array_with_length 671 672**Return value** 673 674- If **length** is too large, the native symbol throws an exception and interrupts the process. OpenHarmony attempts to allocate memory. If the memory allocation fails, an exception is thrown and an array with length of 0 is returned. 675 676### napi_create_arraybuffer 677 678**Return value** 679 680- If **length** is too large, the native symbol throws an exception and interrupts the process. OpenHarmony attempts to allocate memory. If the memory allocation fails, an exception is thrown and **undefined** is returned. 681 682## Symbols Not Exported from the Node-API Library 683 684|Symbol Type|Symbol|Description| 685| --- | --- | --- | 686|FUNC|napi_adjust_external_memory|Adjusts the external memory held by a JS object.| 687 688## Node-API Extended Symbols 689 690|Symbol Type|Symbol|Description|Start API Version| 691| --- | --- | --- | --- | 692|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| 693|FUNC|napi_run_script_path|Runs an ABC file.|10| 694|FUNC|napi_load_module|Loads an .abc file as a module. This API returns the namespace of the module.|11| 695|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| 696|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| 697|FUNC|napi_coerce_to_native_binding_object|Forcibly binds a JS object and a native object.|11| 698|FUNC|napi_create_ark_runtime|Creates an ArkTS runtime environment.|12| 699|FUNC|napi_destroy_ark_runtime|Destroys the ArkTS runtime environment.|12| 700|FUNC|napi_run_event_loop|Runs the underlying event loop.|12| 701|FUNC|napi_stop_event_loop|Stops the underlying event loop.|12| 702|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| 703|FUNC|napi_serialize|Converts an ArkTS object into native data.|12| 704|FUNC|napi_deserialize|Converts native data into an ArkTS object.|12| 705|FUNC|napi_delete_serialization_data|Deletes serialized data.|12| 706|FUNC|napi_call_threadsafe_function_with_priority|Calls a task with the specified priority and enqueuing mode into the ArkTS main thread.|12| 707|FUNC|napi_is_sendable|Checks whether the given JS value is sendable.|12| 708|FUNC|napi_define_sendable_class|Creates a sendable class.|12| 709|FUNC|napi_create_sendable_object_with_properties | Creates a sendable object with the given **napi_property_descriptor**.|12| 710|FUNC|napi_create_sendable_array | Creates a sendable array.|12| 711|FUNC|napi_create_sendable_array_with_length | Creates a sendable array of the specified length.|12| 712|FUNC|napi_create_sendable_arraybuffer | Creates a sendable **ArrayBuffer**.|12| 713|FUNC|napi_create_sendable_typedarray | Creates a sendable **TypedArray**.|12| 714|FUNC|napi_wrap_sendable | Wraps a native instance into an ArkTS object.|12| 715|FUNC|napi_wrap_sendable_with_size | Wraps a native instance into an ArkTS object with the specified size.|12| 716|FUNC|napi_unwrap_sendable | Unwraps the native instance from an ArkTS object.|12| 717|FUNC|napi_remove_wrap_sendable | Removes and obtains the native instance wrapped by an ArkTS object. After removal, the callback will no longer be triggered and must be manually deleted to free memory.|12| 718|FUNC|napi_wrap_enhance | Wraps a Node-API instance into an ArkTS object and specifies the instance size. You can specify whether to execute the registered callback asynchronously (if asynchronous, it must be thread-safe).|18| 719|FUNC|napi_create_ark_context|Creates a new runtime context environment.|20| 720|FUNC|napi_switch_ark_context|Switches to the specified runtime context environment.|20| 721|FUNC|napi_destroy_ark_context|Destroys a context environment created by **napi_create_ark_context**.|20| 722 723> **NOTE** 724> 725> For details about the sendable feature, see [Sendable Object Overview](../../arkts-utils/arkts-sendable.md). 726 727### napi_qos_t 728 729```cpp 730typedef enum { 731 napi_qos_background = 0, // Low priority for works invisible to users, such as data synchronization and backup. 732 napi_qos_utility = 1, // Medium priority for works that do not require immediate response, such as downloading or importing data. 733 napi_qos_default = 2, // Default priority. 734 napi_qos_user_initiated = 3, // High priority for user-triggered works with visible progress, for example, opening a file. 735} napi_qos_t; 736``` 737 738**Description** 739Enumerates the QoS levels, which determine the priority of thread scheduling. 740 741### napi_event_mode 742 743```cpp 744typedef enum { 745 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. 746 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. 747} napi_event_mode; 748``` 749 750**Description** 751Enumerates the modes for running the underlying event loop. 752 753### napi_queue_async_work_with_qos 754 755```cpp 756napi_status napi_queue_async_work_with_qos(napi_env env, 757 napi_async_work work, 758 napi_qos_t qos); 759``` 760 761**Description** 762 763Adds an async work object to the queue so that it can be scheduled for execution based on the QoS priority passed in. 764 765**Parameters** 766 767- **env**: environment, in which the API is invoked. 768 769- **work**: handle to the async work object to schedule. This object is created by **napi_create_async_work**. 770 771- **qos**: priority of the task to schedule. 772 773**Return value** 774 775**napi_ok** if the operation is successful. 776 777### napi_run_script_path 778 779```cpp 780napi_status napi_run_script_path(napi_env env, 781 const char* abcPath, 782 napi_value* result); 783``` 784 785**Description** 786 787Runs an .abc file. 788 789**Parameters** 790 791- **env**: environment, in which the API is invoked. 792 793- **abcPath**: JS path of the script to run. The value is a string that specifies the location of the script file to run. 794 795- **result**: pointer to **napi_value**, which holds the script execution result. 796 797**Return value** 798 799**napi_ok** if the operation is successful. 800 801### napi_load_module 802 803```cpp 804napi_status napi_load_module(napi_env env, 805 const char* path, 806 napi_value* result); 807``` 808 809**Description** 810 811Loads a system module or a customized module. This API returns the namespace of the module loaded. 812 813**Parameters** 814 815- **env**: environment, in which the API is invoked. 816 817- **path**: name of the system module to load or path of the customized module to load. 818 819- **result**: pointer to **napi_value**, which holds the module loading result. 820 821**Return value** 822 823**napi_ok** if the operation is successful. 824 825### napi_create_object_with_properties 826 827```cpp 828napi_status napi_create_object_with_properties(napi_env env, 829 napi_value* result, 830 size_t property_count, 831 const napi_property_descriptor* properties); 832``` 833 834**Description** 835 836Creates a JS object using the given **napi_property_descriptor**.<br>**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. 837 838 The key in **napi_property_descriptor** must be a string that cannot be converted into a number. 839 840**Parameters** 841 842- **env**: environment, in which the API is invoked. 843 844- **result**: pointer to **napi_value**, which holds the created object. 845 846- **property_count**: number of properties to be added to the object. 847 848- **properties**: pointer to a **napi_property_descriptor** array containing information about the properties to be added to the object. 849 850**Return value** 851 852**napi_ok** if the operation is successful. 853 854### napi_create_object_with_named_properties 855 856```cpp 857napi_status napi_create_object_with_named_properties(napi_env env, 858 napi_value* result, 859 size_t property_count, 860 const char** keys, 861 const napi_value* values); 862``` 863 864**Description** 865 866Creates a JS object using the given **napi_value**s and keys. The key must be a string and cannot be converted into a number. 867 868**Parameters** 869 870- **env**: environment, in which the API is invoked. 871 872- **result**: pointer to **napi_value**, which holds the created object. 873 874- **property_count**: number of properties to be added to the object. 875 876- **keys**: pointer to a const char array containing the keys of the properties to add. 877 878- **values**: pointer to a **napi_value** array containing the properties to add. The keys and properties are in one-to-one mapping. 879 880**Return value** 881 882**napi_ok** if the operation is successful. 883 884### napi_coerce_to_native_binding_object 885 886```cpp 887napi_status napi_coerce_to_native_binding_object(napi_env env, 888 napi_value js_object, 889 napi_native_binding_detach_callback detach_cb, 890 napi_native_binding_attach_callback attach_cb, 891 void* native_object, 892 void* hint); 893``` 894 895**Description** 896 897Converts a JS object into an object carrying native information by forcibly binding callbacks and callback data to the JS object. 898 899**Parameters** 900 901- **env**: environment, in which the API is invoked. 902 903- **js_object**: JS object to convert. 904 905- **detach_cb**: callback to be invoked to perform cleanup operations when the object is detached during serialization. 906 907- **attach_cb**: callback to be invoked when the object is attached during serialization. 908 909- **native_object**: parameters to be passed to the callbacks. This object cannot be empty. 910 911- **hint**: pointer to the additional information to be passed to the callbacks. 912 913**Return value** 914 915**napi_ok** if the operation is successful. 916 917### napi_create_ark_runtime 918 919```cpp 920napi_status napi_create_ark_runtime(napi_env *env) 921``` 922 923**Description** 924 925Creates a runtime environment. A process allows up to 64 instances, and the total number of child threads, including those created by [Worker](../../arkts-utils/worker-introduction.md), cannot exceed 80. 926 927**Parameters** 928 929- **env**: environment, in which the API is invoked. 930 931**Return value** 932 933**napi_ok** if the operation is successful. 934 935### napi_destroy_ark_runtime 936 937```cpp 938napi_status napi_destroy_ark_runtime(napi_env *env) 939``` 940 941**Description** 942 943Destroys an ArkTS runtime environment. 944 945**Parameters** 946 947- **env**: environment, in which the API is invoked. 948 949**Return value** 950 951**napi_ok** if the operation is successful. 952 953### napi_run_event_loop 954 955```cpp 956napi_status napi_run_event_loop(napi_env env, napi_event_mode mode) 957``` 958 959**Description** 960 961Runs the underlying event loop. 962 963**Parameters** 964 965- **env**: environment, in which the API is invoked. 966- **mode**: event mode for running the event loop. 967 968**Return value** 969 970**napi_ok** if the operation is successful. 971 972### napi_stop_event_loop 973 974```cpp 975napi_status napi_stop_event_loop(napi_env env) 976``` 977 978**Description** 979 980Stops the underlying event loop. 981 982**Parameters** 983 984- **env**: environment, in which the API is invoked. 985 986**Return value** 987 988**napi_ok** if the operation is successful. 989 990### napi_load_module_with_info 991 992```cpp 993napi_status napi_load_module_with_info(napi_env env, 994 const char* path, 995 const char* module_info, 996 napi_value* result) 997``` 998 999**Description** 1000 1001Loads 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. 1002 1003**Parameters** 1004 1005- **env**: environment, in which the API is invoked. 1006 1007- **path**: path of the module to load. 1008 1009- **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. 1010 1011- **result**: pointer to **napi_value**, which holds the module loading result. 1012 1013**Return value** 1014 1015**napi_ok** if the operation is successful. 1016 1017### napi_serialize 1018 1019```cpp 1020napi_status napi_serialize(napi_env env, 1021 napi_value object, 1022 napi_value transfer_list, 1023 napi_value clone_list, 1024 void** result) 1025``` 1026 1027**Description** 1028 1029Converts an ArkTS object into native data. 1030 1031**Parameters** 1032 1033- **env**: environment, in which the API is invoked. 1034 1035- **object**: JS object to be serialized. 1036 1037- **transfer_list**: list of JS objects to be passed during serialization. 1038 1039- **clone_list**: list of JS objects to be cloned during serialization. 1040 1041- **result**: pointer to the serialization result. After the call is complete, the pointer to the native data converted is stored in this position. 1042 1043**Return value** 1044 1045**napi_ok** if the operation is successful. 1046 1047### napi_deserialize 1048 1049```cpp 1050napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object) 1051``` 1052 1053**Description** 1054 1055Converts native data into an ArkTS object. 1056 1057**Parameters** 1058 1059- **env**: environment, in which the API is invoked. 1060 1061- **buffer**: pointer to the binary data, which needs to be deserialized into a JS object. 1062 1063- **object**: pointer to the deserialized JS object. 1064 1065**Return value** 1066 1067**napi_ok** if the operation is successful. 1068 1069### napi_delete_serialization_data 1070 1071```cpp 1072napi_status napi_delete_serialization_data(napi_env env, void* buffer) 1073``` 1074 1075**Description** 1076 1077Deletes serialized data. 1078 1079**Parameters** 1080 1081- **env**: environment, in which the API is invoked. 1082 1083- **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. 1084 1085**Return value** 1086 1087**napi_ok** if the operation is successful. 1088 1089### napi_call_threadsafe_function_with_priority 1090 1091```cpp 1092napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 1093 void *data, 1094 napi_task_priority priority, 1095 bool isTail) 1096``` 1097 1098**Description** 1099 1100Calls a task with the specified priority and enqueuing mode into the ArkTS main thread. 1101 1102**Parameters** 1103 1104- **func**: thread-safe function object, which is returned when a thread-safe function is created. 1105 1106- **data**: pointer to the data to be passed to the JS callback function. 1107 1108- **priority**: priority of the task that calls the JS callback function. 1109 1110- **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. 1111 1112**Return value** 1113 1114**napi_ok** if the operation is successful. 1115 1116### napi_is_sendable 1117 1118```cpp 1119napi_status napi_is_sendable(napi_env env, napi_value value, bool* result) 1120``` 1121 1122**Description** 1123 1124Checks whether the given JS value is sendable. 1125 1126**Parameters** 1127 1128- **env**: environment, in which the API is invoked. 1129 1130- **value**: JS value to check. 1131 1132- **result**: pointer of the bool type, indicating whether the JS value is sendable. 1133 1134**Return value** 1135 1136**napi_ok** if the operation is successful. 1137 1138 1139### napi_define_sendable_class 1140 1141```cpp 1142napi_status napi_define_sendable_class(napi_env env, 1143 const char* utf8name, 1144 size_t length, 1145 napi_callback constructor, 1146 void* data, 1147 size_t property_count, 1148 const napi_property_descriptor* properties, 1149 napi_value parent, 1150 napi_value* result) 1151 1152 1153``` 1154 1155**Description** 1156 1157Creates a sendable class. 1158 1159**Parameters** 1160 1161- **env**: environment, in which the API is invoked. 1162 1163- **utf8name**: pointer to the name of the class to create. This parameter is of the const char* type. 1164 1165- **length**: length of the class name, in bytes. This parameter is of the size_t type. 1166 1167- **constructor**: constructor of the class. This parameter is of the napi_callback type. 1168 1169- **data**: (optional) pointer to the additional data of the constructor. This parameter is of the void* type. 1170 1171- **property_count**: number of properties of the class. This parameter is of the size_t type. 1172 1173- **properties**: (optional) pointer to the descriptors of the properties. This parameter of the const napi_property_descriptor* type. 1174 1175- **parent**: (optional) parent class of the class to create. This parameter is of the napi_value type. 1176 1177- **result**: pointer to the sendable class created. This parameter is of the napi_value type. 1178 1179**Return value** 1180 1181**napi_ok** if the operation is successful. 1182 1183### napi_create_sendable_object_with_properties 1184 1185```cpp 1186napi_status napi_create_sendable_object_with_properties(napi_env env, 1187 size_t property_count, 1188 const napi_property_descriptor* properties, 1189 napi_value* result) 1190``` 1191 1192**Description** 1193 1194Creates a sendable object with the given **napi_property_descriptor**. 1195 1196**Parameters** 1197 1198- **env**: environment, in which the API is invoked. 1199 1200- **property_count**: number of properties of the class. This parameter is of the size_t type. 1201 1202- **properties**: pointer to the descriptors of the properties. This parameter of the const napi_property_descriptor* type. 1203 1204- **result**: pointer to the sendable class created. This parameter is of the napi_value type. 1205 1206**Return value** 1207 1208**napi_ok** if the operation is successful. 1209 1210### napi_create_sendable_array 1211 1212```cpp 1213napi_status napi_create_sendable_array(napi_env env, napi_value* result) 1214``` 1215 1216**Description** 1217 1218Creates a sendable array. 1219 1220**Parameters** 1221 1222- **env**: environment, in which the API is invoked. 1223 1224- **result**: pointer to the sendable array created. This parameter is of the napi_value type. 1225 1226**Return value** 1227 1228**napi_ok** if the operation is successful. 1229 1230### napi_create_sendable_array_with_length 1231 1232```cpp 1233napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result) 1234``` 1235 1236**Description** 1237 1238Creates a sendable array of the specified length. 1239 1240**Parameters** 1241 1242- **env**: environment, in which the API is invoked. 1243 1244- **length**: length of the sendable array to create. 1245 1246- **result**: pointer to the sendable array created. This parameter is of the napi_value type. 1247 1248**Return value** 1249 1250**napi_ok** if the operation is successful. 1251 1252### napi_create_sendable_arraybuffer 1253 1254```cpp 1255napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result) 1256``` 1257 1258**Description** 1259 1260Creates a sendable **ArrayBuffer**. 1261 1262**Parameters** 1263 1264- **env**: environment, in which the API is invoked. 1265 1266- **byte_length**: length of the ArrayBuffer to create. 1267 1268- **data**: pointer to the byte buffer for storing the ArrayBuffer created. 1269 1270- **result**: pointer to the ArrayBuffer created. This parameter is of the napi_value type. 1271 1272**Return value** 1273 1274**napi_ok** if the operation is successful. 1275 1276### napi_create_sendable_typedarray 1277 1278```cpp 1279napi_status napi_create_sendable_typedarray(napi_env env, 1280 napi_typedarray_type type, 1281 size_t length, 1282 napi_value arraybuffer, 1283 size_t byte_offset, 1284 napi_value* result); 1285``` 1286 1287**Description** 1288 1289Creates a sendable **TypedArray**. 1290 1291**Parameters** 1292 1293- **env**: environment, in which the API is invoked. 1294 1295- **type**: type of the TypedArray to create. 1296 1297- **length**: length of the TypedArray to create. 1298 1299- **arraybuffer**: ArrayBuffer instance to create. 1300 1301- **byte_offset**: offset of the ArrayBuffer. 1302 1303- **result**: pointer to the TypedArray created. This parameter is of the napi_value type. 1304 1305**Return value** 1306 1307**napi_ok** if the operation is successful. 1308 1309### napi_wrap_sendable 1310 1311```cpp 1312napi_status napi_wrap_sendable(napi_env env, 1313 napi_value js_object, 1314 void* native_object, 1315 napi_finalize finalize_cb, 1316 void* finalize_hint); 1317``` 1318 1319**Description** 1320 1321Wraps a native instance into an ArkTS object. 1322 1323**Parameters** 1324 1325- **env**: environment, in which the API is invoked. 1326 1327- **js_object**: ArkTS object. 1328 1329- **native_object**: pointer to the native instance to be wrapped in the ArkTS object. 1330 1331- **napi_finalize**: (optional) callback to be invoked when the ArkTS object is destroyed. 1332 1333- **finalize_hint**: (optional) pointer to the callback context, which will be passed to the callback. 1334 1335**Return value** 1336 1337**napi_ok** if the operation is successful. 1338 1339### napi_wrap_sendable_with_size 1340 1341```cpp 1342napi_status napi_wrap_sendable_with_size(napi_env env, 1343 napi_value js_object, 1344 void* native_object, 1345 napi_finalize finalize_cb, 1346 void* finalize_hint, 1347 size_t native_binding_size); 1348``` 1349 1350**Description** 1351 1352Wraps a native instance into an ArkTS object with the specified size. 1353 1354**Parameters** 1355 1356- **env**: environment, in which the API is invoked. 1357 1358- **js_object**: ArkTS object. 1359 1360- **native_object**: pointer to the native instance to be wrapped in the ArkTS object. 1361 1362- **napi_finalize**: (optional) callback to be invoked when the ArkTS object is destroyed. 1363 1364- **finalize_hint**: (optional) pointer to the callback context, which will be passed to the callback. 1365 1366- **native_binding_size**: (optional) size of the native instance wrapped. 1367 1368**Return value** 1369 1370**napi_ok** if the operation is successful. 1371 1372### napi_unwrap_sendable 1373 1374```cpp 1375napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result) 1376``` 1377 1378**Description** 1379 1380Unwraps the native instance from an ArkTS object. 1381 1382**Parameters** 1383 1384- **env**: environment, in which the API is invoked. 1385 1386- **js_object**: ArkTS object. 1387 1388- **result**: double pointer to the native instance unwrapped. 1389 1390**Return value** 1391 1392**napi_ok** if the operation is successful. 1393 1394### napi_remove_wrap_sendable 1395 1396```cpp 1397napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result) 1398``` 1399 1400**Description** 1401 1402Removes and obtains the native instance wrapped by an ArkTS object. After removal, the callback will no longer be triggered and must be manually deleted to free memory. 1403 1404**Parameters** 1405 1406- **env**: environment, in which the API is invoked. 1407 1408- **js_object**: ArkTS object. 1409 1410- **result**: double pointer to the native instance unwrapped. 1411 1412**Return value** 1413 1414**napi_ok** if the operation is successful. 1415 1416### napi_wrap_enhance 1417 1418```cpp 1419napi_status napi_wrap_enhance(napi_env env, 1420 napi_value js_object, 1421 void* native_object, 1422 napi_finalize finalize_cb, 1423 bool async_finalizer, 1424 void* finalize_hint, 1425 size_t native_binding_size, 1426 napi_ref* result); 1427``` 1428 1429**Description** 1430 1431Wraps a Node-API instance into an ArkTS object and specifies the instance size. You can specify whether to execute the registered callback asynchronously (if asynchronous, it must be thread-safe). 1432 1433**Parameters** 1434 1435- **env**: environment, in which the API is invoked. 1436 1437- **js_object**: ArkTS object. 1438 1439- **native_object**: pointer to the native instance to be wrapped in the ArkTS object. 1440 1441- **finalize_cb**: (optional) callback to be called when the ArkTS object is destroyed. For details, see [napi_finalize](#napi_finalize callback function description). 1442 1443- **async_finalizer**: a Boolean value used to indicate whether to execute the **finalize_cb** callback asynchronously. The value **true** means to execute the callback asynchronously. In this case, thread safety must be ensured. The value **false** means to execute the callback synchronously. 1444 1445- **finalize_hint**: (optional) pointer to the callback context, which will be passed to the callback. 1446 1447- **native_binding_size**: (optional) size of the native instance wrapped. 1448 1449- **result**: (optional) pointer to the ArkTS object reference. 1450 1451**Return value** 1452 1453- **napi_ok**: The operation is successful. 1454 1455- **napi_invalid_arg**: The **env**, **js_object**, or **native_object** parameter is null. 1456 1457- **napi_object_expected**: The **js_object** parameter is not an ArkTs object or function. 1458 1459- **napi_pending_exception**: An uncaught exception or an exception occurs during the execution. 1460 1461### napi_create_ark_context 1462 1463```cpp 1464napi_status napi_create_ark_context(napi_env env, napi_env* newEnv); 1465``` 1466 1467**Description** 1468 1469Creates a new runtime context environment. 1470 1471Note the following when using this API: 1472 14731. Only new context environments created through the initial context environment are supported. It is prohibited to create new context environments using the context environment created by this API. 14742. Currently, this API cannot be called on ArkTS threads that are not the main thread. 14753. Before calling this API, ensure that the current context environment is normal. Otherwise, the API call fails. 14764. The context environment created by this API can only load some native.so files of ArkUI. Loading application-specific native .so files and common basic library native so files is not supported. 14775. The multi-context runtime environment does not support the sendable feature. 14786. The runtime context environment created through **napi_create_ark_context** does not support module capabilities such as console and timer. 1479 1480**Parameters** 1481 1482- **env**: environment, in which the API is invoked. 1483 1484- newEnv: pointer to the new runtime context environment. 1485 1486**Return value** 1487 1488**napi_ok** if the operation is successful. 1489 1490### napi_switch_ark_context 1491 1492```cpp 1493napi_status napi_switch_ark_context(napi_env env) 1494``` 1495 1496**Description** 1497 1498Switches to the specified runtime context environment. Note the following when using this API: 1499 15001. Currently, this API does not support calls in ArkTS threads that are not the main thread. 15012. Before calling this API, ensure that the current context environment is normal. Otherwise, the API call fails. 1502 1503**Parameters** 1504 1505- env: specified runtime context environment. 1506 1507**Return value** 1508 1509**napi_ok** if the operation is successful. 1510 1511### napi_destroy_ark_context 1512 1513```cpp 1514napi_status napi_destroy_ark_context(napi_env env) 1515``` 1516 1517**Description** 1518 1519Destroys a context environment created by **napi_create_ark_context**. Note the following when using this API: 1520 15211. Currently, this API does not support calls in ArkTS threads that are not the main thread. 15222. This API can only be used to destroy runtime context environments created by calling **napi_create_ark_context**. 15233. You cannot use this API to destroy a context environment that is currently in use. 1524 1525**Parameters** 1526 1527- env: runtime context to be destroyed. 1528 1529**Return value** 1530 1531**napi_ok** if the operation is successful. 1532 1533### **napi_finalize** description 1534 1535```cpp 1536typedef void (*napi_finalize)(napi_env env, 1537 void* finalize_data, 1538 void* finalize_hint); 1539``` 1540 1541**Description** 1542 1543Called when the lifecycle of a Node-API object ends. 1544 1545**Parameters** 1546 1547- **env**: environment, in which the API is invoked. 1548 1549- **finalize_data**: pointer to the user data to be cleared. 1550 1551- **finalize_hint**: context hint, which is used to assist the clear process. 1552 1553**Return value** 1554 1555- **void**: no return value. 1556 1557<!--no_check--> 1558