1 /* 2 * Copyright (c) 2021-2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup ArkTS_Napi_NativeModule 18 * @{ 19 * 20 * 21 * @brief Provides native api of ArkTS native module. 22 * 23 * @since 10 24 */ 25 26 /** 27 * @file native_api.h 28 * 29 * @brief Defines native api of ArkTS native module. 30 * 31 * @kit ArkTS 32 * @library libace_napi.z.so 33 * @syscap SystemCapability.ArkUI.ArkUI.Napi 34 * @since 10 35 * @version 1.0 36 */ 37 38 #ifndef FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H 39 #define FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H 40 41 #ifndef NAPI_VERSION 42 #define NAPI_VERSION 8 43 #endif // NAPI_VERSION 44 45 #ifndef NAPI_EXPERIMENTAL 46 #define NAPI_EXPERIMENTAL 47 #endif // NAPI_EXPERIMENTAL 48 49 #include "common.h" 50 #include "node_api.h" 51 52 #ifdef NAPI_TEST 53 #ifdef _WIN32 // WIN32 54 #define NAPI_INNER_EXTERN __declspec(dllexport) 55 #else // NON-WIN32 56 #define NAPI_INNER_EXTERN __attribute__((visibility("default"))) 57 #endif // _WIN32 58 59 #else // NAPI_TEST 60 #ifdef _WIN32 61 #define NAPI_INNER_EXTERN __declspec(deprecated) 62 #else 63 #define NAPI_INNER_EXTERN __attribute__((__deprecated__)) 64 #endif // __WIN32 65 #endif 66 67 NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, 68 const char16_t* str, 69 size_t length, 70 napi_value* result); 71 72 NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env, 73 napi_value value, 74 char16_t* buf, 75 size_t bufsize, 76 size_t* result); 77 78 NAPI_EXTERN napi_status napi_type_tag_object(napi_env env, 79 napi_value value, 80 const napi_type_tag* type_tag); 81 82 NAPI_EXTERN napi_status napi_check_object_type_tag(napi_env env, 83 napi_value value, 84 const napi_type_tag* type_tag, 85 bool* result); 86 87 NAPI_INNER_EXTERN napi_status napi_adjust_external_memory(napi_env env, 88 int64_t change_in_bytes, 89 int64_t* adjusted_value); 90 91 #ifdef __cplusplus 92 extern "C" { 93 #endif 94 95 /** 96 * @brief Native detach callback of napi_coerce_to_native_binding_object that can be used to 97 * detach the ArkTS object and the native object. 98 * 99 * @since 11 100 */ 101 typedef void* (*napi_native_binding_detach_callback)(napi_env env, void* native_object, void* hint); 102 103 /** 104 * @brief Native attach callback of napi_coerce_to_native_binding_object that can be used to 105 * bind the ArkTS object and the native object. 106 * 107 * @since 11 108 */ 109 typedef napi_value (*napi_native_binding_attach_callback)(napi_env env, void* native_object, void* hint); 110 111 NAPI_EXTERN napi_status napi_run_script_path(napi_env env, const char* path, napi_value* result); 112 NAPI_EXTERN napi_status napi_queue_async_work_with_qos(napi_env env, napi_async_work work, napi_qos_t qos); 113 114 /** 115 * @brief Loads an .abc file as a module. This API returns the namespace of the module. 116 * @param env Current running virtual machine context. 117 * @param path Path of the .abc file or name of the module to load. 118 * @param result Result of the module object. 119 * 120 * @return Returns the function execution status. 121 * @since 11 122 */ 123 NAPI_EXTERN napi_status napi_load_module(napi_env env, 124 const char* path, 125 napi_value* result); 126 127 /** 128 * @brief Associates data with the currently running environment. 129 * 130 * @param env Current running virtual machine context. 131 * @param data Data item to bind with the 'env'. 132 * @param finalize_cb Optional native callback that will be triggered when 'env' is destroyed or this interface 133 * repeatedly calls. 134 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 135 * 136 * @return Returns the function execution status. 137 * @since 11 138 */ 139 NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, 140 void* data, 141 napi_finalize finalize_cb, 142 void* finalize_hint); 143 144 /** 145 * @brief Retrieves the data that was previously associated with the currently running environment. 146 * 147 * @param env Current running virtual machine context. 148 * @param data Data item is bound with the 'env'. 149 * 150 * @return Returns the function execution status. 151 * @since 11 152 */ 153 NAPI_EXTERN napi_status napi_get_instance_data(napi_env env, 154 void** data); 155 156 /** 157 * @brief Registers a clean-up hook for releasing resources when the environment exits. 158 * 159 * @param env Current running virtual machine context. 160 * @param fun Function pointer which will be triggered when environment is destroy. 161 * @param arg The argument is passed to the function pointer 'fun'. 162 * 163 * @return Returns the function execution status. 164 * @since 11 165 */ 166 NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, 167 void (*fun)(void* arg), 168 void* arg); 169 170 /** 171 * @brief Unregisters the clean-up hook. 172 * 173 * @param env Current running virtual machine context. 174 * @param fun Function pointer which will be triggered when environment is destroy. 175 * @param arg The argument is passed to the function pointer 'fun'. 176 * 177 * @return Returns the function execution status. 178 * @since 11 179 */ 180 NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, 181 void (*fun)(void* arg), 182 void* arg); 183 184 /** 185 * @brief Registers an asynchronous clean-up hook for releasing resources when the environment exits. 186 * 187 * @param env Current running virtual machine context. 188 * @param hook The function pointer to call at environment teardown. 189 * @param arg The pointer to pass to `hook` when it gets called. 190 * @param remove_handle Optional handle that refers to the asynchronous cleanup. 191 * 192 * @return Returns the function execution status. 193 * @since 11 194 */ 195 NAPI_EXTERN napi_status napi_add_async_cleanup_hook(napi_env env, 196 napi_async_cleanup_hook hook, 197 void* arg, 198 napi_async_cleanup_hook_handle* remove_handle); 199 200 /** 201 * @brief Unregisters the asynchronous clean-up hook. 202 * 203 * @param remove_handle Optional handle that refers to the asynchronous cleanup. 204 * 205 * @return Returns the function execution status. 206 * @since 11 207 */ 208 NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(napi_async_cleanup_hook_handle remove_handle); 209 210 /** 211 * @brief Creates an asynchronous context. The capabilities related to 'async_hook' are not supported currently. 212 * 213 * @param env Current running virtual machine context. 214 * @param async_resource Object associated with the async work that will be passed to possible 'async_hook'. 215 * @param async_resource_name Identifier for the kind of resource that is being provided for diagnostic information 216 * exposed by the async_hooks API. 217 * @param result The initialized async context. 218 * 219 * @return Returns the function execution status. 220 * @since 11 221 */ 222 NAPI_EXTERN napi_status napi_async_init(napi_env env, 223 napi_value async_resource, 224 napi_value async_resource_name, 225 napi_async_context* result); 226 227 /** 228 * @brief Destroys the previously created asynchronous context. The capabilities related to 'async_hook' are not 229 * supported currently. 230 * 231 * @param env Current running virtual machine context. 232 * @param async_context The async context to be destroyed. 233 * 234 * @return Returns the function execution status. 235 * @since 11 236 */ 237 NAPI_EXTERN napi_status napi_async_destroy(napi_env env, 238 napi_async_context async_context); 239 240 /** 241 * @brief Opens a callback scope. The capabilities related to 'async_hook' are not supported currently. 242 * @param env Current running virtual machine context. 243 * @param resource_object The resource object to be passed to possible 'async_hook'. 244 * @param context The context environment for the async operation. 245 * @param result The generated callback scope. 246 * 247 * @return Returns the function execution status. 248 * @since 11 249 */ 250 NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, 251 napi_value resource_object, 252 napi_async_context context, 253 napi_callback_scope* result); 254 255 /** 256 * @brief Closes the callback scope. The capabilities related to 'async_hook' are not supported currently. 257 * 258 * @param env Current running virtual machine context. 259 * @param scope The callback scope to be closed. 260 * 261 * @return Returns the function execution status. 262 * @since 11 263 */ 264 NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, 265 napi_callback_scope scope); 266 267 /** 268 * @brief Obtains the absolute path of the location, from which the addon is loaded. 269 * 270 * @param env Current running virtual machine context. 271 * @param result The absolute path of the location of the loaded addon. 272 * 273 * @return Returns the function execution status. 274 * @since 11 275 */ 276 NAPI_EXTERN napi_status node_api_get_module_file_name(napi_env env, 277 const char** result); 278 279 /** 280 * @brief Create ArkTS Object with initial properties given by descriptors, note that property key must be String, and 281 * must can not convert to element_index, also all keys must not duplicate. 282 * 283 * @param env Current running virtual machine context. 284 * @param result The created ArkTS object. 285 * @param property_count Number of the property descriptors. 286 * @param properties Array of property descriptors which are expected to be applied to the ArkTS object. 287 * 288 * @return Returns the function execution status. 289 * @since 11 290 */ 291 NAPI_EXTERN napi_status napi_create_object_with_properties(napi_env env, 292 napi_value* result, 293 size_t property_count, 294 const napi_property_descriptor* properties); 295 296 /** 297 * @brief Create ArkTS Object with initial properties given by keys and values, note that property key must be String, 298 * and must can not convert to element_index, also all keys must not duplicate. 299 * 300 * @param env Current running virtual machine context. 301 * @param result The absolute path of the location of the loaded addon. 302 * @param property_count Number of the propertied which needs to be applied on the ArkTS object. 303 * @param keys Array of the keys of the properties. 304 * @param values Array of the values of the properties. 305 * 306 * @return Returns the function execution status. 307 * @since 11 308 */ 309 NAPI_EXTERN napi_status napi_create_object_with_named_properties(napi_env env, 310 napi_value* result, 311 size_t property_count, 312 const char** keys, 313 const napi_value* values); 314 315 /** 316 * @brief This API sets native properties to a object and converts this ArkTS object to native binding object. 317 * 318 * @param env Current running virtual machine context. 319 * @param js_object The JavaScript value to coerce. 320 * @param detach_cb Native callback that can be used to detach the ArkTS object and the native object. 321 * @param attach_cb Native callback that can be used to bind the ArkTS object and the native object. 322 * @param native_object User-provided native instance to pass to thr detach callback and attach callback. 323 * @param hint Optional hint to pass to the detach callback and attach callback. 324 * 325 * @return Return the function execution status. 326 * @since 11 327 */ 328 NAPI_EXTERN napi_status napi_coerce_to_native_binding_object(napi_env env, 329 napi_value js_object, 330 napi_native_binding_detach_callback detach_cb, 331 napi_native_binding_attach_callback attach_cb, 332 void* native_object, 333 void* hint); 334 335 /** 336 * @brief Adds a 'napi_finalize' callback, which will be called when the ArkTS object is garbage-collected. 337 * 338 * @param env Current running virtual machine context. 339 * @param js_object The ArkTS object value. 340 * @param native_object Native object to bind with the ArkTS object. 341 * @param finalize_cb Native callback that can be used to free the native object when the ArkTS object is 342 garbage-collected. 343 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 344 * @param result Optional reference of the ArkTS object. 345 * 346 * @return Return the function execution status. 347 * @since 11 348 */ 349 NAPI_EXTERN napi_status napi_add_finalizer(napi_env env, 350 napi_value js_object, 351 void* native_object, 352 napi_finalize finalize_cb, 353 void* finalize_hint, 354 napi_ref* result); 355 356 /** 357 * @brief The module is loaded through the NAPI. By default, the default object is exported from the module. 358 * 359 * @param env Current running virtual machine context. 360 * @param path Path name of the module to be loaded, like @ohos.hilog. 361 * @param module_info Path names of bundle and module, like com.example.application/entry. 362 * @param result Result of loading a module, which is an exported object of the module. 363 * 364 * @return Returns the function execution status. 365 * @since 12 366 */ 367 NAPI_EXTERN napi_status napi_load_module_with_info(napi_env env, 368 const char* path, 369 const char* module_info, 370 napi_value* result); 371 372 /** 373 * @brief Create the ark runtime. 374 * 375 * @param env Indicates the ark runtime environment. 376 * 377 * @return Return the function execution status. 378 * @since 12 379 */ 380 NAPI_EXTERN napi_status napi_create_ark_runtime(napi_env* env); 381 382 /** 383 * @brief Destroy the ark runtime. 384 * 385 * @param env Indicates the ark runtime environment. 386 * 387 * @return Return the function execution status. 388 * @since 12 389 */ 390 NAPI_EXTERN napi_status napi_destroy_ark_runtime(napi_env* env); 391 392 /** 393 * @brief Defines a sendable class. 394 * 395 * @param env The environment that the API is invoked under. 396 * @param utf8name Name of the ArkTS constructor function. 397 * @param length The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated. 398 * @param constructor Callback function that handles constructing instances of the class. 399 * @param data Optional data to be passed to the constructor callback as the data property of the callback info. 400 * @param property_count Number of items in the properties array argument. 401 * @param properties Array of property descriptors describing static and instance data properties, accessors, and 402 * methods on the class. See napi_property_descriptor. 403 * @param parent A napi_value representing the Superclass. 404 * @param result A napi_value representing the constructor function for the class. 405 * 406 * @return Return the function execution status. 407 * @since 12 408 */ 409 NAPI_EXTERN napi_status napi_define_sendable_class(napi_env env, 410 const char* utf8name, 411 size_t length, 412 napi_callback constructor, 413 void* data, 414 size_t property_count, 415 const napi_property_descriptor* properties, 416 napi_value parent, 417 napi_value* result); 418 419 /** 420 * @brief Queries a napi_value to check if it is sendable. 421 * 422 * @param env The environment that the API is invoked under. 423 * @param value The napi_value to be checked. 424 * @param result Boolean value that is set to true if napi_value is sendable, false otherwise. 425 * 426 * @return Return the function execution status. 427 * @since 12 428 */ 429 NAPI_EXTERN napi_status napi_is_sendable(napi_env env, 430 napi_value value, 431 bool* result); 432 433 /** 434 * @brief Defines a sendable object. 435 * 436 * @param env The environment that the API is invoked under. 437 * @param property_count The count of object properties. 438 * @param properties Object properties. 439 * @param result The created sendable object. 440 * 441 * @return Return the function execution status. 442 * @since 12 443 */ 444 NAPI_EXTERN napi_status napi_create_sendable_object_with_properties(napi_env env, 445 size_t property_count, 446 const napi_property_descriptor* properties, 447 napi_value* result); 448 /** 449 * @brief Wraps a native instance in a ArkTS object. 450 * @param env The environment that the API is invoked under. 451 * @param js_object The ArkTS object that will be the wrapper for the native object. 452 * @param native_object The native instance that will be wrapped in the ArkTS object. 453 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 454 * has been garbage-collected. 455 * @param async_finalizer A bool value to determine that finalize_cb execute async or not. 456 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 457 * @param native_binding_size The size of native binding. 458 * @param result Optional reference to the wrapped object. 459 * 460 * @return Returns the function execution status. 461 * {@link napi_ok } If the function executedd successfully.\n 462 * {@link napi_invalid_arg } If the param env, js_object or native_object is nullptr.\n 463 * {@link napi_object_expected } If the param js_object is not an ArkTS Object or Function.\n 464 * {@link napi_pending_exception } If have uncaught exception, or exception occured in execution.\n 465 * @since 18 466 */ 467 NAPI_EXTERN napi_status napi_wrap_enhance(napi_env env, 468 napi_value js_object, 469 void* native_object, 470 napi_finalize finalize_cb, 471 bool async_finalizer, 472 void* finalize_hint, 473 size_t native_binding_size, 474 napi_ref* result); 475 476 /** 477 * @brief Wraps a native instance in a ArkTS object. 478 * 479 * @param env The environment that the API is invoked under. 480 * @param js_object The ArkTS object that will be the wrapper for the native object. 481 * @param native_object The native instance that will be wrapped in the ArkTS object. 482 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 483 * has been garbage-collected. 484 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 485 * 486 * @return Return the function execution status. 487 * @since 12 488 */ 489 NAPI_EXTERN napi_status napi_wrap_sendable(napi_env env, 490 napi_value js_object, 491 void* native_object, 492 napi_finalize finalize_cb, 493 void* finalize_hint); 494 495 /** 496 * @brief Wraps a native instance in a ArkTS object. 497 * 498 * @param env The environment that the API is invoked under. 499 * @param js_object The ArkTS object that will be the wrapper for the native object. 500 * @param native_object The native instance that will be wrapped in the ArkTS object. 501 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 502 * has been garbage-collected. 503 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 504 * @param native_binding_size The size of native binding. 505 * 506 * @return Return the function execution status. 507 * @since 12 508 */ 509 NAPI_EXTERN napi_status napi_wrap_sendable_with_size(napi_env env, 510 napi_value js_object, 511 void* native_object, 512 napi_finalize finalize_cb, 513 void* finalize_hint, 514 size_t native_binding_size); 515 516 /** 517 * @brief Retrieves a native instance that was previously wrapped in a ArkTS object. 518 * 519 * @param env The environment that the API is invoked under. 520 * @param js_object The object associated with the native instance. 521 * @param result Pointer to the wrapped native instance. 522 * 523 * @return Return the function execution status. 524 * @since 12 525 */ 526 NAPI_EXTERN napi_status napi_unwrap_sendable(napi_env env, 527 napi_value js_object, 528 void** result); 529 530 /** 531 * @brief Retrieves a native instance that was previously wrapped in a ArkTS object and removes the wrapping. 532 * 533 * @param env The environment that the API is invoked under. 534 * @param js_object The object associated with the native instance. 535 * @param result Pointer to the wrapped native instance. 536 * 537 * @return Return the function execution status. 538 * @since 12 539 */ 540 NAPI_EXTERN napi_status napi_remove_wrap_sendable(napi_env env, 541 napi_value js_object, 542 void** result); 543 544 /** 545 * @brief Create a sendable array. 546 * 547 * @param env The environment that the API is invoked under. 548 * @param result A napi_value representing a sendable array. 549 * 550 * @return Return the function execution status. 551 * @since 12 552 */ 553 NAPI_EXTERN napi_status napi_create_sendable_array(napi_env env, 554 napi_value* result); 555 556 /** 557 * @brief Create a sendable array with length. 558 * 559 * @param env The environment that the API is invoked under. 560 * @param length The initial length of the sendable array. 561 * @param result A napi_value representing a sendable array. 562 * 563 * @return Return the function execution status. 564 * @since 12 565 */ 566 NAPI_EXTERN napi_status napi_create_sendable_array_with_length(napi_env env, 567 size_t length, 568 napi_value* result); 569 570 /** 571 * @brief Create a sendable arraybuffer. 572 * 573 * @param env The environment that the API is invoked under. 574 * @param byte_length The length in bytes of the sendable arraybuffer to create. 575 * @param data Pointer to the underlying byte buffer of the sendable arraybuffer. 576 * @param result A napi_value representing a sendable arraybuffer. 577 * 578 * @return Return the function execution status. 579 * @since 12 580 */ 581 NAPI_EXTERN napi_status napi_create_sendable_arraybuffer(napi_env env, 582 size_t byte_length, 583 void** data, 584 napi_value* result); 585 586 /** 587 * @brief Create a sendable typedarray. 588 * 589 * @param env The environment that the API is invoked under. 590 * @param type Scalar datatype of the elements within the sendable typedarray. 591 * @param length Number of elements in the typedarray. 592 * @param arraybuffer Sendable arraybuffer underlying the sendable typedarray. 593 * @param byte_offset The byte offset within the sendable arraybuffer from which to start projecting the 594 * sendable typedarray. 595 * @param result A napi_value representing a sendable typedarray. 596 * 597 * @return Return the function execution status. 598 * @since 12 599 */ 600 NAPI_EXTERN napi_status napi_create_sendable_typedarray(napi_env env, 601 napi_typedarray_type type, 602 size_t length, 603 napi_value arraybuffer, 604 size_t byte_offset, 605 napi_value* result); 606 607 /** 608 * @brief Run the event loop by the given env and running mode in current thread. 609 * 610 * Support to run the native event loop in an asynchronous native thread with the specified running mode. 611 * 612 * @param env Current running virtual machine context. 613 * @param mode Indicates the running mode of the native event loop. 614 * 615 * @return Return the function execution status. 616 * @since 12 617 */ 618 NAPI_EXTERN napi_status napi_run_event_loop(napi_env env, 619 napi_event_mode mode); 620 621 /** 622 * @brief Stop the event loop in current thread. 623 * 624 * Support to stop the running event loop in current native thread. 625 * 626 * @param env Current running virtual machine context. 627 * 628 * @return Return the function execution status. 629 * @since 12 630 */ 631 NAPI_EXTERN napi_status napi_stop_event_loop(napi_env env); 632 633 /** 634 * @brief Serialize a ArkTS object. 635 * 636 * @param env Current running virtual machine context. 637 * @param object The ArkTS object to serialize. 638 * @param transfer_list List of data to transfer in transfer mode. 639 * @param clone_list List of Sendable data to transfer in clone mode. 640 * @param result Serialization result of the ArkTS object. 641 * 642 * @return Returns the function execution status. 643 * @since 12 644 */ 645 NAPI_EXTERN napi_status napi_serialize(napi_env env, 646 napi_value object, 647 napi_value transfer_list, 648 napi_value clone_list, 649 void** result); 650 651 /** 652 * @brief Restore serialization data to a ArkTS object. 653 * 654 * @param env Current running virtual machine context. 655 * @param buffer Data to deserialize. 656 * @param object ArkTS object obtained by deserialization. 657 * 658 * @return Returns the function execution status. 659 * @since 12 660 */ 661 NAPI_EXTERN napi_status napi_deserialize(napi_env env, 662 void* buffer, 663 napi_value* object); 664 665 /** 666 * @brief Delete serialization data. 667 * 668 * @param env Current running virtual machine context. 669 * @param buffer Data to delete. 670 * 671 * @return Returns the function execution status. 672 * @since 12 673 */ 674 NAPI_EXTERN napi_status napi_delete_serialization_data(napi_env env, 675 void* buffer); 676 677 /** 678 * @brief Dispatch a task with specified priority from a native thread to an ArkTS thread, the task will execute 679 * the given thread safe function. 680 * 681 * @param func Indicates the thread safe function. 682 * @param data Indicates the data anticipated to be transferred to the ArkTS thread. 683 * @param priority Indicates the priority of the task dispatched. 684 * @param isTail Indicates the way of the task dispatched into the native event queue. When "isTail" is true, 685 * the task will be dispatched to the tail of the native event queue. Conversely, when "isTail" is false, the 686 * tasks will be dispatched to the head of the native event queue. 687 * 688 * @return Return the function execution status. 689 * @since 12 690 */ 691 NAPI_EXTERN napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 692 void *data, 693 napi_task_priority priority, 694 bool isTail); 695 696 /** 697 * @brief Throws UncaughtException to ArkTS. 698 * @param env Current running virtual machine context. 699 * @param err Error object which is passed to 'UncaughtException'. 700 * 701 * @return Returns the function execution status. 702 * @since 12 703 */ 704 NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, 705 napi_value err); 706 707 /** 708 * @brief Allows a ArkTS function to be called in the asynchronous context. The capabilities related to 'async_hook' 709 * are not supported currently. 710 * @param env Current running virtual machine context. 711 * @param async_context The context environment for the async operation. 712 * @param recv The 'this' pointer of the function. 713 * @param func ArkTS function to be called. 714 * @param argc Size of the argument array which is passed to 'func'. 715 * @param argv Argument array. 716 * @param result Result returned by the ArkTS function. 717 * 718 * @return Returns the function execution status. 719 * @since 11 720 */ 721 NAPI_EXTERN napi_status napi_make_callback(napi_env env, 722 napi_async_context async_context, 723 napi_value recv, 724 napi_value func, 725 size_t argc, 726 const napi_value* argv, 727 napi_value* result); 728 729 /** 730 * @brief Creates an ArkTS ArrayBuffer object of the specified size. 731 * 732 * @param env Current running virtual machine context. 733 * @param length Bytes size of the underlying arraybuffer. 734 * @param data Raw pointer to the underlying arraybuffer. 735 * @param result Created ArkTS ArrayBuffer object. 736 * @return Returns the function execution status. 737 * {@link napi_ok } If the function executed successfully.\n 738 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 739 * or length is less than zero.\n 740 * @since 10 741 */ 742 NAPI_EXTERN napi_status napi_create_buffer(napi_env env, 743 size_t length, 744 void** data, 745 napi_value* result); 746 747 /** 748 * @brief Creates a deferred object and an ArkTS promise. 749 * @param env Current running virtual machine context. 750 * @param deferred The created deferred object which will be passed to 'napi_resolve_deferred()' or 751 * 'napi_reject_deferred()' to resolve or reject the promise. 752 * @param promise The ArkTS promise which is associated with the deferred object. 753 * @return Returns the function execution status. 754 * {@link napi_ok } If the function executed successfully.\n 755 * {@link napi_invalid_arg } If env, deferred or resolution is nullptr.\n 756 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 757 * {@link napi_generic_failure } If create promise failed.\n 758 * @since 10 759 */ 760 NAPI_EXTERN napi_status napi_create_promise(napi_env env, 761 napi_deferred* deferred, 762 napi_value* promise); 763 764 /** 765 * @brief Resolves a promise by way of the deferred object associated. 766 * @param env Current running virtual machine context. 767 * @param deferred The deferred object which is utilized to resolve the promise. 768 * @param resolution The resolution value used to resolve the promise. 769 * @return Returns the function execution status. 770 * {@link napi_ok } If the function executed successfully.\n 771 * {@link napi_invalid_arg } If env, deferred or resolution is nullptr.\n 772 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 773 * @since 10 774 */ 775 NAPI_EXTERN napi_status napi_resolve_deferred(napi_env env, 776 napi_deferred deferred, 777 napi_value resolution); 778 779 /** 780 * @brief Rejects a promise by way of the deferred object associated. 781 * @param env Current running virtual machine context. 782 * @param deferred The deferred object which is utilized to reject the promise. 783 * @param rejection The rejection value used to reject the promise. 784 * @return Returns the function execution status. 785 * {@link napi_ok } If the function executed successfully.\n 786 * {@link napi_invalid_arg } If env, deferred or rejection is nullptr.\n 787 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 788 * @since 10 789 */ 790 NAPI_EXTERN napi_status napi_reject_deferred(napi_env env, 791 napi_deferred deferred, 792 napi_value rejection); 793 794 /** 795 * @brief Checks whether the given 'napi_value' is a promise object. 796 * @param env Current running virtual machine context. 797 * @param value The 'napi_value' to be checked. 798 * @param is_promise Boolean value that is set to true if the 'value' is a promise object, false otherwise. 799 * @return Returns the function execution status. 800 * {@link napi_ok } If the function executed successfully.\n 801 * {@link napi_invalid_arg } If env, value or is_promise is nullptr.\n 802 * @since 10 803 */ 804 NAPI_EXTERN napi_status napi_is_promise(napi_env env, 805 napi_value value, 806 bool* is_promise); 807 808 /** 809 * @brief Obtains the current libuv loop instance. 810 * @param env Current running virtual machine context. 811 * @param loop Libuv event loop. 812 * @return Returns the function execution status. 813 * {@link napi_ok } If the function executed successfully.\n 814 * {@link napi_invalid_arg } If env or loop is nullptr.\n 815 * {@link napi_generic_failure } If env is invalid.\n 816 * @since 10 817 */ 818 NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, 819 struct uv_loop_s** loop); 820 821 /** 822 * @brief Creates a thread-safe function. 823 * @param env Current running virtual machine context. 824 * @param func ArkTS function to be called. 825 * @param async_resource An optional Object associated with the async work that will be passed to possible 826 * 'async_hooks'. 827 * @param async_resource_name An ArkTS string to provide an identifier for the kind of resource that is being 828 * provided for diagnostic information exposed by the `async_hooks` interface. 829 * @param max_queue_size Maximum size of the event queue in the thread-safe function. 830 * @param initial_thread_count Initial thread count of the thread-safe function. 831 * @param thread_finalize_data Data passed to the finalize callback. 832 * @param thread_finalize_cb Finalize callback function which will be triggered when the thread-safe function is 833 * released. 834 * @param context Optional data is passed to 'call_js_cb'. 835 * @param call_js_cb Callback function which will be triggered after 'napi_call_threadsafe_function()' is called. 836 * @param result The created thread-safe function. 837 * @return Returns the function execution status. 838 * {@link napi_ok } If the function executed successfully.\n 839 * {@link napi_invalid_arg } If env, async_resource_name or result is nullptr; max_queue_size is less than 0;\n 840 * initial_thread_count is greater than 128 or less than 0; func and call_js_cb are\n 841 * nullptr at same time.\n 842 * {@link napi_generic_failure } If create thread-safe function failed.\n 843 * @since 10 844 */ 845 NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env, 846 napi_value func, 847 napi_value async_resource, 848 napi_value async_resource_name, 849 size_t max_queue_size, 850 size_t initial_thread_count, 851 void* thread_finalize_data, 852 napi_finalize thread_finalize_cb, 853 void* context, 854 napi_threadsafe_function_call_js call_js_cb, 855 napi_threadsafe_function* result); 856 857 /** 858 * @brief Obtains the context of a thread-safe function. 859 * @param func The created thread-safe function. 860 * @param result Pointer pointer to the context of the thread-safe function. 861 * @return Returns the function execution status. 862 * {@link napi_ok } If the function executed successfully.\n 863 * {@link napi_invalid_arg } If func or result is nullptr.\n 864 * @since 10 865 */ 866 NAPI_EXTERN napi_status napi_get_threadsafe_function_context(napi_threadsafe_function func, 867 void** result); 868 869 /** 870 * @brief Calls a thread-safe function. 871 * @param func The created thread-safe function. 872 * @param data Data passed to the callback function 'call_js_cb' which is registered by calling 873 * 'napi_create_threadsafe_function()'. 874 * @param is_blocking If true, this function blocks until the event queue is not full. If false, return directly. 875 * @return Returns the function execution status. 876 * {@link napi_ok } If the function executed successfully.\n 877 * {@link napi_invalid_arg } If func is nullptr.\n 878 * {@link napi_queue_full } If event queue is full.\n 879 * {@link napi_closing } If the thread-safe function is closing.\n 880 * {@link napi_generic_failure } If call thread-safe function failed.\n 881 * @since 10 882 */ 883 NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, 884 void* data, 885 napi_threadsafe_function_call_mode is_blocking); 886 887 /** 888 * @brief Acquires a thread-safe function. 889 * @param func The created thread-safe function. 890 * @return Returns the function execution status. 891 * {@link napi_ok } If the function executed successfully.\n 892 * {@link napi_invalid_arg } If func is nullptr.\n 893 * {@link napi_generic_failure } If acquire thread-safe function failed.\n 894 * @since 10 895 */ 896 NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); 897 898 /** 899 * @brief Releases a thread-safe function. 900 * @param func The created thread-safe function. 901 * @param mode Value of mode can be either 'napi_tsfn_release' to indicate that no more calls should be made 902 * to the thread-safe function from current thread or 'napi_tsfn_abort' to indicate that the queue 903 * of the thread-safe function will be closed and 'napi_closing' will be return when calling 904 * 'napi_call_threadsafe_function()' under the circumstance. 905 * @return Returns the function execution status. 906 * {@link napi_ok } If the function executed successfully.\n 907 * {@link napi_invalid_arg } If func is nullptr.\n 908 * {@link napi_generic_failure } If release thread-safe function failed.\n 909 * @since 10 910 */ 911 NAPI_EXTERN napi_status napi_release_threadsafe_function(napi_threadsafe_function func, 912 napi_threadsafe_function_release_mode mode); 913 914 /** 915 * @brief Indicates that the event loop running on the main thread may exit before the thread-safe function 916 * is destroyed. 917 * @param env Current running virtual machine context. 918 * @param func The created thread-safe function. 919 * @return Returns the function execution status. 920 * {@link napi_ok } If the function executed successfully.\n 921 * {@link napi_invalid_arg } If env or func is nullptr.\n 922 * {@link napi_generic_failure } If unref thread-safe function failed.\n 923 * @since 10 924 */ 925 NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, 926 napi_threadsafe_function func); 927 928 /** 929 * @brief Indicates that the event loop running on the main thread should not exit until the thread-safe 930 * function is destroyed. 931 * @param env Current running virtual machine context. 932 * @param func The created thread-safe function. 933 * @return Returns the function execution status. 934 * {@link napi_ok } If the function executed successfully.\n 935 * {@link napi_invalid_arg } If env or func is nullptr.\n 936 * {@link napi_generic_failure } If ref thread-safe function failed.\n 937 * @since 10 938 */ 939 NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, 940 napi_threadsafe_function func); 941 942 /** 943 * @brief Creates an ArkTS 'Date' object from C double data 944 * @param env Current running virtual machine context. 945 * @param time ArkTS time value in milliseconds format since 01 January, 1970 UTC. 946 * @param result Created ArkTS data object. 947 * @return Returns the function execution status. 948 * {@link napi_ok } If the function executed successfully.\n 949 * {@link napi_invalid_arg } If env or result is nullptr.\n 950 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 951 * @since 10 952 */ 953 NAPI_EXTERN napi_status napi_create_date(napi_env env, 954 double time, 955 napi_value* result); 956 957 /** 958 * @brief Checks whether the given ArkTS value is a 'Date' object. You can use this API to check the type 959 * of the parameter passed from ArkTS. 960 * @param env Current running virtual machine context. 961 * @param value ArkTS data object. 962 * @param is_date Boolean value that is set to true if the 'value' is a 'Date' object, false otherwise. 963 * @return Returns the function execution status. 964 * {@link napi_ok } If the function executed successfully.\n 965 * {@link napi_invalid_arg } If env, value or is_date is nullptr.\n 966 * @since 10 967 */ 968 NAPI_EXTERN napi_status napi_is_date(napi_env env, 969 napi_value value, 970 bool* is_date); 971 972 /** 973 * @brief Obtains the C equivalent of the given ArkTS 'Date' object. 974 * 975 * @param env Current running virtual machine context. 976 * @param value ArkTS data object. 977 * @param result C time value in milliseconds format since 01 January, 1970 UTC. 978 * @return Returns the function execution status. 979 * {@link napi_ok } If the function executed successfully.\n 980 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 981 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 982 * {@link napi_date_expected } If the 'value' is not a 'Date' object.\n 983 * @since 10 984 */ 985 NAPI_EXTERN napi_status napi_get_date_value(napi_env env, 986 napi_value value, 987 double* result); 988 989 /** 990 * @brief Creates a ArkTS BigInt from C int64 data. 991 * 992 * @param env Current running virtual machine context. 993 * @param value C int64 data. 994 * @param result Created ArkTS BigInt object from C int64 data. 995 * @return Returns the function execution status. 996 * {@link napi_ok } If the function executed successfully.\n 997 * {@link napi_invalid_arg } If env or result is nullptr.\n 998 * @since 10 999 */ 1000 NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env, 1001 int64_t value, 1002 napi_value* result); 1003 1004 /** 1005 * @brief Creates a ArkTS BigInt from C int64 data. 1006 * 1007 * @param env Current running virtual machine context. 1008 * @param value C int64 data. 1009 * @param result Created ArkTS BigInt object from C int64 data. 1010 * @return Returns the function execution status. 1011 * {@link napi_ok } If the function executed successfully.\n 1012 * {@link napi_invalid_arg } If env or result is nullptr.\n 1013 * @since 10 1014 */ 1015 NAPI_EXTERN napi_status napi_create_bigint_uint64(napi_env env, 1016 uint64_t value, 1017 napi_value* result); 1018 1019 /** 1020 * @brief Creates a single ArkTS BigInt from a C uint64 array. 1021 * 1022 * @param env Current running virtual machine context. 1023 * @param sign_bit Sign bit of the BigInt. If sign_bit is 0, the BigInt is positive, otherwise it is negative. 1024 * @param word_count The size of the words array. 1025 * @param words C uint64 array in little-endian 64-bit format. 1026 * @param result Created ArkTS BigInt object from C int64 array. 1027 * @return Returns the function execution status. 1028 * {@link napi_ok } If the function executed successfully.\n 1029 * {@link napi_invalid_arg } If env, words or result is nullptr or word_count is larger than 2147483647.\n 1030 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 1031 * @since 10 1032 */ 1033 NAPI_EXTERN napi_status napi_create_bigint_words(napi_env env, 1034 int sign_bit, 1035 size_t word_count, 1036 const uint64_t* words, 1037 napi_value* result); 1038 1039 /** 1040 * @brief Obtains a signed 64-bit integer from an ArkTS BigInt object. 1041 * 1042 * @param env Current running virtual machine context. 1043 * @param value ArkTS BigInt object. 1044 * @param result Pointer points to the location where store the C signed 64-bit integer value. 1045 * @param lossless Indicates whether the conversion is lossless. If lossless is true, the conversion is lossless, 1046 * false otherwise. 1047 * @return Returns the function execution status. 1048 * {@link napi_ok } If the function executed successfully.\n 1049 * {@link napi_invalid_arg } If env, value, result or lossless is nullptr or word_count is larger than\n 1050 * 2147483647.\n 1051 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1052 * @since 10 1053 */ 1054 NAPI_EXTERN napi_status napi_get_value_bigint_int64(napi_env env, 1055 napi_value value, 1056 int64_t* result, 1057 bool* lossless); 1058 1059 /** 1060 * @brief Obtains an unsigned 64-bit integer from an ArkTS BigInt object. 1061 * 1062 * @param env Current running virtual machine context. 1063 * @param value ArkTS BigInt object. 1064 * @param result Pointer points to the location where store the C unsigned 64-bit integer value. 1065 * @param lossless Indicates whether the conversion is lossless. If lossless is true, the conversion is lossless, 1066 * false otherwise. 1067 * @return Returns the function execution status. 1068 * {@link napi_ok } If the function executed successfully.\n 1069 * {@link napi_invalid_arg } If env, value, result or lossless is nullptr or word_count is larger than\n 1070 * 2147483647.\n 1071 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1072 * @since 10 1073 */ 1074 NAPI_EXTERN napi_status napi_get_value_bigint_uint64(napi_env env, 1075 napi_value value, 1076 uint64_t* result, 1077 bool* lossless); 1078 1079 /** 1080 * @brief Obtains the underlying 64-bit unsigned (uint64) byte data from an ArkTS BigInt object. 1081 * 1082 * @param env Current running virtual machine context. 1083 * @param value ArkTS BigInt object. 1084 * @param sign_bit Sign bit of the BigInt. If sign_bit is 0, the BigInt is positive, otherwise it is negative. 1085 * @param word_count The size of the words array. 1086 * @param words C uint64 array in little-endian 64-bit format. 1087 * @return Returns the function execution status. 1088 * {@link napi_ok } If the function executed successfully.\n 1089 * {@link napi_invalid_arg } If env, value or word_count is nullptr or word_count is larger than 2147483647.\n 1090 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1091 * @since 10 1092 */ 1093 NAPI_EXTERN napi_status napi_get_value_bigint_words(napi_env env, 1094 napi_value value, 1095 int* sign_bit, 1096 size_t* word_count, 1097 uint64_t* words); 1098 1099 /** 1100 * @brief Creates an ArkTS ArrayBuffer object of the specified size and initializes it with the given data. 1101 * 1102 * @param env Current running virtual machine context.n 1103 * @param length Bytes size of the given data. 1104 * @param data Given data. 1105 * @param finalize_cb Optional native callback that can be used to free the given data when the ArkTS ArrayBuffer 1106 * object has been garbage-collected. 1107 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 1108 * @param result Created ArkTS ArrayBuffer object. 1109 * @return Returns the function execution status. 1110 * {@link napi_ok } If the function executed successfully.\n 1111 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 1112 * or length is less than or equal to zero.\n 1113 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 1114 * @since 10 1115 */ 1116 NAPI_EXTERN napi_status napi_create_external_buffer(napi_env env, 1117 size_t length, 1118 void* data, 1119 napi_finalize finalize_cb, 1120 void* finalize_hint, 1121 napi_value* result); 1122 1123 /** 1124 * @brief Creates an ArkTS ArrayBuffer object of the specified size and initializes it with the given data. 1125 * 1126 * @param env Current running virtual machine context. 1127 * @param length Bytes size of the given data. 1128 * @param data Given data. 1129 * @param result_data Raw pointer to the underlying arraybuffer. 1130 * @param result Created ArkTS ArrayBuffer object. 1131 * @return Returns the function execution status. 1132 * {@link napi_ok } If the function executed successfully.\n 1133 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 1134 * or length is less than or equal to zero.\n 1135 * @since 10 1136 */ 1137 NAPI_EXTERN napi_status napi_create_buffer_copy(napi_env env, 1138 size_t length, 1139 const void* data, 1140 void** result_data, 1141 napi_value* result); 1142 1143 /** 1144 * @brief Checks whether the given ArkTS value is a 'ArrayBuffer' object. 1145 * 1146 * @param env Current running virtual machine context. 1147 * @param value ArkTS ArrayBuffer object. 1148 * @param result Boolean value that is set to true if the 'value' is a 'ArrayBuffer' object, false otherwise. 1149 * @return Returns the function execution status. 1150 * {@link napi_ok } If the function executed successfully.\n 1151 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1152 * @since 10 1153 */ 1154 NAPI_EXTERN napi_status napi_is_buffer(napi_env env, 1155 napi_value value, 1156 bool* result); 1157 1158 /** 1159 * @brief Obtains the underlying data of 'ArrayBuffer' and its length. 1160 * 1161 * @param env Current running virtual machine context. 1162 * @param value ArkTS ArrayBuffer object. 1163 * @param data Raw pointer to the underlying arraybuffer. 1164 * @param length Bytes size of the underlying arraybuffer. 1165 * @return Returns the function execution status. 1166 * {@link napi_ok } If the function executed successfully.\n 1167 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1168 * {@link napi_arraybuffer_expected } If the 'value' is not an ArkTS array buffer object.\n 1169 * @since 10 1170 */ 1171 NAPI_EXTERN napi_status napi_get_buffer_info(napi_env env, 1172 napi_value value, 1173 void** data, 1174 size_t* length); 1175 1176 /** 1177 * @brief Freezes an ArkTS object. Once an object is frozen, its properties are immutable. 1178 * 1179 * @param env Current running virtual machine context. 1180 * @param object The given ArkTS object. 1181 * @return Returns the function execution status. 1182 * {@link napi_ok } If the function executed successfully.\n 1183 * {@link napi_invalid_arg } If env or object is nullptr.\n 1184 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 1185 * @since 10 1186 */ 1187 NAPI_EXTERN napi_status napi_object_freeze(napi_env env, 1188 napi_value object); 1189 1190 /** 1191 * @brief Seals an ArkTS object. Once an object is sealed, its properties cannot be added or deleted, but property 1192 * values can be modified. 1193 * 1194 * @param env Current running virtual machine context. 1195 * @param object The given ArkTS object. 1196 * @return Returns the function execution status. 1197 * {@link napi_ok } If the function executed successfully.\n 1198 * {@link napi_invalid_arg } If env or object is nullptr.\n 1199 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 1200 * @since 10 1201 */ 1202 NAPI_EXTERN napi_status napi_object_seal(napi_env env, 1203 napi_value object); 1204 1205 /** 1206 * @brief Detaches the underlying data from an 'ArrayBuffer' object. After the data is detached, you 1207 * can operate the data in C/C++. 1208 * 1209 * @param env Current running virtual machine context. 1210 * @param arraybuffer ArkTS ArrayBuffer object. 1211 * @return Returns the function execution status. 1212 * {@link napi_ok } If the function executed successfully.\n 1213 * {@link napi_invalid_arg } If env or arraybuffer is nullptr, if 'arraybuffer' is not an ArrayBuffer object.\n 1214 * {@link napi_object_expected } If the 'arraybuffer' is not an ArkTS object.\n 1215 * @since 10 1216 */ 1217 NAPI_EXTERN napi_status napi_detach_arraybuffer(napi_env env, 1218 napi_value arraybuffer); 1219 1220 /** 1221 * @brief Checks whether the given 'ArrayBuffer' has been detached. 1222 * 1223 * @param env Current running virtual machine context. 1224 * @param value ArkTS ArrayBuffer object. 1225 * @param result Boolean value that is set to true if the 'value' has been detached, false otherwise. 1226 * @return Returns the function execution status. 1227 * {@link napi_ok } If the function executed successfully.\n 1228 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1229 * @since 10 1230 */ 1231 NAPI_EXTERN napi_status napi_is_detached_arraybuffer(napi_env env, 1232 napi_value value, 1233 bool* result); 1234 1235 /** 1236 * @brief Obtains the names of all properties of an ArkTS object. 1237 * 1238 * @param env Current running virtual machine context. 1239 * @param object ArkTS object. 1240 * @param key_mode Key collection mode. If key_mode is napi_key_include_prototypes, the result includes properties on 1241 * prototypes. If key_mode is napi_key_own_only, the result includes only properties directly on own 1242 * object. 1243 * @param key_filter Which properties to be collected. 1244 * @param key_conversion Key conversion mode. If key_conversion is napi_key_keep_numbers, the numbered property keys 1245 * will keep number type. If key_conversion is napi_key_numbers_to_strings, the numbered property 1246 * keys will be convert to string type. 1247 * @param result An array of ArkTS object that represent the property names of the object. 1248 * @return Returns the function execution status. 1249 * {@link napi_ok } If the function executed successfully.\n 1250 * {@link napi_invalid_arg } If env, object or result is nullptr;\n 1251 * key_mode is not enumeration value of napi_key_collection_mode;\n 1252 * key_conversion is not enumeration value of napi_key_conversion.\n 1253 * {@link napi_pending_exception } If a ArkTS exception existed when the function was called.\n 1254 * {@link napi_object_expected } If object is not object type and function type.\n 1255 * @since 10 1256 */ 1257 NAPI_EXTERN napi_status napi_get_all_property_names(napi_env env, 1258 napi_value object, 1259 napi_key_collection_mode key_mode, 1260 napi_key_filter key_filter, 1261 napi_key_conversion key_conversion, 1262 napi_value* result); 1263 1264 /** 1265 * @brief Registers a native module. 1266 * 1267 * @param mod Native module of type 'napi_module' to be registered. 1268 * @since 10 1269 */ 1270 NAPI_EXTERN void napi_module_register(napi_module* mod); 1271 1272 /** 1273 * @brief Obtains the napi_extended_error_info struct, which contains the latest error information. 1274 * 1275 * @param env Current running virtual machine context. 1276 * @param result The error info about the error. 1277 * 1278 * @return Returns the function execution status. 1279 * {@link napi_ok } If the function executed successfully.\n 1280 * {@link napi_invalid_arg } If env or result is nullptr.\n 1281 * @since 10 1282 */ 1283 NAPI_EXTERN napi_status napi_get_last_error_info(napi_env env, 1284 const napi_extended_error_info** result); 1285 1286 /** 1287 * @brief Throws a ArkTS error. 1288 * @param env Current running virtual machine context. 1289 * @param error The ArkTS error to be thrown. 1290 * 1291 * @return Returns the function execution status. 1292 * {@link napi_ok } If the function executed successfully.\n 1293 * {@link napi_invalid_arg } If env or error is nullptr, or error is not an error object.\n 1294 * @since 10 1295 */ 1296 NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); 1297 1298 /** 1299 * @brief Throws a ArkTS Error with text information. 1300 * @param env Current running virtual machine context. 1301 * @param code Optional error code to set on the error. 1302 * @param msg C string representing the text to be associated with the error. 1303 * 1304 * @return Returns the function execution status. 1305 * {@link napi_ok } If the function executed successfully.\n 1306 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1307 * @since 10 1308 */ 1309 NAPI_EXTERN napi_status napi_throw_error(napi_env env, 1310 const char* code, 1311 const char* msg); 1312 1313 /** 1314 * @brief Throws a ArkTS TypeError with text information. 1315 * @param env Current running virtual machine context. 1316 * @param code Optional error code to set on the error. 1317 * @param msg C string representing the text to be associated with the error. 1318 * 1319 * @return Returns the function execution status. 1320 * {@link napi_ok } If the function executed successfully.\n 1321 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1322 * @since 10 1323 */ 1324 NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, 1325 const char* code, 1326 const char* msg); 1327 1328 /** 1329 * @brief Throws a ArkTS RangeError with text information. 1330 * @param env Current running virtual machine context. 1331 * @param code Optional error code to set on the error. 1332 * @param msg C string representing the text to be associated with the error. 1333 * 1334 * @return Returns the function execution status. 1335 * {@link napi_ok } If the function executed successfully.\n 1336 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1337 * @since 10 1338 */ 1339 NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, 1340 const char* code, 1341 const char* msg); 1342 1343 /** 1344 * @brief Checks whether a 'napi_value' is an error object. 1345 * @param env Current running virtual machine context. 1346 * @param value The value to check 1347 * @param result Boolean value that is set to true if the value represents an error object, false otherwise. 1348 * 1349 * @return Returns the function execution status. 1350 * {@link napi_ok } If the function executed successfully.\n 1351 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1352 * @since 10 1353 */ 1354 NAPI_EXTERN napi_status napi_is_error(napi_env env, 1355 napi_value value, 1356 bool* result); 1357 1358 /** 1359 * @brief Creates a ArkTS Error with text information. 1360 * @param env Current running virtual machine context. 1361 * @param code Optional error code to set on the error. 1362 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1363 * @param result napi_value representing the error created. 1364 * 1365 * @return Returns the function execution status. 1366 * {@link napi_ok } If the function executed successfully.\n 1367 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is 1368 * not a string type.\n 1369 * @since 10 1370 */ 1371 NAPI_EXTERN napi_status napi_create_error(napi_env env, 1372 napi_value code, 1373 napi_value msg, 1374 napi_value* result); 1375 1376 /** 1377 * @brief Creates a ArkTS TypeError with text information. 1378 * @param env Current running virtual machine context. 1379 * @param code Optional error code to set on the error. 1380 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1381 * @param result napi_value representing the error created. 1382 * 1383 * @return Returns the function execution status. 1384 * {@link napi_ok } If the function executed successfully.\n 1385 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is 1386 * not a string type.\n 1387 * @since 10 1388 */ 1389 NAPI_EXTERN napi_status napi_create_type_error(napi_env env, 1390 napi_value code, 1391 napi_value msg, 1392 napi_value* result); 1393 1394 /** 1395 * @brief Creates a ArkTS RangeError with text information. 1396 * @param env Current running virtual machine context. 1397 * @param code Optional error code to set on the error. 1398 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1399 * @param result napi_value representing the error created. 1400 * 1401 * @return Returns the function execution status. 1402 * {@link napi_ok } If the function executed successfully.\n 1403 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is 1404 * not a string type.\n 1405 * @since 10 1406 */ 1407 NAPI_EXTERN napi_status napi_create_range_error(napi_env env, 1408 napi_value code, 1409 napi_value msg, 1410 napi_value* result); 1411 1412 /** 1413 * @brief Checks whether an exception occurs. 1414 * @param env Current running virtual machine context. 1415 * @param result Boolean value that is true if there is a pending exception. 1416 * 1417 * @return Returns the function execution status. 1418 * {@link napi_ok } If the function executed successfully.\n 1419 * {@link napi_invalid_arg } If env or result is nullptr.\n 1420 * @since 10 1421 */ 1422 NAPI_EXTERN napi_status napi_is_exception_pending(napi_env env, bool* result); 1423 1424 /** 1425 * @brief Obtains and clears the latest exception. 1426 * @param env Current running virtual machine context. 1427 * @param result The exception if there is a pending exception; otherwise return a null value. 1428 * 1429 * @return Returns the function execution status. 1430 * {@link napi_ok } If the function executed successfully.\n 1431 * {@link napi_invalid_arg } If env or result is nullptr.\n 1432 * @since 10 1433 */ 1434 NAPI_EXTERN napi_status napi_get_and_clear_last_exception(napi_env env, 1435 napi_value* result); 1436 1437 /** 1438 * @brief Raises a fatal error to terminate the process immediately. 1439 * @param location Optional location for the error occurrence. 1440 * @param location_len The byte length of the location, or NAPI_AUTO_LENGTH if it is terminated by a null character. 1441 * @param message The message associated with the error. 1442 * @param message_len The byte length of the message, or NAPI_AUTO_LENGTH if it is terminated by a null character. 1443 * 1444 * @since 10 1445 */ 1446 NAPI_EXTERN NAPI_NO_RETURN void napi_fatal_error(const char* location, 1447 size_t location_len, 1448 const char* message, 1449 size_t message_len); 1450 1451 /** 1452 * @brief Opens a scope. 1453 * @param env Current running virtual machine context. 1454 * @param result napi_value representing the new scope. 1455 * 1456 * @return Returns the function execution status. 1457 * {@link napi_ok } If the function executed successfully.\n 1458 * {@link napi_invalid_arg } If env or result is nullptr.\n 1459 * @since 10 1460 */ 1461 NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, 1462 napi_handle_scope* result); 1463 1464 /** 1465 * @brief Closes the scope passed in. After the scope is closed, all references declared in it are closed. 1466 * @param env Current running virtual machine context. 1467 * @param scope The scope to close. 1468 * 1469 * @return Returns the function execution status. 1470 * {@link napi_ok } If the function executed successfully.\n 1471 * {@link napi_invalid_arg } If env or scope is nullptr.\n 1472 * {@link napi_handle_scope_mismatch } If there is no scope still existed.\n 1473 * @since 10 1474 */ 1475 NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, 1476 napi_handle_scope scope); 1477 1478 /** 1479 * @brief Opens an escapable handle scope from which the declared values can be returned to the outer scope. 1480 * @param env Current running virtual machine context. 1481 * @param result The new scope. 1482 * 1483 * @return Returns the function execution status. 1484 * {@link napi_ok } If the function executed successfully.\n 1485 * {@link napi_invalid_arg } If env or result is nullptr.\n 1486 * @since 10 1487 */ 1488 NAPI_EXTERN napi_status napi_open_escapable_handle_scope(napi_env env, 1489 napi_escapable_handle_scope* result); 1490 1491 /** 1492 * @brief Closes the escapable handle scope passed in. 1493 * @param env Current running virtual machine context. 1494 * @param scope The scope to close. 1495 * 1496 * @return Returns the function execution status. 1497 * {@link napi_ok } If the function executed successfully.\n 1498 * {@link napi_invalid_arg } If env or scope is nullptr.\n 1499 * {@link napi_handle_scope_mismatch } If there is no scope still existed.\n 1500 * @since 10 1501 */ 1502 NAPI_EXTERN napi_status napi_close_escapable_handle_scope(napi_env env, 1503 napi_escapable_handle_scope scope); 1504 1505 /** 1506 * @brief Promotes the handle to the input ArkTS object so that it is valid for the lifespan of its outer scope. 1507 * @param env Current running virtual machine context. 1508 * @param scope Current scope. 1509 * @param escapee The ArkTS object to be escaped. 1510 * @param result The handle to the escaped object in the outer scope. 1511 * 1512 * @return Returns the function execution status. 1513 * {@link napi_ok } If the function executed successfully.\n 1514 * {@link napi_invalid_arg } If env, scope, escapee or result is nullptr.\n 1515 * @since 10 1516 */ 1517 NAPI_EXTERN napi_status napi_escape_handle(napi_env env, 1518 napi_escapable_handle_scope scope, 1519 napi_value escapee, 1520 napi_value* result); 1521 1522 /** 1523 * @brief Creates a reference for an object to extend its lifespan. The caller needs to manage the reference lifespan. 1524 * @param env Current running virtual machine context. 1525 * @param value The napi_value that is being referenced. 1526 * @param initial_refcount The initial count for the new reference. 1527 * @param result napi_ref pointing to the new reference. 1528 * 1529 * @return Returns the function execution status. 1530 * {@link napi_ok } If the function executed successfully.\n 1531 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1532 * @since 10 1533 */ 1534 NAPI_EXTERN napi_status napi_create_reference(napi_env env, 1535 napi_value value, 1536 uint32_t initial_refcount, 1537 napi_ref* result); 1538 1539 /** 1540 * @brief Deletes the reference passed in. 1541 * @param env Current running virtual machine context. 1542 * @param ref The napi_ref to be deleted. 1543 * 1544 * @return Returns the function execution status. 1545 * {@link napi_ok } If the function executed successfully.\n 1546 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1547 * @since 10 1548 */ 1549 NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); 1550 1551 /** 1552 * @brief Increments the reference count for the reference passed in and returns the count. 1553 * @param env Current running virtual machine context. 1554 * @param ref The napi_ref whose reference count will be incremented. 1555 * @param result The new reference count. 1556 * 1557 * @return Returns the function execution status. 1558 * {@link napi_ok } If the function executed successfully.\n 1559 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1560 * @since 10 1561 */ 1562 NAPI_EXTERN napi_status napi_reference_ref(napi_env env, 1563 napi_ref ref, 1564 uint32_t* result); 1565 1566 /** 1567 * @brief Decrements the reference count for the reference passed in and returns the count. 1568 * @param env Current running virtual machine context. 1569 * @param ref The napi_ref whose reference count will be decremented. 1570 * @param result The new reference count. 1571 * 1572 * @return Returns the function execution status. 1573 * {@link napi_ok } If the function executed successfully.\n 1574 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1575 * @since 10 1576 */ 1577 NAPI_EXTERN napi_status napi_reference_unref(napi_env env, 1578 napi_ref ref, 1579 uint32_t* result); 1580 1581 /** 1582 * @brief Obtains the ArkTS Object associated with the reference. 1583 * @param env Current running virtual machine context. 1584 * @param ref The napi_ref of the value being requested. 1585 * @param result The napi_value referenced by the napi_ref. 1586 * 1587 * @return Returns the function execution status. 1588 * {@link napi_ok } If the function executed successfully.\n 1589 * {@link napi_invalid_arg } If env, ref or result is nullptr.\n 1590 * @since 10 1591 */ 1592 NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, 1593 napi_ref ref, 1594 napi_value* result); 1595 1596 /** 1597 * @brief Check if the given ArkTS Object has the named own property or not. 1598 * @param env Current running virtual machine context. 1599 * @param object The ArkTS object. 1600 * @param key The name of the property to check. 1601 * @param result Whether the own property exists on the object or not. 1602 * 1603 * @return Returns the function execution status. 1604 * {@link napi_ok } If the function executed successfully.\n 1605 * {@link napi_invalid_arg } If the param env, object, key and(or) result is nullptr.\n 1606 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 1607 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 1608 * @since 10 1609 */ 1610 NAPI_EXTERN napi_status napi_has_own_property(napi_env env, 1611 napi_value object, 1612 napi_value key, 1613 bool* result); 1614 1615 /** 1616 * @brief Defines an ArkTS class, including constructor function and properties. 1617 * @param env Current running virtual machine context. 1618 * @param utf8name Name of the ArkTS constructor function. 1619 * @param length The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated. 1620 * @param constructor Callback function that handles constructing instances of the class. 1621 * @param data Optional data to be passed to the constructor callback as the data property of the callback info. 1622 * @param property_count Number of items in the properties array argument. 1623 * @param properties Array of property descriptors. 1624 * @param result A napi_value representing the constructor function for the class. 1625 * 1626 * @return Returns the function execution status. 1627 * {@link napi_ok } If the function executed successfully.\n execution.\n 1628 * {@link napi_invalid_arg } If the param env, utf8name and(or) result is nullptr. If napi_property_descriptor 1629 * is nullptr but property_count greater than 0.\n 1630 * {@link napi_function_expected } If the param func is not an ArkTS Function.\n 1631 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 1632 * @since 10 1633 */ 1634 NAPI_EXTERN napi_status napi_define_class(napi_env env, 1635 const char* utf8name, 1636 size_t length, 1637 napi_callback constructor, 1638 void* data, 1639 size_t property_count, 1640 const napi_property_descriptor* properties, 1641 napi_value* result); 1642 #ifdef __cplusplus 1643 } 1644 #endif 1645 /** @} */ 1646 #endif /* FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H */ 1647