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 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, 72 const char16_t* str, 73 size_t length, 74 napi_value* result); 75 76 NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env, 77 napi_value value, 78 char16_t* buf, 79 size_t bufsize, 80 size_t* result); 81 82 NAPI_EXTERN napi_status napi_type_tag_object(napi_env env, 83 napi_value value, 84 const napi_type_tag* type_tag); 85 86 NAPI_EXTERN napi_status napi_check_object_type_tag(napi_env env, 87 napi_value value, 88 const napi_type_tag* type_tag, 89 bool* result); 90 91 NAPI_INNER_EXTERN napi_status napi_adjust_external_memory(napi_env env, 92 int64_t change_in_bytes, 93 int64_t* adjusted_value); 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 ArkTS 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 342 * when the ArkTS object is 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 /** 450 * @brief Wraps a native instance in an ArkTS object. 451 * 452 * @param env The environment that the API is invoked under. 453 * @param js_object The ArkTS object that will be the wrapper for the native object. 454 * @param native_object The native instance that will be wrapped in the ArkTS object. 455 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 456 * has been garbage-collected. 457 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 458 * 459 * @return Return the function execution status. 460 * @since 12 461 */ 462 NAPI_EXTERN napi_status napi_wrap_sendable(napi_env env, 463 napi_value js_object, 464 void* native_object, 465 napi_finalize finalize_cb, 466 void* finalize_hint); 467 468 /** 469 * @brief Wraps a native instance in an ArkTS object. 470 * 471 * @param env The environment that the API is invoked under. 472 * @param js_object The ArkTS object that will be the wrapper for the native object. 473 * @param native_object The native instance that will be wrapped in the ArkTS object. 474 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 475 * has been garbage-collected. 476 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 477 * @param native_binding_size The size of native binding. 478 * 479 * @return Return the function execution status. 480 * @since 12 481 */ 482 NAPI_EXTERN napi_status napi_wrap_sendable_with_size(napi_env env, 483 napi_value js_object, 484 void* native_object, 485 napi_finalize finalize_cb, 486 void* finalize_hint, 487 size_t native_binding_size); 488 489 /** 490 * @brief Retrieves a native instance that was previously wrapped in an ArkTS object. 491 * 492 * @param env The environment that the API is invoked under. 493 * @param js_object The object associated with the native instance. 494 * @param result Pointer to the wrapped native instance. 495 * 496 * @return Return the function execution status. 497 * @since 12 498 */ 499 NAPI_EXTERN napi_status napi_unwrap_sendable(napi_env env, 500 napi_value js_object, 501 void** result); 502 503 /** 504 * @brief Retrieves a native instance that was previously wrapped in an ArkTS object and removes the wrapping. 505 * 506 * @param env The environment that the API is invoked under. 507 * @param js_object The object associated with the native instance. 508 * @param result Pointer to the wrapped native instance. 509 * 510 * @return Return the function execution status. 511 * @since 12 512 */ 513 NAPI_EXTERN napi_status napi_remove_wrap_sendable(napi_env env, 514 napi_value js_object, 515 void** result); 516 517 /** 518 * @brief Create a sendable array. 519 * 520 * @param env The environment that the API is invoked under. 521 * @param result A napi_value representing a sendable array. 522 * 523 * @return Return the function execution status. 524 * @since 12 525 */ 526 NAPI_EXTERN napi_status napi_create_sendable_array(napi_env env, 527 napi_value* result); 528 529 /** 530 * @brief Create a sendable array with length. 531 * 532 * @param env The environment that the API is invoked under. 533 * @param length The initial length of the sendable array. 534 * @param result A napi_value representing a sendable array. 535 * 536 * @return Return the function execution status. 537 * @since 12 538 */ 539 NAPI_EXTERN napi_status napi_create_sendable_array_with_length(napi_env env, 540 size_t length, 541 napi_value* result); 542 543 /** 544 * @brief Create a sendable arraybuffer. 545 * 546 * @param env The environment that the API is invoked under. 547 * @param byte_length The length in bytes of the sendable arraybuffer to create. 548 * @param data Pointer to the underlying byte buffer of the sendable arraybuffer. 549 * @param result A napi_value representing a sendable arraybuffer. 550 * 551 * @return Return the function execution status. 552 * @since 12 553 */ 554 NAPI_EXTERN napi_status napi_create_sendable_arraybuffer(napi_env env, 555 size_t byte_length, 556 void** data, 557 napi_value* result); 558 559 /** 560 * @brief Create a sendable typedarray. 561 * 562 * @param env The environment that the API is invoked under. 563 * @param type Scalar datatype of the elements within the sendable typedarray. 564 * @param length Number of elements in the typedarray. 565 * @param arraybuffer Sendable arraybuffer underlying the sendable typedarray. 566 * @param byte_offset The byte offset within the sendable arraybuffer from which to start projecting the 567 * sendable typedarray. 568 * @param result A napi_value representing a sendable typedarray. 569 * 570 * @return Return the function execution status. 571 * @since 12 572 */ 573 NAPI_EXTERN napi_status napi_create_sendable_typedarray(napi_env env, 574 napi_typedarray_type type, 575 size_t length, 576 napi_value arraybuffer, 577 size_t byte_offset, 578 napi_value* result); 579 580 /** 581 * @brief Run the event loop by the given env and running mode in current thread. 582 * 583 * Support to run the native event loop in an asynchronous native thread with the specified running mode. 584 * 585 * @param env Current running virtual machine context. 586 * @param mode Indicates the running mode of the native event loop. 587 * 588 * @return Return the function execution status. 589 * @since 12 590 */ 591 NAPI_EXTERN napi_status napi_run_event_loop(napi_env env, 592 napi_event_mode mode); 593 594 /** 595 * @brief Stop the event loop in current thread. 596 * 597 * Support to stop the running event loop in current native thread. 598 * 599 * @param env Current running virtual machine context. 600 * 601 * @return Return the function execution status. 602 * @since 12 603 */ 604 NAPI_EXTERN napi_status napi_stop_event_loop(napi_env env); 605 606 /** 607 * @brief Serialize an ArkTS object. 608 * 609 * @param env Current running virtual machine context. 610 * @param object The ArkTS object to serialize. 611 * @param transfer_list List of data to transfer in transfer mode. 612 * @param clone_list List of Sendable data to transfer in clone mode. 613 * @param result Serialization result of the ArkTS object. 614 * 615 * @return Returns the function execution status. 616 * @since 12 617 */ 618 NAPI_EXTERN napi_status napi_serialize(napi_env env, 619 napi_value object, 620 napi_value transfer_list, 621 napi_value clone_list, 622 void** result); 623 624 /** 625 * @brief Restore serialization data to an ArkTS object. 626 * 627 * @param env Current running virtual machine context. 628 * @param buffer Data to deserialize. 629 * @param object ArkTS object obtained by deserialization. 630 * 631 * @return Returns the function execution status. 632 * @since 12 633 */ 634 NAPI_EXTERN napi_status napi_deserialize(napi_env env, 635 void* buffer, 636 napi_value* object); 637 638 /** 639 * @brief Delete serialization data. 640 * 641 * @param env Current running virtual machine context. 642 * @param buffer Data to delete. 643 * 644 * @return Returns the function execution status. 645 * @since 12 646 */ 647 NAPI_EXTERN napi_status napi_delete_serialization_data(napi_env env, 648 void* buffer); 649 650 /** 651 * @brief Dispatch a task with specified priority from a native thread to an ArkTS thread, the task will execute 652 * the given thread safe function. 653 * 654 * @param func Indicates the thread safe function. 655 * @param data Indicates the data anticipated to be transferred to the ArkTS thread. 656 * @param priority Indicates the priority of the task dispatched. 657 * @param isTail Indicates the way of the task dispatched into the native event queue. When "isTail" is true, 658 * the task will be dispatched to the tail of the native event queue. Conversely, when "isTail" is 659 * false, the tasks will be dispatched to the head of the native event queue. 660 * 661 * @return Return the function execution status. 662 * @since 12 663 */ 664 NAPI_EXTERN napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 665 void *data, 666 napi_task_priority priority, 667 bool isTail); 668 669 /** 670 * @brief Throws UncaughtException to ArkTS. 671 * @param env Current running virtual machine context. 672 * @param err Error object which is passed to 'UncaughtException'. 673 * 674 * @return Returns the function execution status. 675 * {@link napi_ok } If the function executed successfully.\n 676 * {@link napi_invalid_arg } If the param env and(or) err is nullptr;\n 677 * If the param err is not an ArkTS Error value.\n 678 * {@link napi_pending_exception } There is an uncaught exception occurred before execution.\n 679 * @since 12 680 */ 681 NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, 682 napi_value err); 683 684 /** 685 * @brief Allows an ArkTS function to be called in the asynchronous context. The capabilities related to 'async_hook' 686 * are not supported currently. 687 * @param env Current running virtual machine context. 688 * @param async_context The context environment for the async operation. 689 * @param recv The 'this' pointer of the function. 690 * @param func ArkTS function to be called. 691 * @param argc Size of the argument array which is passed to 'func'. 692 * @param argv Argument array. 693 * @param result Result returned by the ArkTS function. 694 * 695 * @return Returns the function execution status. 696 * {@link napi_ok } If the function executed successfully.\n 697 * {@link napi_invalid_arg } If the param env, func and(or) recv is nullptr;\n 698 * If the param argc is greater than 0 but argv is nullptr.\n 699 * {@link napi_object_expected } If the param recv is not an ArkTS Object.\n 700 * {@link napi_function_expected } If the param func is not an ArkTS Function.\n 701 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 702 * @since 11 703 */ 704 NAPI_EXTERN napi_status napi_make_callback(napi_env env, 705 napi_async_context async_context, 706 napi_value recv, 707 napi_value func, 708 size_t argc, 709 const napi_value* argv, 710 napi_value* result); 711 712 /** 713 * @brief Creates an ArkTS ArrayBuffer object of the specified size. 714 * 715 * @param env Current running virtual machine context. 716 * @param length Bytes size of the underlying arraybuffer. 717 * @param data Raw pointer to the underlying arraybuffer. 718 * @param result Created ArkTS ArrayBuffer object. 719 * @return Returns the function execution status. 720 * {@link napi_ok } If the function executed successfully.\n 721 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 722 * or length is less than zero.\n 723 * @since 10 724 */ 725 NAPI_EXTERN napi_status napi_create_buffer(napi_env env, 726 size_t length, 727 void** data, 728 napi_value* result); 729 730 /** 731 * @brief Creates a deferred object and an ArkTS promise. 732 * @param env Current running virtual machine context. 733 * @param deferred The created deferred object which will be passed to 'napi_resolve_deferred()' or 734 * 'napi_reject_deferred()' to resolve or reject the promise. 735 * @param promise The ArkTS promise which is associated with the deferred 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, deferred or resolution is nullptr.\n 739 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 740 * {@link napi_generic_failure } If create promise failed.\n 741 * @since 10 742 */ 743 NAPI_EXTERN napi_status napi_create_promise(napi_env env, 744 napi_deferred* deferred, 745 napi_value* promise); 746 747 /** 748 * @brief Resolves a promise by way of the deferred object associated. 749 * @param env Current running virtual machine context. 750 * @param deferred The deferred object which is utilized to resolve the promise. 751 * @param resolution The resolution value used to resolve the promise. 752 * @return Returns the function execution status. 753 * {@link napi_ok } If the function executed successfully.\n 754 * {@link napi_invalid_arg } If env, deferred or resolution is nullptr.\n 755 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 756 * @since 10 757 */ 758 NAPI_EXTERN napi_status napi_resolve_deferred(napi_env env, 759 napi_deferred deferred, 760 napi_value resolution); 761 762 /** 763 * @brief Rejects a promise by way of the deferred object associated. 764 * @param env Current running virtual machine context. 765 * @param deferred The deferred object which is utilized to reject the promise. 766 * @param rejection The rejection value used to reject the promise. 767 * @return Returns the function execution status. 768 * {@link napi_ok } If the function executed successfully.\n 769 * {@link napi_invalid_arg } If env, deferred or rejection is nullptr.\n 770 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 771 * @since 10 772 */ 773 NAPI_EXTERN napi_status napi_reject_deferred(napi_env env, 774 napi_deferred deferred, 775 napi_value rejection); 776 777 /** 778 * @brief Checks whether the given 'napi_value' is a promise object. 779 * @param env Current running virtual machine context. 780 * @param value The 'napi_value' to be checked. 781 * @param is_promise Boolean value that is set to true if the 'value' is a promise object, false otherwise. 782 * @return Returns the function execution status. 783 * {@link napi_ok } If the function executed successfully.\n 784 * {@link napi_invalid_arg } If env, value or is_promise is nullptr.\n 785 * @since 10 786 */ 787 NAPI_EXTERN napi_status napi_is_promise(napi_env env, 788 napi_value value, 789 bool* is_promise); 790 791 /** 792 * @brief Obtains the current libuv loop instance. 793 * @param env Current running virtual machine context. 794 * @param loop Libuv event loop. 795 * @return Returns the function execution status. 796 * {@link napi_ok } If the function executed successfully.\n 797 * {@link napi_invalid_arg } If env or loop is nullptr.\n 798 * {@link napi_generic_failure } If env is invalid.\n 799 * @since 10 800 */ 801 NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, 802 struct uv_loop_s** loop); 803 804 /** 805 * @brief Creates a thread-safe function. 806 * @param env Current running virtual machine context. 807 * @param func ArkTS function to be called. 808 * @param async_resource An optional Object associated with the async work that will be passed to possible 809 * 'async_hooks'. 810 * @param async_resource_name An ArkTS string to provide an identifier for the kind of resource that is being 811 * provided for diagnostic information exposed by the `async_hooks` interface. 812 * @param max_queue_size Maximum size of the event queue in the thread-safe function. 813 * @param initial_thread_count Initial thread count of the thread-safe function. 814 * @param thread_finalize_data Data passed to the finalize callback. 815 * @param thread_finalize_cb Finalize callback function which will be triggered when the thread-safe function is 816 * released. 817 * @param context Optional data is passed to 'call_js_cb'. 818 * @param call_js_cb Callback function which will be triggered after 'napi_call_threadsafe_function()' is called. 819 * @param result The created thread-safe function. 820 * @return Returns the function execution status. 821 * {@link napi_ok } If the function executed successfully.\n 822 * {@link napi_invalid_arg } If env, async_resource_name or result is nullptr; max_queue_size is less than 0;\n 823 * initial_thread_count is greater than 128 or less than 0; func and call_js_cb are\n 824 * nullptr at same time.\n 825 * {@link napi_generic_failure } If create thread-safe function failed.\n 826 * @since 10 827 */ 828 NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env, 829 napi_value func, 830 napi_value async_resource, 831 napi_value async_resource_name, 832 size_t max_queue_size, 833 size_t initial_thread_count, 834 void* thread_finalize_data, 835 napi_finalize thread_finalize_cb, 836 void* context, 837 napi_threadsafe_function_call_js call_js_cb, 838 napi_threadsafe_function* result); 839 840 /** 841 * @brief Obtains the context of a thread-safe function. 842 * @param func The created thread-safe function. 843 * @param result Pointer pointer to the context of the thread-safe function. 844 * @return Returns the function execution status. 845 * {@link napi_ok } If the function executed successfully.\n 846 * {@link napi_invalid_arg } If func or result is nullptr.\n 847 * @since 10 848 */ 849 NAPI_EXTERN napi_status napi_get_threadsafe_function_context(napi_threadsafe_function func, 850 void** result); 851 852 /** 853 * @brief Calls a thread-safe function. 854 * @param func The created thread-safe function. 855 * @param data Data passed to the callback function 'call_js_cb' which is registered by calling 856 * 'napi_create_threadsafe_function()'. 857 * @param is_blocking If true, this function blocks until the event queue is not full. If false, return directly. 858 * @return Returns the function execution status. 859 * {@link napi_ok } If the function executed successfully.\n 860 * {@link napi_invalid_arg } If func is nullptr.\n 861 * {@link napi_queue_full } If event queue is full.\n 862 * {@link napi_closing } If the thread-safe function is closing.\n 863 * {@link napi_generic_failure } If call thread-safe function failed.\n 864 * @since 10 865 */ 866 NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, 867 void* data, 868 napi_threadsafe_function_call_mode is_blocking); 869 870 /** 871 * @brief Acquires a thread-safe function. 872 * @param func The created thread-safe function. 873 * @return Returns the function execution status. 874 * {@link napi_ok } If the function executed successfully.\n 875 * {@link napi_invalid_arg } If func is nullptr.\n 876 * {@link napi_generic_failure } If acquire thread-safe function failed.\n 877 * @since 10 878 */ 879 NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); 880 881 /** 882 * @brief Releases a thread-safe function. 883 * @param func The created thread-safe function. 884 * @param mode Value of mode can be either 'napi_tsfn_release' to indicate that no more calls should be made 885 * to the thread-safe function from current thread or 'napi_tsfn_abort' to indicate that the queue 886 * of the thread-safe function will be closed and 'napi_closing' will be return when calling 887 * 'napi_call_threadsafe_function()' under the circumstance. 888 * @return Returns the function execution status. 889 * {@link napi_ok } If the function executed successfully.\n 890 * {@link napi_invalid_arg } If func is nullptr.\n 891 * {@link napi_generic_failure } If release thread-safe function failed.\n 892 * @since 10 893 */ 894 NAPI_EXTERN napi_status napi_release_threadsafe_function(napi_threadsafe_function func, 895 napi_threadsafe_function_release_mode mode); 896 897 /** 898 * @brief Indicates that the event loop running on the main thread may exit before the thread-safe function 899 * is destroyed. 900 * @param env Current running virtual machine context. 901 * @param func The created thread-safe function. 902 * @return Returns the function execution status. 903 * {@link napi_ok } If the function executed successfully.\n 904 * {@link napi_invalid_arg } If env or func is nullptr.\n 905 * {@link napi_generic_failure } If unref thread-safe function failed.\n 906 * @since 10 907 */ 908 NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, 909 napi_threadsafe_function func); 910 911 /** 912 * @brief Indicates that the event loop running on the main thread should not exit until the thread-safe 913 * function is destroyed. 914 * @param env Current running virtual machine context. 915 * @param func The created thread-safe function. 916 * @return Returns the function execution status. 917 * {@link napi_ok } If the function executed successfully.\n 918 * {@link napi_invalid_arg } If env or func is nullptr.\n 919 * {@link napi_generic_failure } If ref thread-safe function failed.\n 920 * @since 10 921 */ 922 NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, 923 napi_threadsafe_function func); 924 925 /** 926 * @brief Creates an ArkTS 'Date' object from C double data 927 * @param env Current running virtual machine context. 928 * @param time ArkTS time value in milliseconds format since 01 January, 1970 UTC. 929 * @param result Created ArkTS data object. 930 * @return Returns the function execution status. 931 * {@link napi_ok } If the function executed successfully.\n 932 * {@link napi_invalid_arg } If env or result is nullptr.\n 933 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 934 * @since 10 935 */ 936 NAPI_EXTERN napi_status napi_create_date(napi_env env, 937 double time, 938 napi_value* result); 939 940 /** 941 * @brief Checks whether the given ArkTS value is a 'Date' object. You can use this API to check the type 942 * of the parameter passed from ArkTS. 943 * @param env Current running virtual machine context. 944 * @param value ArkTS data object. 945 * @param is_date Boolean value that is set to true if the 'value' is a 'Date' object, false otherwise. 946 * @return Returns the function execution status. 947 * {@link napi_ok } If the function executed successfully.\n 948 * {@link napi_invalid_arg } If env, value or is_date is nullptr.\n 949 * @since 10 950 */ 951 NAPI_EXTERN napi_status napi_is_date(napi_env env, 952 napi_value value, 953 bool* is_date); 954 955 /** 956 * @brief Obtains the C equivalent of the given ArkTS 'Date' object. 957 * 958 * @param env Current running virtual machine context. 959 * @param value ArkTS data object. 960 * @param result C time value in milliseconds format since 01 January, 1970 UTC. 961 * @return Returns the function execution status. 962 * {@link napi_ok } If the function executed successfully.\n 963 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 964 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 965 * {@link napi_date_expected } If the 'value' is not a 'Date' object.\n 966 * @since 10 967 */ 968 NAPI_EXTERN napi_status napi_get_date_value(napi_env env, 969 napi_value value, 970 double* result); 971 972 /** 973 * @brief Creates an ArkTS BigInt from C int64 data. 974 * 975 * @param env Current running virtual machine context. 976 * @param value C int64 data. 977 * @param result Created ArkTS BigInt object from C int64 data. 978 * @return Returns the function execution status. 979 * {@link napi_ok } If the function executed successfully.\n 980 * {@link napi_invalid_arg } If env or result is nullptr.\n 981 * @since 10 982 */ 983 NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env, 984 int64_t value, 985 napi_value* result); 986 987 /** 988 * @brief Creates an ArkTS BigInt from C int64 data. 989 * 990 * @param env Current running virtual machine context. 991 * @param value C int64 data. 992 * @param result Created ArkTS BigInt object from C int64 data. 993 * @return Returns the function execution status. 994 * {@link napi_ok } If the function executed successfully.\n 995 * {@link napi_invalid_arg } If env or result is nullptr.\n 996 * @since 10 997 */ 998 NAPI_EXTERN napi_status napi_create_bigint_uint64(napi_env env, 999 uint64_t value, 1000 napi_value* result); 1001 1002 /** 1003 * @brief Creates a single ArkTS BigInt from a C uint64 array. 1004 * 1005 * @param env Current running virtual machine context. 1006 * @param sign_bit Sign bit of the BigInt. If sign_bit is 0, the BigInt is positive, otherwise it is negative. 1007 * @param word_count The size of the words array. 1008 * @param words C uint64 array in little-endian 64-bit format. 1009 * @param result Created ArkTS BigInt object from C int64 array. 1010 * @return Returns the function execution status. 1011 * {@link napi_ok } If the function executed successfully.\n 1012 * {@link napi_invalid_arg } If env, words or result is nullptr or word_count is larger than 2147483647.\n 1013 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 1014 * @since 10 1015 */ 1016 NAPI_EXTERN napi_status napi_create_bigint_words(napi_env env, 1017 int sign_bit, 1018 size_t word_count, 1019 const uint64_t* words, 1020 napi_value* result); 1021 1022 /** 1023 * @brief Obtains a signed 64-bit integer from an ArkTS BigInt object. 1024 * 1025 * @param env Current running virtual machine context. 1026 * @param value ArkTS BigInt object. 1027 * @param result Pointer points to the location where store the C signed 64-bit integer value. 1028 * @param lossless Indicates whether the conversion is lossless. If lossless is true, the conversion is lossless, 1029 * false otherwise. 1030 * @return Returns the function execution status. 1031 * {@link napi_ok } If the function executed successfully.\n 1032 * {@link napi_invalid_arg } If env, value, result or lossless is nullptr or word_count is larger than\n 1033 * 2147483647.\n 1034 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1035 * @since 10 1036 */ 1037 NAPI_EXTERN napi_status napi_get_value_bigint_int64(napi_env env, 1038 napi_value value, 1039 int64_t* result, 1040 bool* lossless); 1041 1042 /** 1043 * @brief Obtains an unsigned 64-bit integer from an ArkTS BigInt object. 1044 * 1045 * @param env Current running virtual machine context. 1046 * @param value ArkTS BigInt object. 1047 * @param result Pointer points to the location where store the C unsigned 64-bit integer value. 1048 * @param lossless Indicates whether the conversion is lossless. If lossless is true, the conversion is lossless, 1049 * false otherwise. 1050 * @return Returns the function execution status. 1051 * {@link napi_ok } If the function executed successfully.\n 1052 * {@link napi_invalid_arg } If env, value, result or lossless is nullptr or word_count is larger than\n 1053 * 2147483647.\n 1054 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1055 * @since 10 1056 */ 1057 NAPI_EXTERN napi_status napi_get_value_bigint_uint64(napi_env env, 1058 napi_value value, 1059 uint64_t* result, 1060 bool* lossless); 1061 1062 /** 1063 * @brief Obtains the underlying 64-bit unsigned (uint64) byte data from an ArkTS BigInt object. 1064 * 1065 * @param env Current running virtual machine context. 1066 * @param value ArkTS BigInt object. 1067 * @param sign_bit Sign bit of the BigInt. If sign_bit is 0, the BigInt is positive, otherwise it is negative. 1068 * @param word_count The size of the words array. 1069 * @param words C uint64 array in little-endian 64-bit format. 1070 * @return Returns the function execution status. 1071 * {@link napi_ok } If the function executed successfully.\n 1072 * {@link napi_invalid_arg } If env, value or word_count is nullptr or word_count is larger than 2147483647.\n 1073 * {@link napi_bigint_expected } If the 'value' is not an ArkTS bigint object.\n 1074 * @since 10 1075 */ 1076 NAPI_EXTERN napi_status napi_get_value_bigint_words(napi_env env, 1077 napi_value value, 1078 int* sign_bit, 1079 size_t* word_count, 1080 uint64_t* words); 1081 1082 /** 1083 * @brief Creates an ArkTS ArrayBuffer object of the specified size and initializes it with the given data. 1084 * 1085 * @param env Current running virtual machine context.n 1086 * @param length Bytes size of the given data. 1087 * @param data Given data. 1088 * @param finalize_cb Optional native callback that can be used to free the given data when the ArkTS ArrayBuffer 1089 * object has been garbage-collected. 1090 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 1091 * @param result Created ArkTS ArrayBuffer object. 1092 * @return Returns the function execution status. 1093 * {@link napi_ok } If the function executed successfully.\n 1094 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 1095 * or length is less than or equal to zero.\n 1096 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 1097 * @since 10 1098 */ 1099 NAPI_EXTERN napi_status napi_create_external_buffer(napi_env env, 1100 size_t length, 1101 void* data, 1102 napi_finalize finalize_cb, 1103 void* finalize_hint, 1104 napi_value* result); 1105 1106 /** 1107 * @brief Creates an ArkTS ArrayBuffer object of the specified size and initializes it with the given data. 1108 * 1109 * @param env Current running virtual machine context. 1110 * @param length Bytes size of the given data. 1111 * @param data Given data. 1112 * @param result_data Raw pointer to the underlying arraybuffer. 1113 * @param result Created ArkTS ArrayBuffer object. 1114 * @return Returns the function execution status. 1115 * {@link napi_ok } If the function executed successfully.\n 1116 * {@link napi_invalid_arg } If env, data or result is nullptr, or length is larger than 2097152, 1117 * or length is less than or equal to zero.\n 1118 * @since 10 1119 */ 1120 NAPI_EXTERN napi_status napi_create_buffer_copy(napi_env env, 1121 size_t length, 1122 const void* data, 1123 void** result_data, 1124 napi_value* result); 1125 1126 /** 1127 * @brief Checks whether the given ArkTS value is a 'ArrayBuffer' object. 1128 * 1129 * @param env Current running virtual machine context. 1130 * @param value ArkTS ArrayBuffer object. 1131 * @param result Boolean value that is set to true if the 'value' is a 'ArrayBuffer' object, false otherwise. 1132 * @return Returns the function execution status. 1133 * {@link napi_ok } If the function executed successfully.\n 1134 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1135 * @since 10 1136 */ 1137 NAPI_EXTERN napi_status napi_is_buffer(napi_env env, 1138 napi_value value, 1139 bool* result); 1140 1141 /** 1142 * @brief Obtains the underlying data of 'ArrayBuffer' and its length. 1143 * 1144 * @param env Current running virtual machine context. 1145 * @param value ArkTS ArrayBuffer object. 1146 * @param data Raw pointer to the underlying arraybuffer. 1147 * @param length Bytes size of the underlying arraybuffer. 1148 * @return Returns the function execution status. 1149 * {@link napi_ok } If the function executed successfully.\n 1150 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1151 * {@link napi_arraybuffer_expected } If the 'value' is not an ArkTS array buffer object.\n 1152 * @since 10 1153 */ 1154 NAPI_EXTERN napi_status napi_get_buffer_info(napi_env env, 1155 napi_value value, 1156 void** data, 1157 size_t* length); 1158 1159 /** 1160 * @brief Freezes an ArkTS object. Once an object is frozen, its properties are immutable. 1161 * 1162 * @param env Current running virtual machine context. 1163 * @param object The given ArkTS object. 1164 * @return Returns the function execution status. 1165 * {@link napi_ok } If the function executed successfully.\n 1166 * {@link napi_invalid_arg } If env or object is nullptr.\n 1167 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 1168 * @since 10 1169 */ 1170 NAPI_EXTERN napi_status napi_object_freeze(napi_env env, 1171 napi_value object); 1172 1173 /** 1174 * @brief Seals an ArkTS object. Once an object is sealed, its properties cannot be added or deleted, but property 1175 * values can be modified. 1176 * 1177 * @param env Current running virtual machine context. 1178 * @param object The given ArkTS object. 1179 * @return Returns the function execution status. 1180 * {@link napi_ok } If the function executed successfully.\n 1181 * {@link napi_invalid_arg } If env or object is nullptr.\n 1182 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 1183 * @since 10 1184 */ 1185 NAPI_EXTERN napi_status napi_object_seal(napi_env env, 1186 napi_value object); 1187 1188 /** 1189 * @brief Detaches the underlying data from an 'ArrayBuffer' object. After the data is detached, you 1190 * can operate the data in C/C++. 1191 * 1192 * @param env Current running virtual machine context. 1193 * @param arraybuffer ArkTS ArrayBuffer object. 1194 * @return Returns the function execution status. 1195 * {@link napi_ok } If the function executed successfully.\n 1196 * {@link napi_invalid_arg } If env or arraybuffer is nullptr, if 'arraybuffer' is not an ArrayBuffer object.\n 1197 * {@link napi_object_expected } If the 'arraybuffer' is not an ArkTS object.\n 1198 * @since 10 1199 */ 1200 NAPI_EXTERN napi_status napi_detach_arraybuffer(napi_env env, 1201 napi_value arraybuffer); 1202 1203 /** 1204 * @brief Checks whether the given 'ArrayBuffer' has been detached. 1205 * 1206 * @param env Current running virtual machine context. 1207 * @param value ArkTS ArrayBuffer object. 1208 * @param result Boolean value that is set to true if the 'value' has been detached, false otherwise. 1209 * @return Returns the function execution status. 1210 * {@link napi_ok } If the function executed successfully.\n 1211 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1212 * @since 10 1213 */ 1214 NAPI_EXTERN napi_status napi_is_detached_arraybuffer(napi_env env, 1215 napi_value value, 1216 bool* result); 1217 1218 /** 1219 * @brief Obtains the names of all properties of an ArkTS object. 1220 * 1221 * @param env Current running virtual machine context. 1222 * @param object ArkTS object. 1223 * @param key_mode Key collection mode. If key_mode is napi_key_include_prototypes, the result includes properties on 1224 * prototypes. If key_mode is napi_key_own_only, the result includes only properties directly on own 1225 * object. 1226 * @param key_filter Which properties to be collected. 1227 * @param key_conversion Key conversion mode. If key_conversion is napi_key_keep_numbers, the numbered property keys 1228 * will keep number type. If key_conversion is napi_key_numbers_to_strings, the numbered property 1229 * keys will be convert to string type. 1230 * @param result An array of ArkTS object that represent the property names of the object. 1231 * @return Returns the function execution status. 1232 * {@link napi_ok } If the function executed successfully.\n 1233 * {@link napi_invalid_arg } If env, object or result is nullptr;\n 1234 * key_mode is not enumeration value of napi_key_collection_mode;\n 1235 * key_conversion is not enumeration value of napi_key_conversion.\n 1236 * {@link napi_pending_exception } If an ArkTS exception existed when the function was called.\n 1237 * {@link napi_object_expected } If object is not object type and function type.\n 1238 * @since 10 1239 */ 1240 NAPI_EXTERN napi_status napi_get_all_property_names(napi_env env, 1241 napi_value object, 1242 napi_key_collection_mode key_mode, 1243 napi_key_filter key_filter, 1244 napi_key_conversion key_conversion, 1245 napi_value* result); 1246 1247 /** 1248 * @brief Registers a native module. 1249 * 1250 * @param mod Native module of type 'napi_module' to be registered. 1251 * @since 10 1252 */ 1253 NAPI_EXTERN void napi_module_register(napi_module* mod); 1254 1255 /** 1256 * @brief Obtains the napi_extended_error_info struct, which contains the latest error information. 1257 * 1258 * @param env Current running virtual machine context. 1259 * @param result The error info about the error. 1260 * 1261 * @return Returns the function execution status. 1262 * {@link napi_ok } If the function executed successfully.\n 1263 * {@link napi_invalid_arg } If env or result is nullptr.\n 1264 * @since 10 1265 */ 1266 NAPI_EXTERN napi_status napi_get_last_error_info(napi_env env, 1267 const napi_extended_error_info** result); 1268 1269 /** 1270 * @brief Throws an ArkTS error. 1271 * @param env Current running virtual machine context. 1272 * @param error The ArkTS error to be thrown. 1273 * 1274 * @return Returns the function execution status. 1275 * {@link napi_ok } If the function executed successfully.\n 1276 * {@link napi_invalid_arg } If env or error is nullptr, or error is not an error object.\n 1277 * @since 10 1278 */ 1279 NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); 1280 1281 /** 1282 * @brief Throws an ArkTS Error with text information. 1283 * @param env Current running virtual machine context. 1284 * @param code Optional error code to set on the error. 1285 * @param msg C string representing the text to be associated with the error. 1286 * 1287 * @return Returns the function execution status. 1288 * {@link napi_ok } If the function executed successfully.\n 1289 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1290 * @since 10 1291 */ 1292 NAPI_EXTERN napi_status napi_throw_error(napi_env env, 1293 const char* code, 1294 const char* msg); 1295 1296 /** 1297 * @brief Throws an ArkTS TypeError with text information. 1298 * @param env Current running virtual machine context. 1299 * @param code Optional error code to set on the error. 1300 * @param msg C string representing the text to be associated with the error. 1301 * 1302 * @return Returns the function execution status. 1303 * {@link napi_ok } If the function executed successfully.\n 1304 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1305 * @since 10 1306 */ 1307 NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, 1308 const char* code, 1309 const char* msg); 1310 1311 /** 1312 * @brief Throws an ArkTS RangeError with text information. 1313 * @param env Current running virtual machine context. 1314 * @param code Optional error code to set on the error. 1315 * @param msg C string representing the text to be associated with the error. 1316 * 1317 * @return Returns the function execution status. 1318 * {@link napi_ok } If the function executed successfully.\n 1319 * {@link napi_invalid_arg } If env or msg is nullptr.\n 1320 * @since 10 1321 */ 1322 NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, 1323 const char* code, 1324 const char* msg); 1325 1326 /** 1327 * @brief Checks whether a 'napi_value' is an error object. 1328 * @param env Current running virtual machine context. 1329 * @param value The value to check 1330 * @param result Boolean value that is set to true if the value represents an error object, false otherwise. 1331 * 1332 * @return Returns the function execution status. 1333 * {@link napi_ok } If the function executed successfully.\n 1334 * {@link napi_invalid_arg } If env, value or result is nullptr.\n 1335 * @since 10 1336 */ 1337 NAPI_EXTERN napi_status napi_is_error(napi_env env, 1338 napi_value value, 1339 bool* result); 1340 1341 /** 1342 * @brief Creates an ArkTS Error with text information. 1343 * @param env Current running virtual machine context. 1344 * @param code Optional error code to set on the error. 1345 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1346 * @param result napi_value representing the error created. 1347 * 1348 * @return Returns the function execution status. 1349 * {@link napi_ok } If the function executed successfully.\n 1350 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is\n 1351 * not a string type.\n 1352 * @since 10 1353 */ 1354 NAPI_EXTERN napi_status napi_create_error(napi_env env, 1355 napi_value code, 1356 napi_value msg, 1357 napi_value* result); 1358 1359 /** 1360 * @brief Creates an ArkTS TypeError with text information. 1361 * @param env Current running virtual machine context. 1362 * @param code Optional error code to set on the error. 1363 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1364 * @param result napi_value representing the error created. 1365 * 1366 * @return Returns the function execution status. 1367 * {@link napi_ok } If the function executed successfully.\n 1368 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is\n 1369 * not a string type.\n 1370 * @since 10 1371 */ 1372 NAPI_EXTERN napi_status napi_create_type_error(napi_env env, 1373 napi_value code, 1374 napi_value msg, 1375 napi_value* result); 1376 1377 /** 1378 * @brief Creates an ArkTS RangeError with text information. 1379 * @param env Current running virtual machine context. 1380 * @param code Optional error code to set on the error. 1381 * @param msg napi_value representing the EcmaScript string to be associated with the error. 1382 * @param result napi_value representing the error created. 1383 * 1384 * @return Returns the function execution status. 1385 * {@link napi_ok } If the function executed successfully.\n 1386 * {@link napi_invalid_arg } If env, msg or result is nullptr, code is not string and number type or msg is\n 1387 * not a string type.\n 1388 * @since 10 1389 */ 1390 NAPI_EXTERN napi_status napi_create_range_error(napi_env env, 1391 napi_value code, 1392 napi_value msg, 1393 napi_value* result); 1394 1395 /** 1396 * @brief Checks whether an exception occurs. 1397 * @param env Current running virtual machine context. 1398 * @param result Boolean value that is true if there is a pending exception. 1399 * 1400 * @return Returns the function execution status. 1401 * {@link napi_ok } If the function executed successfully.\n 1402 * {@link napi_invalid_arg } If env or result is nullptr.\n 1403 * @since 10 1404 */ 1405 NAPI_EXTERN napi_status napi_is_exception_pending(napi_env env, bool* result); 1406 1407 /** 1408 * @brief Obtains and clears the latest exception. 1409 * @param env Current running virtual machine context. 1410 * @param result The exception if there is a pending exception; otherwise return a null value. 1411 * 1412 * @return Returns the function execution status. 1413 * {@link napi_ok } If the function executed successfully.\n 1414 * {@link napi_invalid_arg } If env or result is nullptr.\n 1415 * @since 10 1416 */ 1417 NAPI_EXTERN napi_status napi_get_and_clear_last_exception(napi_env env, 1418 napi_value* result); 1419 1420 /** 1421 * @brief Raises a fatal error to terminate the process immediately. 1422 * @param location Optional location for the error occurrence. 1423 * @param location_len The byte length of the location, or NAPI_AUTO_LENGTH if it is terminated by a null character. 1424 * @param message The message associated with the error. 1425 * @param message_len The byte length of the message, or NAPI_AUTO_LENGTH if it is terminated by a null character. 1426 * 1427 * @since 10 1428 */ 1429 NAPI_EXTERN NAPI_NO_RETURN void napi_fatal_error(const char* location, 1430 size_t location_len, 1431 const char* message, 1432 size_t message_len); 1433 1434 /** 1435 * @brief Opens a scope. 1436 * @param env Current running virtual machine context. 1437 * @param result napi_value representing the new scope. 1438 * 1439 * @return Returns the function execution status. 1440 * {@link napi_ok } If the function executed successfully.\n 1441 * {@link napi_invalid_arg } If env or result is nullptr.\n 1442 * @since 10 1443 */ 1444 NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, 1445 napi_handle_scope* result); 1446 1447 /** 1448 * @brief Closes the scope passed in. After the scope is closed, all references declared in it are closed. 1449 * @param env Current running virtual machine context. 1450 * @param scope The scope to close. 1451 * 1452 * @return Returns the function execution status. 1453 * {@link napi_ok } If the function executed successfully.\n 1454 * {@link napi_invalid_arg } If env or scope is nullptr.\n 1455 * {@link napi_handle_scope_mismatch } If there is no scope still existed.\n 1456 * @since 10 1457 */ 1458 NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, 1459 napi_handle_scope scope); 1460 1461 /** 1462 * @brief Opens an escapable handle scope from which the declared values can be returned to the outer scope. 1463 * @param env Current running virtual machine context. 1464 * @param result The new scope. 1465 * 1466 * @return Returns the function execution status. 1467 * {@link napi_ok } If the function executed successfully.\n 1468 * {@link napi_invalid_arg } If env or result is nullptr.\n 1469 * @since 10 1470 */ 1471 NAPI_EXTERN napi_status napi_open_escapable_handle_scope(napi_env env, 1472 napi_escapable_handle_scope* result); 1473 1474 /** 1475 * @brief Closes the escapable handle scope passed in. 1476 * @param env Current running virtual machine context. 1477 * @param scope The scope to close. 1478 * 1479 * @return Returns the function execution status. 1480 * {@link napi_ok } If the function executed successfully.\n 1481 * {@link napi_invalid_arg } If env or scope is nullptr.\n 1482 * {@link napi_handle_scope_mismatch } If there is no scope still existed.\n 1483 * @since 10 1484 */ 1485 NAPI_EXTERN napi_status napi_close_escapable_handle_scope(napi_env env, 1486 napi_escapable_handle_scope scope); 1487 1488 /** 1489 * @brief Promotes the handle to the input ArkTS object so that it is valid for the lifespan of its outer scope. 1490 * @param env Current running virtual machine context. 1491 * @param scope Current scope. 1492 * @param escapee The ArkTS object to be escaped. 1493 * @param result The handle to the escaped object in the outer scope. 1494 * 1495 * @return Returns the function execution status. 1496 * {@link napi_ok } If the function executed successfully.\n 1497 * {@link napi_invalid_arg } If env, scope, escapee or result is nullptr.\n 1498 * @since 10 1499 */ 1500 NAPI_EXTERN napi_status napi_escape_handle(napi_env env, 1501 napi_escapable_handle_scope scope, 1502 napi_value escapee, 1503 napi_value* result); 1504 1505 /** 1506 * @brief Creates a reference for an object to extend its lifespan. The caller needs to manage the reference lifespan. 1507 * @param env Current running virtual machine context. 1508 * @param value The napi_value that is being referenced. 1509 * @param initial_refcount The initial count for the new reference. 1510 * @param result napi_ref pointing to the new reference. 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, value or result is nullptr.\n 1515 * @since 10 1516 */ 1517 NAPI_EXTERN napi_status napi_create_reference(napi_env env, 1518 napi_value value, 1519 uint32_t initial_refcount, 1520 napi_ref* result); 1521 1522 /** 1523 * @brief Deletes the reference passed in. 1524 * @param env Current running virtual machine context. 1525 * @param ref The napi_ref to be deleted. 1526 * 1527 * @return Returns the function execution status. 1528 * {@link napi_ok } If the function executed successfully.\n 1529 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1530 * @since 10 1531 */ 1532 NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); 1533 1534 /** 1535 * @brief Increments the reference count for the reference passed in and returns the count. 1536 * @param env Current running virtual machine context. 1537 * @param ref The napi_ref whose reference count will be incremented. 1538 * @param result The new reference count. 1539 * 1540 * @return Returns the function execution status. 1541 * {@link napi_ok } If the function executed successfully.\n 1542 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1543 * @since 10 1544 */ 1545 NAPI_EXTERN napi_status napi_reference_ref(napi_env env, 1546 napi_ref ref, 1547 uint32_t* result); 1548 1549 /** 1550 * @brief Decrements the reference count for the reference passed in and returns the count. 1551 * @param env Current running virtual machine context. 1552 * @param ref The napi_ref whose reference count will be decremented. 1553 * @param result The new reference count. 1554 * 1555 * @return Returns the function execution status. 1556 * {@link napi_ok } If the function executed successfully.\n 1557 * {@link napi_invalid_arg } If env or ref is nullptr.\n 1558 * @since 10 1559 */ 1560 NAPI_EXTERN napi_status napi_reference_unref(napi_env env, 1561 napi_ref ref, 1562 uint32_t* result); 1563 1564 /** 1565 * @brief Obtains the ArkTS Object associated with the reference. 1566 * @param env Current running virtual machine context. 1567 * @param ref The napi_ref of the value being requested. 1568 * @param result The napi_value referenced by the napi_ref. 1569 * 1570 * @return Returns the function execution status. 1571 * {@link napi_ok } If the function executed successfully.\n 1572 * {@link napi_invalid_arg } If env, ref or result is nullptr.\n 1573 * @since 10 1574 */ 1575 NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, 1576 napi_ref ref, 1577 napi_value* result); 1578 1579 /** 1580 * @brief Check if the given ArkTS Object has the named own property or not. 1581 * @param env Current running virtual machine context. 1582 * @param object The ArkTS object. 1583 * @param key The name of the property to check. 1584 * @param result Whether the own property exists on the object or not. 1585 * 1586 * @return Returns the function execution status. 1587 * {@link napi_ok } If the function executed successfully.\n 1588 * {@link napi_invalid_arg } If the param env, object, key and(or) result is nullptr.\n 1589 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 1590 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 1591 * @since 10 1592 */ 1593 NAPI_EXTERN napi_status napi_has_own_property(napi_env env, 1594 napi_value object, 1595 napi_value key, 1596 bool* result); 1597 1598 /** 1599 * @brief Defines an ArkTS class, including constructor function and properties. 1600 * @param env Current running virtual machine context. 1601 * @param utf8name Name of the ArkTS constructor function. 1602 * @param length The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated. 1603 * @param constructor Callback function that handles constructing instances of the class. 1604 * @param data Optional data to be passed to the constructor callback as the data property of the callback info. 1605 * @param property_count Number of items in the properties array argument. 1606 * @param properties Array of property descriptors. 1607 * @param result A napi_value representing the constructor function for the class. 1608 * 1609 * @return Returns the function execution status. 1610 * {@link napi_ok } If the function executed successfully.\n execution.\n 1611 * {@link napi_invalid_arg } If the param env, utf8name and(or) result is nullptr. If napi_property_descriptor 1612 * is nullptr but property_count greater than 0.\n 1613 * {@link napi_function_expected } If the param func is not an ArkTS Function.\n 1614 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 1615 * @since 10 1616 */ 1617 NAPI_EXTERN napi_status napi_define_class(napi_env env, 1618 const char* utf8name, 1619 size_t length, 1620 napi_callback constructor, 1621 void* data, 1622 size_t property_count, 1623 const napi_property_descriptor* properties, 1624 napi_value* result); 1625 1626 /** 1627 * @brief Creates an ArkTS symbol. 1628 * @param env Current running virtual machine context. 1629 * @param description Optional napi_value representing an ArkTS string to describe the symbol. 1630 * @param result A napi_value representing an ArkTS symbol. 1631 * 1632 * @return Returns the function execution status. 1633 * {@link napi_ok } If the function executed successfully.\n 1634 * {@link napi_invalid_arg } If the param env and(or) result is nullptr;\n 1635 * If the param description is not nullptr and is not an ArkTS String.\n 1636 * @since 10 1637 */ 1638 NAPI_EXTERN napi_status napi_create_symbol(napi_env env, 1639 napi_value description, 1640 napi_value* result); 1641 1642 /** 1643 * @brief Create an ArkTS function. This is the primary mechanism to call back into native code from ArkTS. 1644 * @param env Current running virtual machine context. 1645 * @param utf8name The visible within ArkTS as the new function's name property. 1646 * @param length The length oh the utf8name, or NAPI_AUTO_LENGTH if it is null-terminated. 1647 * @param cb The native function which should be called when this function object is called. 1648 * @param data User-provided data context. This will be passed back into the function when invoked. 1649 * @param result The newly created ArkTS function. 1650 * 1651 * @return Returns the function execution status. 1652 * {@link napi_ok } If the function executed successfully.\n 1653 * {@link napi_invalid_arg } If the param env, cb and(or) result is nullptr.\n 1654 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 1655 * @since 10 1656 */ 1657 NAPI_EXTERN napi_status napi_create_function(napi_env env, 1658 const char* utf8name, 1659 size_t length, 1660 napi_callback cb, 1661 void* data, 1662 napi_value* result); 1663 1664 /** 1665 * @brief Similar to typeof operation, support external value, detects null as a separate type. 1666 * @param env Current running virtual machine context. 1667 * @param value The ArkTS value whose type expects to query. 1668 * @param result The type of ArkTS value. 1669 * 1670 * @return Returns the function execution status. 1671 * {@link napi_ok } If the function executed successfully.\n 1672 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1673 * @since 10 1674 */ 1675 NAPI_EXTERN napi_status napi_typeof(napi_env env, 1676 napi_value value, 1677 napi_valuetype* result); 1678 1679 /** 1680 * @brief Obtains the double value corresponding to the given ArkTS value. 1681 * @param env Current running virtual machine context. 1682 * @param value ArkTS number. 1683 * @param result The C primitive equivalent of ArkTS value as double. 1684 * 1685 * @return Returns the function execution status. 1686 * {@link napi_ok } If the function executed successfully.\n 1687 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1688 * {@link napi_number_expected } If a non-number ArkTS value passed in it.\n 1689 * @since 10 1690 */ 1691 NAPI_EXTERN napi_status napi_get_value_double(napi_env env, 1692 napi_value value, 1693 double* result); 1694 1695 /** 1696 * @brief Obtains the int32_t value corresponding to the given ArkTS value. 1697 * @param env Current running virtual machine context. 1698 * @param value ArkTS number. 1699 * @param result The C primitive equivalent of ArkTS value as int32_t. 1700 * 1701 * @return Returns the function execution status. 1702 * {@link napi_ok } If the function executed successfully.\n 1703 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1704 * {@link napi_number_expected } If a non-number ArkTS value passed in it.\n 1705 * @since 10 1706 */ 1707 NAPI_EXTERN napi_status napi_get_value_int32(napi_env env, 1708 napi_value value, 1709 int32_t* result); 1710 1711 /** 1712 * @brief Obtains the uint32_t value corresponding to the given ArkTS value. 1713 * @param env Current running virtual machine context. 1714 * @param value ArkTS number. 1715 * @param result The C primitive equivalent of ArkTS value as uint32_t. 1716 * 1717 * @return Returns the function execution status. 1718 * {@link napi_ok } If the function executed successfully.\n 1719 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1720 * {@link napi_number_expected } If a non-number ArkTS value passed in it.\n 1721 * @since 10 1722 */ 1723 NAPI_EXTERN napi_status napi_get_value_uint32(napi_env env, 1724 napi_value value, 1725 uint32_t* result); 1726 1727 /** 1728 * @brief Obtains the int64_t value corresponding to the given ArkTS value. 1729 * @param env Current running virtual machine context. 1730 * @param value ArkTS number. 1731 * @param result The C primitive equivalent of ArkTS value as int64_t. 1732 * 1733 * @return Returns the function execution status. 1734 * {@link napi_ok } If the function executed successfully.\n 1735 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1736 * {@link napi_number_expected } If a non-number ArkTS value passed in it.\n 1737 * @since 10 1738 */ 1739 NAPI_EXTERN napi_status napi_get_value_int64(napi_env env, 1740 napi_value value, 1741 int64_t* result); 1742 1743 /** 1744 * @brief Obtains the C Boolean equivalent of an ArkTS Boolean value. 1745 * @param env Current running virtual machine context. 1746 * @param value A napi_value representing ArkTS Boolean. 1747 * @param result The C boolean equivalent of the ArkTS Boolean. 1748 * 1749 * @return Returns the function execution status. 1750 * {@link napi_ok } If the function executed successfully.\n 1751 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1752 * {@link napi_boolean_expected } If a non-boolean ArkTS value passed in it.\n 1753 * @since 10 1754 */ 1755 NAPI_EXTERN napi_status napi_get_value_bool(napi_env env, 1756 napi_value value, 1757 bool* result); 1758 1759 /** 1760 * @brief Obtains the ISO-8859-1-encoded string corresponding to the given ArkTS value. 1761 * @param env Current running virtual machine context. 1762 * @param value ArkTS string. 1763 * @param buf Destination buffer that will be filled with the provided ISO-8859-1-encoded string. 1764 * @param bufsize The size of the buffer 'buf'. 1765 * @param result The length of the string in ISO-8859-1-encoded format. 1766 * 1767 * @return Returns the function execution status. 1768 * {@link napi_ok } If the function executed successfully.\n 1769 * {@link napi_invalid_arg } If the param env and(or) value is nullptr;\n 1770 * If the param buf and result both are nullptr.\n 1771 * {@link napi_string_expected } If a non-string ArkTS value passed in it.\n 1772 * @since 10 1773 */ 1774 NAPI_EXTERN napi_status napi_get_value_string_latin1(napi_env env, 1775 napi_value value, 1776 char* buf, 1777 size_t bufsize, 1778 size_t* result); 1779 1780 /** 1781 * @brief Obtains the UTF8-encoded string corresponding to the given ArkTS value. 1782 * @param env Current running virtual machine context. 1783 * @param value ArkTS string. 1784 * @param buf Destination buffer that will be filled with the provided UTF8-encoded string. 1785 * @param bufsize The size of the buffer 'buf'. 1786 * @param result The length of the string in UTF8-encoded format. 1787 * 1788 * @return Returns the function execution status. 1789 * {@link napi_ok } If the function executed successfully.\n 1790 * {@link napi_invalid_arg } If the param env and(or) value is nullptr;\n 1791 * If the param buf and result both are nullptr.\n 1792 * {@link napi_string_expected } If a non-string ArkTS value passed in it.\n 1793 * @since 10 1794 */ 1795 NAPI_EXTERN napi_status napi_get_value_string_utf8(napi_env env, 1796 napi_value value, 1797 char* buf, 1798 size_t bufsize, 1799 size_t* result); 1800 1801 /** 1802 * @brief Obtains the ArkTS undefined value. 1803 * @param env Current running virtual machine context. 1804 * @param result The ArkTS undefined value. 1805 * 1806 * @return Returns the function execution status. 1807 * {@link napi_ok } If the function executed successfully.\n 1808 * {@link napi_invalid_arg } If the parameter env and(or) result is nullptr.\n 1809 * @since 10 1810 */ 1811 NAPI_EXTERN napi_status napi_get_undefined(napi_env env, napi_value* result); 1812 1813 /** 1814 * @brief Obtains the ArkTS null value. 1815 * @param env Current running virtual machine context. 1816 * @param result The ArkTS null value. 1817 * 1818 * @return Returns the function execution status. 1819 * {@link napi_ok } If the function executed successfully.\n 1820 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1821 * @since 10 1822 */ 1823 NAPI_EXTERN napi_status napi_get_null(napi_env env, napi_value* result); 1824 1825 /** 1826 * @brief Obtains the ArkTS global object. 1827 * @param env Current running virtual machine context. 1828 * @param result The ArkTS global Object. 1829 * 1830 * @return Returns the function execution status. 1831 * {@link napi_ok } If the function executed successfully.\n 1832 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1833 * @since 10 1834 */ 1835 NAPI_EXTERN napi_status napi_get_global(napi_env env, napi_value* result); 1836 1837 /** 1838 * @brief Obtains the ArkTS singleton value corresponding to given C primitive boolean value. 1839 * @param env Current running virtual machine context. 1840 * @param value C primitive boolean value. 1841 * @param result The ArkTS singleton value equivalent of C primitive boolean value. 1842 * 1843 * @return Returns the function execution status. 1844 * {@link napi_ok } If the function executed successfully.\n 1845 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1846 * @since 10 1847 */ 1848 NAPI_EXTERN napi_status napi_get_boolean(napi_env env, 1849 bool value, 1850 napi_value* result); 1851 1852 // Methods to create Primitive types/Objects 1853 1854 /** 1855 * @brief Creates a default ArkTS object. 1856 * @param env Current running virtual machine context. 1857 * @param result napi_value representing an ArkTS object. 1858 * 1859 * @return Returns the function execution status. 1860 * {@link napi_ok } If the function executed successfully.\n 1861 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1862 * @since 10 1863 */ 1864 NAPI_EXTERN napi_status napi_create_object(napi_env env, napi_value* result); 1865 1866 /** 1867 * @brief Creates an ArkTS array. 1868 * @param env Current running virtual machine context. 1869 * @param result napi_value representing an ArkTS Array. 1870 * 1871 * @return Returns the function execution status. 1872 * {@link napi_ok } If the function executed successfully.\n 1873 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1874 * @since 10 1875 */ 1876 NAPI_EXTERN napi_status napi_create_array(napi_env env, napi_value* result); 1877 1878 /** 1879 * @brief Creates an ArkTS array of the specified length. 1880 * @param env Current running virtual machine context. 1881 * @param length The length of the Array. 1882 * @param result napi_value representing an ArkTS Array. 1883 * 1884 * @return Returns the function execution status. 1885 * {@link napi_ok } If the function executed successfully.\n 1886 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1887 * @since 10 1888 */ 1889 NAPI_EXTERN napi_status napi_create_array_with_length(napi_env env, 1890 size_t length, 1891 napi_value* result); 1892 1893 /** 1894 * @brief Creates an ArkTS number from C double data. 1895 * @param env Current running virtual machine context. 1896 * @param value The double value to be represented in ArkTS. 1897 * @param result A napi_value representing an ArkTS number. 1898 * 1899 * @return Returns the function execution status. 1900 * {@link napi_ok } If the function executed successfully.\n 1901 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1902 * @since 10 1903 */ 1904 NAPI_EXTERN napi_status napi_create_double(napi_env env, 1905 double value, 1906 napi_value* result); 1907 1908 /** 1909 * @brief Creates an ArkTS number from C int32_t data. 1910 * @param env Current running virtual machine context. 1911 * @param value The int32 value to be represented in ArkTS. 1912 * @param result A napi_value representing an ArkTS number. 1913 * 1914 * @return Returns the function execution status. 1915 * {@link napi_ok } If the function executed successfully.\n 1916 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1917 * @since 10 1918 */ 1919 NAPI_EXTERN napi_status napi_create_int32(napi_env env, 1920 int32_t value, 1921 napi_value* result); 1922 1923 /** 1924 * @brief Creates an ArkTS number from C uint32_t data. 1925 * @param env Current running virtual machine context. 1926 * @param value The uint32 value to be represented in ArkTS. 1927 * @param result A napi_value representing an ArkTS number. 1928 * 1929 * @return Returns the function execution status. 1930 * {@link napi_ok } If the function executed successfully.\n 1931 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1932 * @since 10 1933 */ 1934 NAPI_EXTERN napi_status napi_create_uint32(napi_env env, 1935 uint32_t value, 1936 napi_value* result); 1937 1938 /** 1939 * @brief Creates an ArkTS number from C int64_t data. 1940 * @param env Current running virtual machine context. 1941 * @param value The int64 value to be represented in ArkTS. 1942 * @param result A napi_value representing an ArkTS number. 1943 * 1944 * @return Returns the function execution status. 1945 * {@link napi_ok } If the function executed successfully.\n 1946 * {@link napi_invalid_arg } If the param env and(or) result is nullptr.\n 1947 * @since 10 1948 */ 1949 NAPI_EXTERN napi_status napi_create_int64(napi_env env, 1950 int64_t value, 1951 napi_value* result); 1952 1953 /** 1954 * @brief Creates an ArkTS string from an ISO-8859-1-encoded C string. 1955 * @param env Current running virtual machine context. 1956 * @param str C string encoded in ISO-8859-1-encoded format. 1957 * @param length The length of the C string 'str'. 1958 * @param result Result of the ArkTS string from the ISO-8859-1-encoded C string. 1959 * 1960 * @return Returns the function execution status. 1961 * {@link napi_ok } If the function executed successfully.\n 1962 * {@link napi_invalid_arg } If the param env, str and(or) result is nullptr.\n 1963 * @since 10 1964 */ 1965 NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env, 1966 const char* str, 1967 size_t length, 1968 napi_value* result); 1969 1970 /** 1971 * @brief Creates an ArkTS string from a UTF8-encoded C string. 1972 * @param env Current running virtual machine context. 1973 * @param str C string encoded in UTF8 format. 1974 * @param length The length of the C string 'str'. 1975 * @param result Result of the ArkTS string from the UTF8-encoded C string. 1976 * 1977 * @return Returns the function execution status. 1978 * {@link napi_ok } If the function executed successfully.\n 1979 * {@link napi_invalid_arg } If the param env, str and(or) result is nullptr.\n 1980 * @since 10 1981 */ 1982 NAPI_EXTERN napi_status napi_create_string_utf8(napi_env env, 1983 const char* str, 1984 size_t length, 1985 napi_value* result); 1986 1987 /** 1988 * @brief Checks if the ArkTS value is an ArkTS ArrayBuffer. 1989 * @param env Current running virtual machine context. 1990 * @param value The ArkTS value to check. 1991 * @param result Whether the given ArkTS value is an ArkTS ArrayBuffer. 1992 * 1993 * @return Returns the function execution status. 1994 * {@link napi_ok } If the function executed successfully.\n 1995 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 1996 * @since 10 1997 */ 1998 NAPI_EXTERN napi_status napi_is_arraybuffer(napi_env env, 1999 napi_value value, 2000 bool* result); 2001 /** 2002 * @brief Creates an ArkTS ArrayBuffer of the specified size. 2003 * @param env Current running virtual machine context. 2004 * @param byte_length The length in bytes of the array buffer. 2005 * @param data The byte buffer of the ArrayBuffer. 2006 * @param result A napi_value representing an ArkTS ArrayBuffer. 2007 * 2008 * @return Returns the function execution status. 2009 * {@link napi_ok } If the function executed successfully.\n 2010 * {@link napi_invalid_arg } If the param env, data and(or) result is nullptr.\n 2011 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2012 * @since 10 2013 */ 2014 NAPI_EXTERN napi_status napi_create_arraybuffer(napi_env env, 2015 size_t byte_length, 2016 void** data, 2017 napi_value* result); 2018 2019 /** 2020 * @brief Allocates a JS value with external data. 2021 * @param env Current running virtual machine context. 2022 * @param data Allocates a JS value that references external data. 2023 * @param finalize_cb Optional callback to call when the external value is being collected. 2024 * @param finalize_hint Optional hint that can be passed to the finalize callback function during the garbage 2025 * collection process. 2026 * @param result A napi_value representing an external value. 2027 * 2028 * @return Returns the function execution status. 2029 * {@link napi_ok } If the function executed successfully.\n 2030 * {@link napi_invalid_arg } If the param env or result is nullptr.\n 2031 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2032 * @since 10 2033 */ 2034 NAPI_EXTERN napi_status napi_create_external(napi_env env, 2035 void* data, 2036 napi_finalize finalize_cb, 2037 void* finalize_hint, 2038 napi_value* result); 2039 2040 /** 2041 * @brief The underlying data that ArrayBuffer point to. 2042 * @param env Current running virtual machine context. 2043 * @param external_data Allocates an ArkTS value that references external data. 2044 * @param byte_length The length in bytes of the underlying buffer. 2045 * @param finalize_cb Optional callback to call when the ArrayBuffer is being collected. 2046 * @param finalize_hint Optional hint that can be passed to the finalize callback function during the garbage 2047 * collection process. 2048 * @param result A napi_value representing an ArkTS ArrayBuffer. 2049 * 2050 * @return Returns the function execution status. 2051 * {@link napi_ok } If the function executed successfully.\n 2052 * {@link napi_invalid_arg } If the param env, external_data, finalize_cb and(or) result is nullptr.\n 2053 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2054 * @since 10 2055 */ 2056 NAPI_EXTERN napi_status napi_create_external_arraybuffer(napi_env env, 2057 void* external_data, 2058 size_t byte_length, 2059 napi_finalize finalize_cb, 2060 void* finalize_hint, 2061 napi_value* result); 2062 2063 /** 2064 * @brief Obtains the underlying data buffer of ArrayBuffer and its length. 2065 * @param env Current running virtual machine context. 2066 * @param arraybuffer The napi_value representing the ArrayBuffer being queried. 2067 * @param data The underlying data buffer of the ArrayBuffer. 2068 * @param byte_length Length in bytes of the underlying data buffer. 2069 * 2070 * @return Returns the function execution status. 2071 * {@link napi_ok } If the function executed successfully.\n 2072 * {@link napi_invalid_arg } If the param env, arraybuffer and(or) byte_length is nullptr.\n 2073 * {@link napi_arraybuffer_expected } If the param is neither ArkTS TypedArray nor SendableArrayBuffer.\n 2074 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2075 * @since 10 2076 */ 2077 NAPI_EXTERN napi_status napi_get_arraybuffer_info(napi_env env, 2078 napi_value arraybuffer, 2079 void** data, 2080 size_t* byte_length); 2081 2082 /** 2083 * @brief Checks if the ArkTS value is an ArkTS TypedArray. 2084 * @param env Current running virtual machine context. 2085 * @param value The ArkTS value to check. 2086 * @param result Whether the given ArkTS value is an ArkTS TypedArray. 2087 * 2088 * @return Returns the function execution status. 2089 * {@link napi_ok } If the function executed successfully.\n 2090 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2091 * @since 10 2092 */ 2093 NAPI_EXTERN napi_status napi_is_typedarray(napi_env env, 2094 napi_value value, 2095 bool* result); 2096 /** 2097 * @brief Creates an ArkTS TypeArray from an existing ArrayBuffer. 2098 * @param env Current running virtual machine context. 2099 * @param type The element datatype of the TypedArray. 2100 * @param length Number of elements in the TypedArray. 2101 * @param arraybuffer The underlying ArrayBuffer that supports the TypedArray. 2102 * @param byte_offset The byte offset within the ArrayBuffer from which to start projecting the TypedArray. 2103 * @param result A napi_value representing an ArkTS TypedArray. 2104 * 2105 * @return Returns the function execution status. 2106 * {@link napi_ok } If the function executed successfully.\n 2107 * {@link napi_invalid_arg } If the param env, arraybuffer and(or) result is nullptr;\n 2108 * If param type is not a valid napi_typedarray_type.\n 2109 * {@link napi_arraybuffer_expected } If a non-arraybuffer ArkTS value passed in it.\n 2110 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2111 * @since 10 2112 */ 2113 NAPI_EXTERN napi_status napi_create_typedarray(napi_env env, 2114 napi_typedarray_type type, 2115 size_t length, 2116 napi_value arraybuffer, 2117 size_t byte_offset, 2118 napi_value* result); 2119 2120 /** 2121 * @brief Obtains properties of a TypedArray. 2122 * @param env Current running virtual machine context. 2123 * @param typedarray The napi_value for the TypedArray whose properties are being checked. 2124 * @param type The datatype of elements in the TypedArray. 2125 * @param length The number of elements in the TypedArray. 2126 * @param data The data buffer underlying the TypedArray adjusted by the byte_offset. 2127 * @param arraybuffer The ArrayBuffer underlying the TypedArray. 2128 * @param byte_offset The byte offset within the underlying arraybuffer 2129 * 2130 * @return Returns the function execution status. 2131 * {@link napi_ok } If the function executed successfully.\n 2132 * {@link napi_invalid_arg } If the param env and(or) typedarray is nullptr;\n 2133 * If the param typedarray is neither ArkTS TypedArray nor SendableTypedArray.\n 2134 * @since 10 2135 */ 2136 NAPI_EXTERN napi_status napi_get_typedarray_info(napi_env env, 2137 napi_value typedarray, 2138 napi_typedarray_type* type, 2139 size_t* length, 2140 void** data, 2141 napi_value* arraybuffer, 2142 size_t* byte_offset); 2143 2144 /** 2145 * @brief Creates an ArkTS DataView from an existing ArrayBuffer. 2146 * @param env Current running virtual machine context. 2147 * @param length Number of elements in the DataView. 2148 * @param arraybuffer The underlying ArrayBuffer that supports the DataView. 2149 * @param byte_offset The byte offset within the ArrayBuffer from which to start projecting the DataView. 2150 * @param result A napi_value representing an ArkTS DataView. 2151 * 2152 * @return Returns the function execution status. 2153 * {@link napi_ok } If the function executed successfully.\n 2154 * {@link napi_invalid_arg } If the param env, arraybuffer and(or) result is nullptr.\n 2155 * {@link napi_arraybuffer_expected } If a non-arraybuffer ArkTS value passed in it.\n 2156 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2157 * If the sum of byte_length and length is greater than the byte length of\n 2158 * the arraybuffer.\n 2159 * @since 10 2160 */ 2161 NAPI_EXTERN napi_status napi_create_dataview(napi_env env, 2162 size_t length, 2163 napi_value arraybuffer, 2164 size_t byte_offset, 2165 napi_value* result); 2166 2167 /** 2168 * @brief Checks if the ArkTS value is an ArkTS DataView. 2169 * @param env Current running virtual machine context. 2170 * @param value The ArkTS value to check. 2171 * @param result Whether the given ArkTS value is an ArkTS DataView. 2172 * 2173 * @return Returns the function execution status. 2174 * {@link napi_ok } If the function executed successfully.\n 2175 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2176 * @since 10 2177 */ 2178 NAPI_EXTERN napi_status napi_is_dataview(napi_env env, 2179 napi_value value, 2180 bool* result); 2181 2182 /** 2183 * @brief Obtains properties of a DataView. 2184 * @param env Current running virtual machine context. 2185 * @param dataview The napi_value for the DataView whose properties are being checked. 2186 * @param bytelength The number of elements in the DataView. 2187 * @param data The data buffer underlying the DataView. 2188 * @param arraybuffer The ArrayBuffer underlying the DataView. 2189 * @param byte_offset The byte offset within the underlying arraybuffer 2190 * 2191 * @return Returns the function execution status. 2192 * {@link napi_ok } If the function executed successfully.\n 2193 * {@link napi_invalid_arg } If the param env and(or) dataview is nullptr;\n 2194 * If non-dataview ArkTS value passed in.\n 2195 * @since 10 2196 */ 2197 NAPI_EXTERN napi_status napi_get_dataview_info(napi_env env, 2198 napi_value dataview, 2199 size_t* bytelength, 2200 void** data, 2201 napi_value* arraybuffer, 2202 size_t* byte_offset); 2203 2204 /** 2205 * @brief Obtains the array length. 2206 * @param env Current running virtual machine context. 2207 * @param value The napi_value representing the ArkTS Array being queried. 2208 * @param result The length of the array. 2209 * 2210 * @return Returns the function execution status. 2211 * {@link napi_ok } If the function executed successfully.\n 2212 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr;\n 2213 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2214 * @since 10 2215 */ 2216 NAPI_EXTERN napi_status napi_get_array_length(napi_env env, 2217 napi_value value, 2218 uint32_t* result); 2219 /** 2220 * @brief Obtains the prototype of an ArkTS object. 2221 * @param env Current running virtual machine context. 2222 * @param object The napi_value representing an ArkTS Object whose prototype to return. 2223 * @param result A napi_value representing prototype of the object. 2224 * 2225 * @return Returns the function execution status. 2226 * {@link napi_ok } If the function executed successfully.\n 2227 * {@link napi_invalid_arg } If the param env, object or result is nullptr;\n 2228 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2229 * @since 10 2230 */ 2231 NAPI_EXTERN napi_status napi_get_prototype(napi_env env, 2232 napi_value object, 2233 napi_value* result); 2234 2235 /** 2236 * @brief Obtains the external data pointer previously passed through napi_create_external(). 2237 * @param env Current running virtual machine context. 2238 * @param value JavaScript external value. 2239 * @param result The data wrapped by the JavaScript external value. 2240 2241 * @return Returns the function execution status. 2242 * {@link napi_ok } If the function executed successfully.\n 2243 * {@link napi_invalid_arg } If the param env, value or result is nullptr;\n 2244 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2245 * @since 10 2246 */ 2247 NAPI_EXTERN napi_status napi_get_value_external(napi_env env, 2248 napi_value value, 2249 void** result); 2250 2251 /** 2252 * @brief Coerce the given ArkTS value to an ArkTS boolean value. 2253 * @param env Current running virtual machine context. 2254 * @param value The ArkTS value to coerce. 2255 * @param result The coerced ArkTS boolean value. 2256 * 2257 * @return Returns the function execution status. 2258 * {@link napi_ok } If the function executed successfully.\n 2259 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2260 * @since 10 2261 */ 2262 NAPI_EXTERN napi_status napi_coerce_to_bool(napi_env env, 2263 napi_value value, 2264 napi_value* result); 2265 2266 /** 2267 * @brief Coerce the given ArkTS value to an ArkTS number value. 2268 * @param env Current running virtual machine context. 2269 * @param value The ArkTS value to coerce. 2270 * @param result The coerced ArkTS number value. 2271 * 2272 * @return Returns the function execution status. 2273 * {@link napi_ok } If the function executed successfully.\n 2274 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2275 * @since 10 2276 */ 2277 NAPI_EXTERN napi_status napi_coerce_to_number(napi_env env, 2278 napi_value value, 2279 napi_value* result); 2280 2281 /** 2282 * @brief Coerce the given ArkTS value to an ArkTS object value. 2283 * @param env Current running virtual machine context. 2284 * @param value The ArkTS value to coerce. 2285 * @param result The coerced ArkTS object value. 2286 * 2287 * @return Returns the function execution status. 2288 * {@link napi_ok } If the function executed successfully.\n 2289 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2290 * @since 10 2291 */ 2292 NAPI_EXTERN napi_status napi_coerce_to_object(napi_env env, 2293 napi_value value, 2294 napi_value* result); 2295 2296 /** 2297 * @brief Coerce the given ArkTS value to an ArkTS string value. 2298 * @param env Current running virtual machine context. 2299 * @param value The ArkTS value to coerce. 2300 * @param result The coerced ArkTS string value. 2301 * 2302 * @return Returns the function execution status. 2303 * {@link napi_ok } If the function executed successfully.\n 2304 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2305 * @since 10 2306 */ 2307 NAPI_EXTERN napi_status napi_coerce_to_string(napi_env env, 2308 napi_value value, 2309 napi_value* result); 2310 2311 /** 2312 * @brief Invoke instanceof operation on the object. 2313 * @param env Current running virtual machine context. 2314 * @param object The ArkTS object to check. 2315 * @param constructor The ArkTS constructor function to check against. 2316 * @param result Set to true if the given ArkTS object instanceof constructor. 2317 * 2318 * @return Returns the function execution status. 2319 * {@link napi_ok } If the function executed successfully.\n 2320 * {@link napi_invalid_arg } If the param env, object, constructor and(or) result is nullptr.\n 2321 * {@link napi_object_expected } If the param object is not an ArkTS object value.\n 2322 * {@link napi_function_expected } If the param constructor is not an ArkTS function value.\n 2323 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2324 * @since 10 2325 */ 2326 NAPI_EXTERN napi_status napi_instanceof(napi_env env, 2327 napi_value object, 2328 napi_value constructor, 2329 bool* result); 2330 2331 /** 2332 * @brief Checks if the ArkTS value is an ArkTS Array. 2333 * @param env Current running virtual machine context. 2334 * @param value The ArkTS value to check. 2335 * @param result Whether the given ArkTS value is an ArkTS Array. 2336 * 2337 * @return Returns the function execution status. 2338 * {@link napi_ok } If the function executed successfully.\n 2339 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2340 * @since 10 2341 */ 2342 NAPI_EXTERN napi_status napi_is_array(napi_env env, 2343 napi_value value, 2344 bool* result); 2345 2346 /** 2347 * @brief Checks if the two ArkTS values are equal. 2348 * @param env Current running virtual machine context. 2349 * @param lhs The ArkTS value to check. 2350 * @param rhs The ArkTS value to check against. 2351 * @param result Whether the two given ArkTS values are equal. 2352 * 2353 * @return Returns the function execution status. 2354 * {@link napi_ok } If the function executed successfully.\n 2355 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2356 * @since 10 2357 */ 2358 NAPI_EXTERN napi_status napi_strict_equals(napi_env env, 2359 napi_value lhs, 2360 napi_value rhs, 2361 bool* result); 2362 2363 /** 2364 * @brief Obtains the names of the enumerable properties of object as an Array of Strings. The keys that are symbols 2365 * will not be included. 2366 * @param env Current running virtual machine context. 2367 * @param object The ArkTS object from which the property is retrieved. 2368 * @param result An ArkTS Array that contains the attribute names of the object. 2369 * 2370 * @return Returns the function execution status. 2371 * {@link napi_ok } If the function executed successfully.\n 2372 * {@link napi_invalid_arg } If the param env, value and(or) result is nullptr.\n 2373 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2374 * @since 10 2375 */ 2376 NAPI_EXTERN napi_status napi_get_property_names(napi_env env, 2377 napi_value object, 2378 napi_value* result); 2379 2380 /** 2381 * @brief Set a property on the given ArkTS Object. 2382 * @param env Current running virtual machine context. 2383 * @param object The ArkTS object. 2384 * @param key The name of the property to set. 2385 * @param value The property value. 2386 * 2387 * @return Returns the function execution status. 2388 * {@link napi_ok } If the function executed successfully.\n 2389 * {@link napi_invalid_arg } If the param env, object, key and(or) value is nullptr.\n 2390 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2391 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2392 * @since 10 2393 */ 2394 NAPI_EXTERN napi_status napi_set_property(napi_env env, 2395 napi_value object, 2396 napi_value key, 2397 napi_value value); 2398 2399 /** 2400 * @brief Get the requests property of the given ArkTS Object. 2401 * @param env Current running virtual machine context. 2402 * @param object The ArkTS object. 2403 * @param key The name of the property to get. 2404 * @param result The value of the property. 2405 * 2406 * @return Returns the function execution status. 2407 * {@link napi_ok } If the function executed successfully.\n 2408 * {@link napi_invalid_arg } If the param env, object, key and(or) result is nullptr.\n 2409 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2410 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2411 * @since 10 2412 */ 2413 NAPI_EXTERN napi_status napi_get_property(napi_env env, 2414 napi_value object, 2415 napi_value key, 2416 napi_value* result); 2417 2418 /** 2419 * @brief Check if the given ArkTS Object has the named property or not. 2420 * @param env Current running virtual machine context. 2421 * @param object The ArkTS object. 2422 * @param key The name of the property to check. 2423 * @param result Whether the property exists on the object or not. 2424 * 2425 * @return Returns the function execution status. 2426 * {@link napi_ok } If the function executed successfully.\n 2427 * {@link napi_invalid_arg } If the param env, object, key and(or) result is nullptr.\n 2428 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2429 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2430 * @since 10 2431 */ 2432 NAPI_EXTERN napi_status napi_has_property(napi_env env, 2433 napi_value object, 2434 napi_value key, 2435 bool* result); 2436 /** 2437 * @brief Delete the named property of the given ArkTS Object. 2438 * @param env Current running virtual machine context. 2439 * @param object The ArkTS object. 2440 * @param key The name of the property to delete. 2441 * @param result Whether the execution is succeed or not. Can optionally be ignored by passing nullptr. 2442 * 2443 * @return Returns the function execution status. 2444 * {@link napi_ok } If the function executed successfully.\n 2445 * {@link napi_invalid_arg } If the param env, object and(or) key is nullptr.\n 2446 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2447 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2448 * @since 10 2449 */ 2450 NAPI_EXTERN napi_status napi_delete_property(napi_env env, 2451 napi_value object, 2452 napi_value key, 2453 bool* result); 2454 2455 /** 2456 * @brief Set a property on the given ArkTS Object. 2457 * @param env Current running virtual machine context. 2458 * @param object The ArkTS object. 2459 * @param utf8name The name of the property to set. 2460 * @param value The property value. 2461 * 2462 * @return Returns the function execution status. 2463 * {@link napi_ok } If the function executed successfully.\n 2464 * {@link napi_invalid_arg } If the param env, object, utf8name and(or) value is nullptr.\n 2465 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2466 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2467 * @since 10 2468 */ 2469 NAPI_EXTERN napi_status napi_set_named_property(napi_env env, 2470 napi_value object, 2471 const char* utf8name, 2472 napi_value value); 2473 2474 /** 2475 * @brief Get the requests property of the given ArkTS Object. 2476 * @param env Current running virtual machine context. 2477 * @param object The ArkTS object. 2478 * @param utf8name The name of the property to get. 2479 * @param result The value of the property. 2480 * 2481 * @return Returns the function execution status. 2482 * {@link napi_ok } If the function executed successfully.\n 2483 * {@link napi_invalid_arg } If the param env, object, utf8name and(or) result is nullptr.\n 2484 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2485 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2486 * @since 10 2487 */ 2488 NAPI_EXTERN napi_status napi_get_named_property(napi_env env, 2489 napi_value object, 2490 const char* utf8name, 2491 napi_value* result); 2492 2493 /** 2494 * @brief Check if the given ArkTS Object has the named property or not. 2495 * @param env Current running virtual machine context. 2496 * @param object The ArkTS object. 2497 * @param utf8name The name of the property to check. 2498 * @param result Whether the property exists on the object or not. 2499 * 2500 * @return Returns the function execution status. 2501 * {@link napi_ok } If the function executed successfully.\n 2502 * {@link napi_invalid_arg } If the param env, object, utf8name and(or) result is nullptr.\n 2503 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2504 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2505 * @since 10 2506 */ 2507 NAPI_EXTERN napi_status napi_has_named_property(napi_env env, 2508 napi_value object, 2509 const char* utf8name, 2510 bool* result); 2511 2512 /** 2513 * @brief Set a element on the given ArkTS Array. 2514 * @param env Current running virtual machine context. 2515 * @param object The ArkTS Array. 2516 * @param index The index of the element to set. 2517 * @param value The element value. 2518 * 2519 * @return Returns the function execution status. 2520 * {@link napi_ok } If the function executed successfully.\n 2521 * {@link napi_invalid_arg } If the param env, object and(or) value is nullptr.\n 2522 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2523 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2524 * @since 10 2525 */ 2526 NAPI_EXTERN napi_status napi_set_element(napi_env env, 2527 napi_value object, 2528 uint32_t index, 2529 napi_value value); 2530 2531 /** 2532 * @brief Get the requests element of the given ArkTS Array. 2533 * @param env Current running virtual machine context. 2534 * @param object The ArkTS Array. 2535 * @param index The index of the element to get. 2536 * @param result The value of the element. 2537 * 2538 * @return Returns the function execution status. 2539 * {@link napi_ok } If the function executed successfully.\n 2540 * {@link napi_invalid_arg } If the param env, object and(or) result is nullptr.\n 2541 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2542 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2543 * @since 10 2544 */ 2545 NAPI_EXTERN napi_status napi_get_element(napi_env env, 2546 napi_value object, 2547 uint32_t index, 2548 napi_value* result); 2549 2550 /** 2551 * @brief Check if the given ArkTS Array has an element at the requested index. 2552 * @param env Current running virtual machine context. 2553 * @param object The ArkTS Array. 2554 * @param index The name of the property to check. 2555 * @param result Whether the property exists on the Array or not. 2556 * 2557 * @return Returns the function execution status. 2558 * {@link napi_ok } If the function executed successfully.\n 2559 * {@link napi_invalid_arg } If the param env, object and(or) result is nullptr.\n 2560 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2561 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2562 * @since 10 2563 */ 2564 NAPI_EXTERN napi_status napi_has_element(napi_env env, 2565 napi_value object, 2566 uint32_t index, 2567 bool* result); 2568 2569 /** 2570 * @brief Delete the special index from the given ArkTS Array. 2571 * @param env Current running virtual machine context. 2572 * @param object The ArkTS Array. 2573 * @param index The index of the element to delete. 2574 * @param result Whether the execution is succeed or not. Can optionally be ignored by passing nullptr. 2575 * 2576 * @return Returns the function execution status. 2577 * {@link napi_ok } If the function executed successfully.\n 2578 * {@link napi_invalid_arg } If the param env, object and(or) key is nullptr.\n 2579 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2580 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2581 * @since 10 2582 */ 2583 NAPI_EXTERN napi_status napi_delete_element(napi_env env, 2584 napi_value object, 2585 uint32_t index, 2586 bool* result); 2587 2588 /** 2589 * @brief Efficient define multiple properties on the given ArkTS Object by napi_property_descriptor. 2590 * @param env Current running virtual machine context. 2591 * @param object The ArkTS Object. 2592 * @param property_count The count of elements in the properties array. 2593 * @param properties The properties array. 2594 * 2595 * @return Returns the function execution status. 2596 * {@link napi_ok } If the function executed successfully.\n 2597 * {@link napi_invalid_arg } If the param env, object and(or) properties is nullptr.\n 2598 * {@link napi_object_expected } If the param object is not an ArkTS Object.\n 2599 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2600 * @since 10 2601 */ 2602 NAPI_EXTERN napi_status napi_define_properties(napi_env env, 2603 napi_value object, 2604 size_t property_count, 2605 const napi_property_descriptor* properties); 2606 2607 /** 2608 * @brief Invoke an ArkTS function. This is the primary mechanism to call back into JavaScript. 2609 * @param env Current running virtual machine context. 2610 * @param recv The this value passed to the called function 2611 * @param func The ArkTS function to be invoked. 2612 * @param argc The count of elements in the argv array. 2613 * @param argv ArkTS values passed in as arguments to the function. 2614 * @param result Whether the provided 'type_tag' is matched with the tag on the ArkTS object 'value'. 2615 * 2616 * @return Returns the function execution status. 2617 * {@link napi_ok } If the function executed successfully.\n 2618 * {@link napi_invalid_arg } If the param env and(or) func is nullptr. If argv is nullptr but argc greater\n 2619 * than 0.\n 2620 * {@link napi_function_expected } If the param func is not an ArkTS Function.\n 2621 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2622 * @since 10 2623 */ 2624 NAPI_EXTERN napi_status napi_call_function(napi_env env, 2625 napi_value recv, 2626 napi_value func, 2627 size_t argc, 2628 const napi_value* argv, 2629 napi_value* result); 2630 2631 /** 2632 * @brief Obtains callback details about the call like arguments, this from given callback info. 2633 * @param env Current running virtual machine context. 2634 * @param cbinfo The callback info. 2635 * @param argc Size of the argv array. 2636 * @param argv The Array which arguments will be copied to. If there are more arguments than the provided count, only 2637 * the requested number of arguments are copied. If there are fewer arguments provided, the rest argv is 2638 * filled with undefined. Can optionally be ignored by passing nullptr. 2639 * @param this_arg Receives the ArkTS this argument for the call. Can optionally be ignored by passing nullptr. 2640 * @param data Receives the data pointer for the callback. Can optionally be ignored by passing nullptr. 2641 * 2642 * @return Returns the function execution status. 2643 * {@link napi_ok } If the function executed successfully.\n 2644 * {@link napi_invalid_arg } If the param env and(or) cbinfo is nullptr.\n 2645 * @since 10 2646 */ 2647 NAPI_EXTERN napi_status napi_get_cb_info(napi_env env, 2648 napi_callback_info cbinfo, 2649 size_t* argc, 2650 napi_value* argv, 2651 napi_value* this_arg, 2652 void** data); 2653 2654 /** 2655 * @brief Obtains callback details about the call like arguments, this from given callback info. 2656 * @param env Current running virtual machine context. 2657 * @param cbinfo The callback info. 2658 * @param result The new.target of the constructor call. 2659 * 2660 * @return Returns the function execution status. 2661 * {@link napi_ok } If the function executed successfully.\n 2662 * {@link napi_invalid_arg } If the param env, cbinfo and(or) result is nullptr.\n 2663 * @since 10 2664 */ 2665 NAPI_EXTERN napi_status napi_get_new_target(napi_env env, 2666 napi_callback_info cbinfo, 2667 napi_value* result); 2668 2669 /** 2670 * @brief Instantiate a new ArkTS value using a given napi_value that represents the constructor for the object. 2671 * @param env Current running virtual machine context. 2672 * @param constructor The ArkTS function to be invoked as a constructor. 2673 * @param argc The count of elements in the argv array. 2674 * @param argv Array of ArkTS values representing the arguments to the constructor. If argc is 0 this parameter may 2675 * be omitted by passing in nullptr. 2676 * @param result The ArkTS object returned, which in this case is the constructed object. 2677 * 2678 * @return Returns the function execution status. 2679 * {@link napi_ok } If the function executed successfully.\n 2680 * {@link napi_invalid_arg } If the param env and(or) func is nullptr. If argv is nullptr but argc greater\n 2681 * than 0.\n 2682 * {@link napi_function_expected } If the param func is not an ArkTS Function.\n 2683 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2684 * @since 10 2685 */ 2686 NAPI_EXTERN napi_status napi_new_instance(napi_env env, 2687 napi_value constructor, 2688 size_t argc, 2689 const napi_value* argv, 2690 napi_value* result); 2691 2692 /** 2693 * @brief Wraps a native instance in a ArkTS object. The native instance can be retrieved later using napi_unwrap. 2694 * @param env Current running virtual machine context. 2695 * @param js_object The ArkTS object that will be the wrapper for the native object. 2696 * @param native_object The native instance that will be wrapped in the ArkTS object. 2697 * @param finalize_cb Native callback that can be used to free the native instance when the JavaScript object has 2698 * been garbage-collected. 2699 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 2700 * @param result Optional reference to the wrapped object. 2701 * 2702 * @return Returns the function execution status. 2703 * {@link napi_ok } If the function executed successfully.\n 2704 * {@link napi_invalid_arg } If the param env, js_object, native_object and(or) finalize_cb is nullptr.\n 2705 * {@link napi_object_expected } If the param js_object is not an ArkTS Object.\n 2706 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2707 * @since 10 2708 */ 2709 NAPI_EXTERN napi_status napi_wrap(napi_env env, 2710 napi_value js_object, 2711 void* native_object, 2712 napi_finalize finalize_cb, 2713 void* finalize_hint, 2714 napi_ref* result); 2715 2716 /** 2717 * @brief Retrieves a native instance that was previously wrapped in an ArkTS object using napi_wrap. 2718 * @param env Current running virtual machine context. 2719 * @param js_object The ArkTS object. 2720 * @param result Pointer to the wrapped native instance. 2721 * 2722 * @return Returns the function execution status. 2723 * {@link napi_ok } If the function executed successfully.\n 2724 * {@link napi_invalid_arg } If the param env, js_object and(or) result is nullptr.\n 2725 * {@link napi_object_expected } If the param js_object is not an ArkTS Object.\n 2726 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2727 * @since 10 2728 */ 2729 NAPI_EXTERN napi_status napi_unwrap(napi_env env, 2730 napi_value js_object, 2731 void** result); 2732 2733 /** 2734 * @brief Retrieves a native instance that was previously wrapped in the ArkTS object js_object using napi_wrap 2735 * and removes the wrapping. 2736 * @param env Current running virtual machine context. 2737 * @param js_object The ArkTS object. 2738 * @param result Pointer to the wrapped native instance. 2739 * 2740 * @return Returns the function execution status. 2741 * {@link napi_ok } If the function executed successfully.\n 2742 * {@link napi_invalid_arg } If the param env, js_object and(or) result is nullptr.\n 2743 * {@link napi_object_expected } If the param js_object is not an ArkTS Object.\n 2744 * {@link napi_pending_exception } If have uncaught exception, or exception occurred in execution.\n 2745 * @since 10 2746 */ 2747 NAPI_EXTERN napi_status napi_remove_wrap(napi_env env, 2748 napi_value js_object, 2749 void** result); 2750 2751 /** 2752 * @brief Allocate a work object that is used to execute logic asynchronously. 2753 * @param env Current running virtual machine context. 2754 * @param async_resource Not supported, can be ignored by passing nullptr. 2755 * @param async_resource_name Identifier for the kind of resource that is being provided for diagnostic information 2756 * exposed by the HiTrace. 2757 * @param execute The native function which should be called to execute the logic asynchronously. The given function 2758 * is called from a worker pool thread and can execute in parallel with the main event loop thread. 2759 * @param complete The native function which will be called when the asynchronous logic is completed or is cancelled. 2760 * The given function is called from the main event loop thread. 2761 * @param data User-provided data context. This will be passed back into the execute and complete functions. 2762 * @param result The handle to the newly created async work. 2763 * 2764 * @return Returns the function execution status. 2765 * {@link napi_ok } If the function executed successfully.\n 2766 * {@link napi_invalid_arg } If the param env, async_resource_name, execute, complete and(or) result is\n 2767 * nullptr.\n 2768 * @since 10 2769 */ 2770 NAPI_EXTERN napi_status napi_create_async_work(napi_env env, 2771 napi_value async_resource, 2772 napi_value async_resource_name, 2773 napi_async_execute_callback execute, 2774 napi_async_complete_callback complete, 2775 void* data, 2776 napi_async_work* result); 2777 2778 /** 2779 * @brief Free a previously allocated work object. 2780 * @param env Current running virtual machine context. 2781 * @param work The handle returned by the call to napi_create_async_work. 2782 * 2783 * @return Returns the function execution status. 2784 * {@link napi_ok } If the function executed successfully.\n 2785 * {@link napi_invalid_arg } If the param env and(or) work is nullptr.\n 2786 * @since 10 2787 */ 2788 NAPI_EXTERN napi_status napi_delete_async_work(napi_env env, 2789 napi_async_work work); 2790 2791 /** 2792 * @brief Requests that the previously allocated work be scheduled for execution. Once it returns successfully, 2793 * this API must not be called again with the same napi_async_work item or the result will be undefined. 2794 * @param env Current running virtual machine context. 2795 * @param work The handle returned by the call to napi_create_async_work. 2796 * 2797 * @return Returns the function execution status. 2798 * {@link napi_ok } If the function executed successfully.\n 2799 * {@link napi_invalid_arg } If the param env and(or) work is nullptr.\n 2800 * @since 10 2801 */ 2802 NAPI_EXTERN napi_status napi_queue_async_work(napi_env env, 2803 napi_async_work work); 2804 2805 /** 2806 * @brief Cancels queued work if it has not yet been started. If it has already started executing, it cannot be 2807 * cancelled. If successful, the complete callback will be invoked with a status value of napi_cancelled. 2808 * The work should not be deleted before the complete callback invocation, even if it has been successfully 2809 * cancelled. 2810 * @param env Current running virtual machine context. 2811 * @param work The handle returned by the call to napi_create_async_work. 2812 * 2813 * @return Returns the function execution status. 2814 * {@link napi_ok } If the function executed successfully.\n 2815 * {@link napi_invalid_arg } If the param env and(or) work is nullptr.\n 2816 * @since 10 2817 */ 2818 NAPI_EXTERN napi_status napi_cancel_async_work(napi_env env, 2819 napi_async_work work); 2820 2821 /** 2822 * @brief Wraps a native instance in an ArkTS object. 2823 * @param env The environment that the API is invoked under. 2824 * @param js_object The ArkTS object that will be the wrapper for the native object. 2825 * @param native_object The native instance that will be wrapped in the ArkTS object. 2826 * @param finalize_cb Optional native callback that can be used to free the native instance when the ArkTS object 2827 * has been garbage-collected. 2828 * @param async_finalizer A boolean value to determine that finalize_cb execute async or not. 2829 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 2830 * @param native_binding_size The size of native binding. 2831 * @param result Optional reference to the wrapped object. 2832 * 2833 * @return Returns the function execution status. 2834 * {@link napi_ok } If the function executed successfully.\n 2835 * {@link napi_invalid_arg } If the param env, js_object or native_object is nullptr.\n 2836 * {@link napi_object_expected } If the param js_object is not an ArkTS Object or Function.\n 2837 * {@link napi_pending_exception } There is an uncaught exception occurred before(in) execution.\n 2838 * @since 18 2839 */ 2840 NAPI_EXTERN napi_status napi_wrap_enhance(napi_env env, 2841 napi_value js_object, 2842 void* native_object, 2843 napi_finalize finalize_cb, 2844 bool async_finalizer, 2845 void* finalize_hint, 2846 size_t native_binding_size, 2847 napi_ref* result); 2848 2849 /** 2850 * @brief To create a new virtual machine context. 2851 * @param env Current running virtual machine context. 2852 * @param newEnv New generated virtual machine context which is expected to be used later. 2853 * 2854 * @return Returns the function execution status. 2855 * {@link napi_ok } If the function executed successfully.\n 2856 * {@link napi_invalid_arg } If the param env is nullptr.\n 2857 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 2858 * @since 20 2859 */ 2860 NAPI_EXTERN napi_status napi_create_ark_context(napi_env env, napi_env *newEnv); 2861 2862 /** 2863 * @brief To switch a virtual machine context which is expected to be used later. 2864 * @param env Designated Virtual machine context which is expected to be used as the current virtual machine context. 2865 * 2866 * @return Returns the function execution status. 2867 * {@link napi_ok } If the function executed successfully.\n 2868 * {@link napi_invalid_arg } If the param env is nullptr.\n 2869 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 2870 * @since 20 2871 */ 2872 NAPI_EXTERN napi_status napi_switch_ark_context(napi_env env); 2873 2874 /** 2875 * @brief To destroy a virtual machine context which will not be used again. 2876 * @param env Virtual machine context expected to be destroyed. 2877 * 2878 * @return Returns the function execution status. 2879 * {@link napi_ok } If the function executed successfully.\n 2880 * {@link napi_invalid_arg } If the param env is nullptr.\n 2881 * {@link napi_pending_exception } If have uncaught exception, or exception occurs in execution.\n 2882 * @since 20 2883 */ 2884 NAPI_EXTERN napi_status napi_destroy_ark_context(napi_env env); 2885 #ifdef __cplusplus 2886 } 2887 #endif 2888 /** @} */ 2889 #endif /* FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H */ 2890