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 outer 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 181For 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". 182 183### napi_throw_error 184 185**Return value** 186 187- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 188 189- The exported symbol permits a failure in setting **code**. 190 191### napi_throw_type_error 192 193**Return value** 194 195- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 196 197- The exported symbol permits a failure in setting **code**. 198 199### napi_throw_range_error 200 201**Return value** 202 203- If **code** is a null pointer, the native symbol returns **napi_invalid_arg**, whereas the exported symbol does not check the validity of **code**. 204 205- The exported symbol permits a failure in setting **code**. 206 207### napi_create_error 208 209**Parameters** 210 211- **code**: The value type can be string or number in the exported symbol. 212 213**Return value** 214 215- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 216 217- The exported symbol permits a failure in setting **code**. 218 219### napi_create_type_error 220 221**Parameters** 222 223- **code**: The value type can be string or number in the exported symbol. 224 225**Return value** 226 227- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 228 229- The exported symbol permits a failure in setting **code**. 230 231- The error type created in OpenHarmony is **Error**. 232 233### napi_create_range_error 234 235**Parameters** 236 237- **code**: The value type can be string or number in the exported symbol. 238 239**Return value** 240 241- If the code type is incorrect, the exported symbol returns **napi_invalid_arg**. 242 243- The exported symbol permits a failure in setting **code**. 244 245- The error type created in OpenHarmony is **Error**. 246 247### napi_create_reference 248 249**Parameters** 250 251- **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. 252 253### napi_delete_reference 254 255**NOTE** 256 257- In OpenHarmory, if the **napi_finalize** callback is registered when a strong reference is created, calling this API will trigger the **napi_finalize** callback. 258 259### napi_create_symbol 260 261**Return value** 262 263- The exported symbol returns **napi_invalid_arg** if **description** is not empty and is not a string. 264 265### napi_create_typedarray 266 267**Return value** 268 269- The exported symbol returns **napi_arraybuffer_expected** if **arraybuffer** is not empty and is not an **ArrayBuffer** object. 270 271### napi_create_dataview 272 273**Return value** 274 275- The exported symbol returns **napi_arraybuffer_expected** if **arraybuffer** is not empty and is not an **ArrayBuffer** object. 276 277- 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**. 278 279### napi_get_typedarray_info 280 281**Parameters** 282 283- **object**: The value type can be TypedArray or [Sendable TypedArray](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) in the exported symbol. 284 285### napi_coerce_to_object 286 287**Return value** 288 289- If **value** is **undefined** or null, the exported symbol returns **napi_ok** and **undefined** in **result**. 290 291### napi_instanceof 292 293**Return value** 294 295- If **object** is not an object, the exported symbol returns **napi_object_expected** with **result** unprocessed. 296 297- If **constructor** is not a function object, the exported symbol returns **napi_function_expected** without throwing any exception. 298 299### napi_is_typedarray 300 301**Parameters** 302 303- **value**: The exported symbol also supports the [Sendable TypedArray](../apis-arkts/js-apis-arkts-collections.md#collectionstypedarray) type for **value**. 304 305### napi_get_property_names 306 307**Return value** 308 309- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 310 311### napi_set_property 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_get_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_has_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_delete_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_has_own_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_set_named_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_get_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_has_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_set_element 360 361**Return value** 362 363- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 364 365- 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. 366 367### napi_get_element 368 369**Return value** 370 371- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 372 373### napi_has_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_delete_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_define_properties 386 387**Return value** 388 389- If **object** is not an object or a function, the exported symbol returns **napi_object_expected**. 390 391- 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. 392 393### napi_type_tag_object 394 395**Return value** 396 397- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 398 399### napi_check_object_type_tag 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_call_function 406 407**Return value** 408 409- The export symbol does not check whether the **recv** parameter is **nullptr**. 410 411- If **func** is not a function, the export symbol returns **napi_function_expected**. 412 413### napi_new_instance 414 415**Return value** 416 417- If **constructor** is not a function, the export symbol returns **napi_function_expected**. 418 419### napi_define_class 420 421**Return value** 422 423- If **length** is not **NAPI_AUTO_LENGTH** and is greater than **INT_MAX**, the exported symbol returns **napi_object_expected**. 424 425### napi_wrap 426 427**Parameters** 428 429- **finalize_cb**: It can be empty in the native symbol. If this parameter is empty, the exported symbol returns **napi_invalid_arg**. 430- **result**: The native symbol returns a weak reference, whereas the exported symbol returns a strong reference if **result** is not empty. 431 432**Return value** 433 434- If **js_object** is not an object or a function, the exported symbol returns **napi_object_expected**. 435 436### napi_unwrap 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_remove_wrap 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**NOTE** 449 450- If the wrap is associated with the **finalize** callback, the export symbol will call **finalize()** before removing the wrap. 451 452### napi_create_async_work 453 454**Parameters** 455 456- The exported symbol does not support **async_hooks**. 457 458- The exported symbol does not check whether the input parameter **async_resource_name** is a string. 459 460- The exported symbol does not process the input parameter **async_resource** because it does not support **async_hooks**. 461 462### napi_delete_async_work 463 464**Parameters** 465 466- The exported symbol does not support **async_hooks**. 467 468### napi_queue_async_work 469 470**Parameters** 471 472- The exported symbol does not support **async_hooks**. 473 474### napi_cancel_async_work 475 476**Return value** 477 478- 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. 479 480### napi_async_init 481 482**NOTE** 483 484- Currently, OpenHarmony does not support **async_hooks**. After the exported symbol is called, operations related to **async_hooks** will not be performed. 485 486### napi_make_callback 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_async_destroy 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_get_node_version 499 500**NOTE** 501 502- OpenHarmony does not need to obtain the node version. Therefore, the export symbol is an empty implementation. 503 504### napi_resolve_deferred 505 506**NOTE** 507 508- 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. 509 510### napi_reject_deffered 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_create_threadsafe_function 517 518**Parameters** 519 520- **initial_thread_count**: The maximum value is **128** in the exported symbol. 521 522- **async_resource**: There is no type restriction for this parameter in the exported symbol. 523 524- **async_resource_name**: There is no type restriction for this parameter in the exported symbol. 525 526- **func**: There is no type restriction for this parameter in the exported symbol. 527 528**NOTE** 529 530- 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. 531 532### napi_call_threadsafe_function 533 534**NOTE** 535 536- Before **uv_async_send** is called in OpenHarmony, **env** is checked. 537 538- If **uv_async_send** fails to be called, the exported symbol returns **napi_generic_failure**. 539 540### napi_release_threadsafe_function 541 542**NOTE** 543 544- Before **uv_async_send** is called in OpenHarmony, **env** is checked. 545 546- If **ThreadCount** is **0**, the exported symbol returns **napi_generic_failure**. 547 548### napi_ref_threadsafe_function 549 550**NOTE** 551 552- The exported symbol checks whether **func** and **env** belong to the same ArkTS thread. If not, **napi_generic_failure** is returned. 553 554### napi_unref_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_create_date 561 562**Return value** 563 564- 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**. 565 566### napi_create_bigint_words 567 568**Return value** 569 570- 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**. 571 572### napi_get_value_bigint_words 573 574**Return value** 575 576- If **value** is not a BigInt object, the exported symbol returns **napi_object_expected**. 577 578### napi_create_buffer 579 580**Return value** 581 582- The buffer created in OpenHarmony is of the ArrayBufferLike type. 583 584- If **size** is **0**, the exported symbol returns **napi_invalid_arg**. 585 586- If **size** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 587 588- If **data** is **nullptr**, the exported symbol returns **napi_invalid_arg**. 589 590- If an exception occurs before the native symbol is called or exited, **napi_pending_exception** is returned. There is no such verification in OpenHarmony. 591 592### napi_create_buffer_copy 593 594**Return value** 595 596- The buffer created in OpenHarmony is of the ArrayBufferLike type. 597 598- If **size** is **0**, the exported symbol returns **napi_invalid_arg**. 599 600- If **size** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 601 602- If **data** is **nullptr**, the exported symbol returns **napi_invalid_arg**. 603 604- If an exception occurs before the native symbol is called or exited, **napi_pending_exception** is returned. There is no such verification in OpenHarmony. 605 606### napi_create_external_buffer 607 608**Return value** 609 610- The buffer created in OpenHarmony is of the ArrayBufferLike type. 611 612- If **size** is **0**, the exported symbol returns **napi_invalid_arg**. 613 614- If **size** is greater than **2097152**, the exported symbol returns **napi_invalid_arg** and logs an error. 615 616- 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**. 617 618### napi_get_buffer_info 619 620**Return value** 621 622- OpenHarmony checks whether the value belongs to **buffer**. If not, **napi_arraybuffer_expected** is returned. 623 624### napi_detach_arraybuffer 625 626**Return value** 627 628- 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**. 629 630### napi_add_env_cleanup_hook 631 632**NOTE** 633 634- If data is registered with **env**, OpenHarmony prints only error logs. 635 636### napi_add_finalizer 637 638**Return value** 639 640- If **js_object** is not an object, the exported symbol returns **napi_object_expected**. 641 642**NOTE** 643 644- In OpenHarmony, when a strong reference is deleted, this callback is directly invoked without waiting for the destruction of the object. 645 646- If the callback throws an exception, OpenHarmony triggers JSCrash. 647 648**NOTE** 649 650- The native symbol returns a weak reference, whereas the exported symbol returns a strong reference if **result** is not empty. 651 652### napi_fatal_exception 653 654**Parameters** 655 656- **err**: The exported symbol supports only the **Error** type. If the type does not match, **napi_invalid_arg** is returned. 657 658### napi_get_uv_event_loop 659 660**Return value** 661 662- If **env** is not a valid **napi_env** (for example, it is a released **env**), the exported symbol returns **napi_generic_failure**. 663 664### napi_create_array_with_length 665 666**Return value** 667 668- 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. 669 670### napi_create_arraybuffer 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 **undefined** is returned. 675 676## Symbols Not Exported from the Node-API Library 677 678|Symbol Type|Symbol|Description| 679| --- | --- | --- | 680|FUNC|napi_adjust_external_memory|Adjusts the external memory held by a JS object.| 681 682## Node-API Extended Symbols 683 684|Symbol Type|Symbol|Description|Start API Version| 685| --- | --- | --- | --- | 686|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| 687|FUNC|napi_run_script_path|Runs an ABC file.|10| 688|FUNC|napi_load_module|Loads an .abc file as a module. This API returns the namespace of the module.|11| 689|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| 690|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| 691|FUNC|napi_coerce_to_native_binding_object|Forcibly binds a JS object and a native object.|11| 692|FUNC|napi_create_ark_runtime|Creates an ArkTS runtime environment.|12| 693|FUNC|napi_destroy_ark_runtime|Destroys the ArkTS runtime environment.|12| 694|FUNC|napi_run_event_loop|Runs the underlying event loop.|12| 695|FUNC|napi_stop_event_loop|Stops the underlying event loop.|12| 696|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| 697|FUNC|napi_serialize|Converts an ArkTS object into native data.|12| 698|FUNC|napi_deserialize|Converts native data into an ArkTS object.|12| 699|FUNC|napi_delete_serialization_data|Deletes serialized data.|12| 700|FUNC|napi_call_threadsafe_function_with_priority|Calls a task with the specified priority and enqueuing mode into the ArkTS main thread.|12| 701|FUNC|napi_is_sendable|Checks whether the given JS value is sendable.|12| 702|FUNC|napi_define_sendable_class|Creates a sendable class.|12| 703|FUNC|napi_create_sendable_object_with_properties | Creates a sendable object with the given **napi_property_descriptor**.|12| 704|FUNC|napi_create_sendable_array | Creates a sendable array.|12| 705|FUNC|napi_create_sendable_array_with_length | Creates a sendable array of the specified length.|12| 706|FUNC|napi_create_sendable_arraybuffer | Creates a sendable **ArrayBuffer**.|12| 707|FUNC|napi_create_sendable_typedarray | Creates a sendable **TypedArray**.|12| 708|FUNC|napi_wrap_sendable | Wraps a native instance into an ArkTS object.|12| 709|FUNC|napi_wrap_sendable_with_size | Wraps a native instance into an ArkTS object with the specified size.|12| 710|FUNC|napi_unwrap_sendable | Unwraps the native instance from an ArkTS object.|12| 711|FUNC|napi_remove_wrap_sendable | Removes the native instance from an ArkTS object.|12| 712 713> **NOTE** 714> 715> For details about the sendable feature, see [Sendable Object Overview](../../arkts-utils/arkts-sendable.md). 716 717### napi_qos_t 718 719```cpp 720typedef enum { 721 napi_qos_background = 0, // Low priority for works invisible to users, such as data synchronization and backup. 722 napi_qos_utility = 1, // Medium priority for works that do not require immediate response, such as downloading or importing data. 723 napi_qos_default = 2, // Default priority. 724 napi_qos_user_initiated = 3, // High priority for user-triggered works with visible progress, for example, opening a file. 725} napi_qos_t; 726``` 727 728**Description** 729Enumerates the QoS levels, which determine the priority of thread scheduling. 730 731### napi_event_mode 732 733```cpp 734typedef enum { 735 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. 736 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. 737} napi_event_mode; 738``` 739 740**Description** 741Enumerates the modes for running the underlying event loop. 742 743### napi_queue_async_work_with_qos 744 745```cpp 746napi_status napi_queue_async_work_with_qos(napi_env env, 747 napi_async_work work, 748 napi_qos_t qos); 749``` 750 751**Description** 752 753Adds an async work object to the queue so that it can be scheduled for execution based on the QoS priority passed in. 754 755**Parameters** 756 757- **env**: environment, in which the API is invoked. 758 759- **work**: handle to the async work object to schedule. This object is created by **napi_create_async_work**. 760 761- **qos**: priority of the task to schedule. 762 763**Return value** 764 765Returns **napi_ok** if the operation is successful. 766 767### napi_run_script_path 768 769```cpp 770napi_status napi_run_script_path(napi_env env, 771 const char* abcPath, 772 napi_value* result); 773``` 774 775**Description** 776 777Runs an .abc file. 778 779**Parameters** 780 781- **env**: environment, in which the API is invoked. 782 783- **abcPath**: JS path of the script to run. The value is a string that specifies the location of the script file to run. 784 785- **result**: pointer to **napi_value**, which holds the script execution result. 786 787**Return value** 788 789Returns **napi_ok** if the operation is successful. 790 791### napi_load_module 792 793```cpp 794napi_status napi_load_module(napi_env env, 795 const char* path, 796 napi_value* result); 797``` 798 799**Description** 800 801Loads a system module or a customized module. This API returns the namespace of the module loaded. 802 803**Parameters** 804 805- **env**: environment, in which the API is invoked. 806 807- **path**: name of the system module to load or path of the customized module to load. 808 809- **result**: pointer to **napi_value**, which holds the module loading result. 810 811**Return value** 812 813Returns **napi_ok** if the operation is successful. 814 815### napi_create_object_with_properties 816 817```cpp 818napi_status napi_create_object_with_properties(napi_env env, 819 napi_value* result, 820 size_t property_count, 821 const napi_property_descriptor* properties); 822``` 823 824**Description** 825 826Creates 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. 827 828 The key in **napi_property_descriptor** must be a string that cannot be converted into a number. 829 830**Parameters** 831 832- **env**: environment, in which the API is invoked. 833 834- **result**: pointer to **napi_value**, which holds the created object. 835 836- **property_count**: number of properties to be added to the object. 837 838- **properties**: pointer to a **napi_property_descriptor** array containing information about the properties to be added to the object. 839 840**Return value** 841 842Returns **napi_ok** if the operation is successful. 843 844### napi_create_object_with_named_properties 845 846```cpp 847napi_status napi_create_object_with_named_properties(napi_env env, 848 napi_value* result, 849 size_t property_count, 850 const char** keys, 851 const napi_value* values); 852``` 853 854**Description** 855 856Creates a JS object using the given **napi_value**s and keys. The key must be a string and cannot be converted into a number. 857 858**Parameters** 859 860- **env**: environment, in which the API is invoked. 861 862- **result**: pointer to **napi_value**, which holds the created object. 863 864- **property_count**: number of properties to be added to the object. 865 866- **keys**: pointer to a const char array containing the keys of the properties to add. 867 868- **values**: pointer to a **napi_value** array containing the properties to add. The keys and properties are in one-to-one mapping. 869 870**Return value** 871 872Returns **napi_ok** if the operation is successful. 873 874### napi_coerce_to_native_binding_object 875 876```cpp 877napi_status napi_coerce_to_native_binding_object(napi_env env, 878 napi_value js_object, 879 napi_native_binding_detach_callback detach_cb, 880 napi_native_binding_attach_callback attach_cb, 881 void* native_object, 882 void* hint); 883``` 884 885**Description** 886 887Converts a JS object into an object carrying native information by forcibly binding callbacks and callback data to the JS object. 888 889**Parameters** 890 891- **env**: environment, in which the API is invoked. 892 893- **js_object**: JS object to convert. 894 895- **detach_cb**: callback to be invoked to perform cleanup operations when the object is detached during serialization. 896 897- **attach_cb**: callback to be invoked when the object is attached during serialization. 898 899- **native_object**: parameters to be passed to the callbacks. This object cannot be empty. 900 901- **hint**: pointer to the additional information to be passed to the callbacks. 902 903**Return value** 904 905Returns **napi_ok** if the operation is successful. 906 907### napi_create_ark_runtime 908 909```cpp 910napi_status napi_create_ark_runtime(napi_env *env) 911``` 912 913**Description** 914 915Creates an ArkTS runtime environment. 916 917**Parameters** 918 919- **env**: environment, in which the API is invoked. 920 921**Return value** 922 923Returns **napi_ok** if the operation is successful. 924 925### napi_destroy_ark_runtime 926 927```cpp 928napi_status napi_destroy_ark_runtime(napi_env *env) 929``` 930 931**Description** 932 933Destroys an ArkTS runtime environment. 934 935**Parameters** 936 937- **env**: environment, in which the API is invoked. 938 939**Return value** 940 941Returns **napi_ok** if the operation is successful. 942 943### napi_run_event_loop 944 945```cpp 946napi_status napi_run_event_loop(napi_env env, napi_event_mode mode) 947``` 948 949**Description** 950 951Runs the underlying event loop. 952 953**Parameters** 954 955- **env**: environment, in which the API is invoked. 956- **mode**: event mode for running the event loop. 957 958**Return value** 959 960Returns **napi_ok** if the operation is successful. 961 962### napi_stop_event_loop 963 964```cpp 965napi_status napi_stop_event_loop(napi_env env) 966``` 967 968**Description** 969 970Stops the underlying event loop. 971 972**Parameters** 973 974- **env**: environment, in which the API is invoked. 975 976**Return value** 977 978Returns **napi_ok** if the operation is successful. 979 980### napi_load_module_with_info 981 982```cpp 983napi_status napi_load_module_with_info(napi_env env, 984 const char* path, 985 const char* module_info, 986 napi_value* result) 987``` 988 989**Description** 990 991Loads 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. 992 993**Parameters** 994 995- **env**: environment, in which the API is invoked. 996 997- **path**: path of the module to load. 998 999- **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. 1000 1001- **result**: pointer to **napi_value**, which holds the module loading result. 1002 1003**Return value** 1004 1005Returns **napi_ok** if the operation is successful. 1006 1007### napi_serialize 1008 1009```cpp 1010napi_status napi_serialize(napi_env env, 1011 napi_value object, 1012 napi_value transfer_list, 1013 napi_value clone_list, 1014 void** result) 1015``` 1016 1017**Description** 1018 1019Converts an ArkTS object into native data. 1020 1021**Parameters** 1022 1023- **env**: environment, in which the API is invoked. 1024 1025- **object**: JS object to be serialized. 1026 1027- **transfer_list**: list of JS objects to be passed during serialization. 1028 1029- **clone_list**: list of JS objects to be cloned during serialization. 1030 1031- **result**: pointer to the serialization result. After the call is complete, the pointer to the native data converted is stored in this position. 1032 1033**Return value** 1034 1035Returns **napi_ok** if the operation is successful. 1036 1037### napi_deserialize 1038 1039```cpp 1040napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object) 1041``` 1042 1043**Description** 1044 1045Converts native data into an ArkTS object. 1046 1047**Parameters** 1048 1049- **env**: environment, in which the API is invoked. 1050 1051- **buffer**: pointer to the binary data, which needs to be deserialized into a JS object. 1052 1053- **object**: pointer to the deserialized JS object. 1054 1055**Return value** 1056 1057Returns **napi_ok** if the operation is successful. 1058 1059### napi_delete_serialization_data 1060 1061```cpp 1062napi_status napi_delete_serialization_data(napi_env env, void* buffer) 1063``` 1064 1065**Description** 1066 1067Deletes serialized data. 1068 1069**Parameters** 1070 1071- **env**: environment, in which the API is invoked. 1072 1073- **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. 1074 1075**Return value** 1076 1077Returns **napi_ok** if the operation is successful. 1078 1079### napi_call_threadsafe_function_with_priority 1080 1081```cpp 1082napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 1083 void *data, 1084 napi_task_priority priority, 1085 bool isTail) 1086``` 1087 1088**Description** 1089 1090Calls a task with the specified priority and enqueuing mode into the ArkTS main thread. 1091 1092**Parameters** 1093 1094- **func**: thread-safe function object, which is returned when a thread-safe function is created. 1095 1096- **data**: pointer to the data to be passed to the JS callback function. 1097 1098- **priority**: priority of the task that calls the JS callback function. 1099 1100- **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. 1101 1102**Return value** 1103 1104Returns **napi_ok** if the operation is successful. 1105 1106### napi_is_sendable 1107 1108```cpp 1109napi_status napi_is_sendable(napi_env env, napi_value value, bool* result) 1110``` 1111 1112**Description** 1113 1114Checks whether the given JS value is sendable. 1115 1116**Parameters** 1117 1118- **env**: environment, in which the API is invoked. 1119 1120- **value**: JS value to check. 1121 1122- **result**: pointer of the bool type, indicating whether the JS value is sendable. 1123 1124**Return value** 1125 1126Returns **napi_ok** if the operation is successful. 1127 1128 1129### napi_define_sendable_class 1130 1131```cpp 1132napi_status napi_define_sendable_class(napi_env env, 1133 const char* utf8name, 1134 size_t length, 1135 napi_callback constructor, 1136 void* data, 1137 size_t property_count, 1138 const napi_property_descriptor* properties, 1139 napi_value parent, 1140 napi_value* result) 1141 1142 1143``` 1144 1145**Description** 1146 1147Creates a sendable class. 1148 1149**Parameters** 1150 1151- **env**: environment, in which the API is invoked. 1152 1153- **utf8name**: pointer to the name of the class to create. This parameter is of the const char* type. 1154 1155- **length**: length of the class name, in bytes. This parameter is of the size_t type. 1156 1157- **constructor**: constructor of the class. This parameter is of the napi_callback type. 1158 1159- **data**: (optional) pointer to the additional data of the constructor. This parameter is of the void* type. 1160 1161- **property_count**: number of properties of the class. This parameter is of the size_t type. 1162 1163- **properties**: (optional) pointer to the descriptors of the properties. This parameter of the const napi_property_descriptor* type. 1164 1165- **parent**: (optional) parent class of the class to create. This parameter is of the napi_value type. 1166 1167- **result**: pointer to the sendable class created. This parameter is of the napi_value type. 1168 1169**Return value** 1170 1171Returns **napi_ok** if the operation is successful. 1172 1173### napi_create_sendable_object_with_properties 1174 1175```cpp 1176napi_status napi_create_sendable_object_with_properties(napi_env env, 1177 size_t property_count, 1178 const napi_property_descriptor* properties, 1179 napi_value* result) 1180``` 1181 1182**Description** 1183 1184Creates a sendable object with the given **napi_property_descriptor**. 1185 1186**Parameters** 1187 1188- **env**: environment, in which the API is invoked. 1189 1190- **property_count**: number of properties of the class. This parameter is of the size_t type. 1191 1192- **properties**: pointer to the properties of the sendable object to create. 1193 1194- **result**: pointer to the sendable class created. This parameter is of the napi_value type. 1195 1196**Return value** 1197 1198Returns **napi_ok** if the operation is successful. 1199 1200### napi_create_sendable_array 1201 1202```cpp 1203napi_status napi_create_sendable_array(napi_env env, napi_value* result) 1204``` 1205 1206**Description** 1207 1208Creates a sendable array. 1209 1210**Parameters** 1211 1212- **env**: environment, in which the API is invoked. 1213 1214- **result**: pointer to the sendable array created. This parameter is of the napi_value type. 1215 1216**Return value** 1217 1218Returns **napi_ok** if the operation is successful. 1219 1220### napi_create_sendable_array_with_length 1221 1222```cpp 1223napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result) 1224``` 1225 1226**Description** 1227 1228Creates a sendable array of the specified length. 1229 1230**Parameters** 1231 1232- **env**: environment, in which the API is invoked. 1233 1234- **length**: length of the sendable array to create. 1235 1236- **result**: pointer to the sendable array created. This parameter is of the napi_value type. 1237 1238**Return value** 1239 1240Returns **napi_ok** if the operation is successful. 1241 1242### napi_create_sendable_arraybuffer 1243 1244```cpp 1245napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result) 1246``` 1247 1248**Description** 1249 1250Creates a sendable **ArrayBuffer**. 1251 1252**Parameters** 1253 1254- **env**: environment, in which the API is invoked. 1255 1256- **byte_length**: length of the ArrayBuffer to create. 1257 1258- **data**: pointer to the byte buffer for storing the ArrayBuffer created. 1259 1260- **result**: pointer to the ArrayBuffer created. This parameter is of the napi_value type. 1261 1262**Return value** 1263 1264Returns **napi_ok** if the operation is successful. 1265 1266### napi_create_sendable_typedarray 1267 1268```cpp 1269napi_status napi_create_sendable_typedarray(napi_env env, 1270 napi_typedarray_type type, 1271 size_t length, 1272 napi_value arraybuffer, 1273 size_t byte_offset, 1274 napi_value* result); 1275``` 1276 1277**Description** 1278 1279Creates a sendable **TypedArray**. 1280 1281**Parameters** 1282 1283- **env**: environment, in which the API is invoked. 1284 1285- **type**: type of the TypedArray to create. 1286 1287- **length**: length of the TypedArray to create. 1288 1289- **arraybuffer**: ArrayBuffer instance to create. 1290 1291- **byte_offset**: offset of the ArrayBuffer. 1292 1293- **result**: pointer to the TypedArray created. This parameter is of the napi_value type. 1294 1295**Return value** 1296 1297Returns **napi_ok** if the operation is successful. 1298 1299### napi_wrap_sendable 1300 1301```cpp 1302napi_status napi_wrap_sendable(napi_env env, 1303 napi_value js_object, 1304 void* native_object, 1305 napi_finalize finalize_cb, 1306 void* finalize_hint); 1307``` 1308 1309**Description** 1310 1311Wraps a native instance into an ArkTS object. 1312 1313**Parameters** 1314 1315- **env**: environment, in which the API is invoked. 1316 1317- **js_object**: ArkTS object. 1318 1319- **native_object**: pointer to the native instance to be wrapped in the ArkTS object. 1320 1321- **napi_finalize**: (optional) callback to be invoked when the ArkTS object is destroyed. 1322 1323- **finalize_hint**: (optional) pointer to the callback context, which will be passed to the callback. 1324 1325**Return value** 1326 1327Returns **napi_ok** if the operation is successful. 1328 1329### napi_wrap_sendable_with_size 1330 1331```cpp 1332napi_status napi_wrap_sendable_with_size(napi_env env, 1333 napi_value js_object, 1334 void* native_object, 1335 napi_finalize finalize_cb, 1336 void* finalize_hint, 1337 size_t native_binding_size); 1338``` 1339 1340**Description** 1341 1342Wraps a native instance into an ArkTS object with the specified size. 1343 1344**Parameters** 1345 1346- **env**: environment, in which the API is invoked. 1347 1348- **js_object**: ArkTS object. 1349 1350- **native_object**: pointer to the native instance to be wrapped in the ArkTS object. 1351 1352- **napi_finalize**: (optional) callback to be invoked when the ArkTS object is destroyed. 1353 1354- **finalize_hint**: (optional) pointer to the callback context, which will be passed to the callback. 1355 1356- **native_binding_size**: (optional) size of the native instance wrapped. 1357 1358**Return value** 1359 1360Returns **napi_ok** if the operation is successful. 1361 1362### napi_unwrap_sendable 1363 1364```cpp 1365napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result) 1366``` 1367 1368**Description** 1369 1370Unwraps the native instance from an ArkTS object. 1371 1372**Parameters** 1373 1374- **env**: environment, in which the API is invoked. 1375 1376- **js_object**: ArkTS object. 1377 1378- **result**: double pointer to the native instance unwrapped. 1379 1380**Return value** 1381 1382Returns **napi_ok** if the operation is successful. 1383 1384### napi_remove_wrap_sendable 1385 1386```cpp 1387napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result) 1388``` 1389 1390**Description** 1391 1392Removes the native instance from an ArkTS object. 1393 1394**Parameters** 1395 1396- **env**: environment, in which the API is invoked. 1397 1398- **js_object**: ArkTS object. 1399 1400- **result**: double pointer to the native instance unwrapped. 1401 1402**Return value** 1403 1404Returns **napi_ok** if the operation is successful. 1405 1406<!--no_check--> 1407