1 /* 2 * Copyright (c) 2021 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 * @addtogroup JSVM 17 * @{ 18 * 19 * @brief Provides the standard JavaScript engine capabilities. 20 * 21 * Provides API to Provide independent, standard, and complete JavaScript engine capabilities for developers, 22 * including managing the engine lifecycle, compiling and running JS code, implementing JS/C++ cross language calls, 23 * and taking snapshots. 24 * 25 * @since 11 26 */ 27 28 /** 29 * @file jsvm.h 30 * 31 * @brief Provides the JSVM API define. 32 * 33 * Provides API to Provide independent, standard, and complete JavaScript engine capabilities for developers, 34 * including managing the engine lifecycle, compiling and running JS code, implementing JS/C++ cross language calls, 35 * and taking snapshots. 36 * @library libjsvm.so 37 * @kit ArkTS 38 * @syscap SystemCapability.ArkCompiler.JSVM 39 * @since 11 40 */ 41 42 43 #ifndef ARK_RUNTIME_JSVM_JSVM_H 44 #define ARK_RUNTIME_JSVM_JSVM_H 45 46 47 // This file needs to be compatible with C compilers. 48 #include <stdbool.h> // NOLINT(modernize-deprecated-headers) 49 #include <stddef.h> // NOLINT(modernize-deprecated-headers) 50 #include "jsvm_types.h" 51 52 // Use INT_MAX, this should only be consumed by the pre-processor anyway. 53 #define JSVM_VERSION_EXPERIMENTAL 2147483647 54 #ifndef JSVM_VERSION 55 #ifdef JSVM_EXPERIMENTAL 56 #define JSVM_VERSION JSVM_VERSION_EXPERIMENTAL 57 #else 58 // The baseline version for JSVM-API. 59 // The JSVM_VERSION controls which version will be used by default when 60 // compilling a native addon. If the addon developer specifically wants to use 61 // functions available in a new version of JSVM-API that is not yet ported in all 62 // LTS versions, they can set JSVM_VERSION knowing that they have specifically 63 // depended on that version. 64 #define JSVM_VERSION 8 65 #endif 66 #endif 67 68 #ifndef JSVM_EXTERN 69 #ifdef _WIN32 70 /** 71 * @brief externally visible. 72 * 73 * @since 11 74 */ 75 #define JSVM_EXTERN __declspec(dllexport) 76 #elif defined(__wasm__) 77 #define JSVM_EXTERN \ 78 __attribute__((visibility("default"))) \ 79 __attribute__((__import_module__("jsvm"))) 80 #else 81 #define JSVM_EXTERN __attribute__((visibility("default"))) 82 #endif 83 #endif 84 85 /** 86 * @brief auto length. 87 * 88 * @since 11 89 */ 90 #define JSVM_AUTO_LENGTH SIZE_MAX 91 92 #ifdef __cplusplus 93 #define EXTERN_C_START extern "C" { 94 #define EXTERN_C_END } 95 #else 96 #define EXTERN_C_START 97 #define EXTERN_C_END 98 #endif 99 100 EXTERN_C_START 101 102 /** 103 * @brief Init a JavaScript vm. 104 * 105 * @param options The options for initialize the JavaScript VM. 106 * @return Returns JSVM funtions result code. 107 * Returns {@link JSVM_OK } in all cases.\n 108 * @since 11 109 */ 110 JSVM_EXTERN JSVM_Status OH_JSVM_Init(const JSVM_InitOptions* options); 111 112 /** 113 * @brief This API create a new VM instance. 114 * 115 * @param options The options for create the VM instance. 116 * @param result The new VM instance. 117 * @return Returns JSVM funtions result code. 118 * {@link JSVM_OK } If the function executed successfully.\n 119 * @since 11 120 */ 121 JSVM_EXTERN JSVM_Status OH_JSVM_CreateVM(const JSVM_CreateVMOptions* options, 122 JSVM_VM* result); 123 124 /** 125 * @brief This function controls how Microtasks are invoked of the vm. If the method is not 126 * called, the default microtask policy of vm is JSVM_MicrotaskPolicy::JSVM_MICROTASK_AUTO. 127 * 128 * @param vm The VM instance to set mircrotasks policy. 129 * @param policy Policy for running microtasks. 130 * @return Returns JSVM_OK if the API succeeded. 131 * @since 18 132 */ 133 JSVM_EXTERN JSVM_Status OH_JSVM_SetMicrotaskPolicy(JSVM_VM vm, 134 JSVM_MicrotaskPolicy policy); 135 136 /** 137 * @brief Destroys VM instance. 138 * 139 * @param vm The VM instance to be Destroyed. 140 * @return Returns JSVM funtions result code. 141 * {@link JSVM_OK } If the function executed successfully.\n 142 * @since 11 143 */ 144 JSVM_EXTERN JSVM_Status OH_JSVM_DestroyVM(JSVM_VM vm); 145 146 /** 147 * @brief This API allocates a default JavaScript Proxy. It is the equivalent of 148 * doing new Proxy(target, handler) in JavaScript. 149 * 150 * @param env The environment that the API is invoked under. 151 * @param target A JSVM_Value representing the JavaScript Object which you want to proxy. 152 * @param handler A JSVM_Value representing the JavaScript Object that defines which 153 * operations will be intercepted and how to redefine intercepted operations. 154 * @param result A JSVM_Value representing a JavaScript Proxy. 155 * @return Returns JSVM functions result code. 156 * {@link JSVM_OK } if the API succeeded. \n 157 * {@link JSVM_INVALID_ARG } if the any of the input arguments is NULL. \n 158 * {@link JSVM_OBJECT_EXPECTED} if target or handler is not Javascript Object. \n 159 * {@link JSVM_PENDING_EXCEPTION} if an exception occurs. \n 160 * 161 * @since 18 162 */ 163 JSVM_EXTERN JSVM_Status OH_JSVM_CreateProxy(JSVM_Env env, 164 JSVM_Value target, 165 JSVM_Value handler, 166 JSVM_Value* result); 167 168 /** 169 * @brief This API checks if the value passed in is a Proxy. 170 * 171 * @param env The environment that the API is invoked under. 172 * @param value The JavaScript value to check. 173 * @param isProxy Whether the given value is Proxy. 174 * @return Returns JSVM functions result code. 175 * {@link JSVM_OK } if the API succeeded. \n 176 * {@link JSVM_INVALID_ARG } if the any of the input arguments is NULL. \n 177 * 178 * @since 18 179 */ 180 JSVM_EXTERN JSVM_Status OH_JSVM_IsProxy(JSVM_Env env, 181 JSVM_Value value, 182 bool* isProxy); 183 184 /** 185 * @brief This API gets target from proxy. 186 * 187 * @param env The environment that the API is invoked under. 188 * @param value JSVM_Value representing JavaScript Proxy whose target to return. 189 * @param result Target of the given proxy. 190 * @return Returns JSVM functions result code. 191 * {@link JSVM_OK } if the API succeeded. \n 192 * {@link JSVM_INVALID_ARG } if the any of the input arguments is NULL. \n 193 * {@link JSVM_INVALID_TYPE} if value is not a Javascript Proxy. \n 194 * 195 * @since 18 196 */ 197 JSVM_EXTERN JSVM_Status OH_JSVM_ProxyGetTarget(JSVM_Env env, 198 JSVM_Value value, 199 JSVM_Value* result); 200 201 /** 202 * @brief This API open a new VM scope for the VM instance. 203 * 204 * @param vm The VM instance to open scope for. 205 * @param result The new VM scope. 206 * @return Returns JSVM funtions result code. 207 * {@link JSVM_OK } If the function executed successfully.\n 208 * @since 11 209 */ 210 JSVM_EXTERN JSVM_Status OH_JSVM_OpenVMScope(JSVM_VM vm, 211 JSVM_VMScope* result); 212 213 /** 214 * @brief This function close the VM scope for the VM instance. 215 * 216 * @param vm The VM instance to close scope for. 217 * @param scope The VM scope to be closed. 218 * @return Returns JSVM funtions result code. 219 * {@link JSVM_OK } If the function executed successfully.\n 220 * @since 11 221 */ 222 JSVM_EXTERN JSVM_Status OH_JSVM_CloseVMScope(JSVM_VM vm, 223 JSVM_VMScope scope); 224 225 /** 226 * @brief This function create a new environment with optional properties for the context of the new environment. 227 * 228 * @param vm The VM instance that the env will be created in. 229 * @param propertyCount The number of elements in the properties array. 230 * @param properties The array of property descriptor. 231 * @param result The new environment created. 232 * @return Returns JSVM funtions result code. 233 * {@link JSVM_OK } If the function executed successfully.\n 234 * @since 11 235 */ 236 JSVM_EXTERN JSVM_Status OH_JSVM_CreateEnv(JSVM_VM vm, 237 size_t propertyCount, 238 const JSVM_PropertyDescriptor* properties, 239 JSVM_Env* result); 240 241 /** 242 * @brief This function create a new environment from the start snapshot of the vm. 243 * 244 * @param vm The VM instance that the env will be created in. 245 * @param index The index of the environment in the snapshot. 246 * @param result The new environment created. 247 * @return Returns JSVM funtions result code. 248 * {@link JSVM_OK } If the function executed successfully.\n 249 * @since 11 250 */ 251 JSVM_EXTERN JSVM_Status OH_JSVM_CreateEnvFromSnapshot(JSVM_VM vm, 252 size_t index, 253 JSVM_Env* result); 254 255 /** 256 * @brief This function destroys the environment. 257 * 258 * @param env The environment to be destroyed. 259 * @return Returns JSVM funtions result code. 260 * {@link JSVM_OK } If the function executed successfully.\n 261 * @since 11 262 */ 263 JSVM_EXTERN JSVM_Status OH_JSVM_DestroyEnv(JSVM_Env env); 264 265 /** 266 * @brief This function open a new environment scope. 267 * 268 * @param env The environment that the JSVM-API call is invoked under. 269 * @param result The new environment scope. 270 * @return Returns JSVM funtions result code. 271 * {@link JSVM_OK } If the function executed successfully.\n 272 * @since 11 273 */ 274 JSVM_EXTERN JSVM_Status OH_JSVM_OpenEnvScope(JSVM_Env env, 275 JSVM_EnvScope* result); 276 277 /** 278 * @brief This function closes the environment scope of the environment. 279 * 280 * @param env The environment that the JSVM-API call is invoked under. 281 * @param scope The environment scope to be closed. 282 * @return Returns JSVM funtions result code. 283 * {@link JSVM_OK } If the function executed successfully.\n 284 * @since 11 285 */ 286 JSVM_EXTERN JSVM_Status OH_JSVM_CloseEnvScope(JSVM_Env env, 287 JSVM_EnvScope scope); 288 289 /** 290 * @brief This function retrieves the VM instance of the given environment. 291 * 292 * @param env The environment that the JSVM-API call is invoked under. 293 * @param result The VM instance of the environment. 294 * @return Returns JSVM funtions result code. 295 * Returns {@link JSVM_OK } in all cases.\n 296 * @since 12 297 */ 298 JSVM_EXTERN JSVM_Status OH_JSVM_GetVM(JSVM_Env env, 299 JSVM_VM* result); 300 301 /** 302 * @brief This function compiles a string of JavaScript code and returns the compiled script. 303 * 304 * @param env The environment that the JSVM-API call is invoked under. 305 * @param script A JavaScript string containing the script yo be compiled. 306 * @param cachedData Optional code cache data for the script. 307 * @param cacheDataLength The length of cachedData array. 308 * @param eagerCompile Whether to compile the script eagerly. 309 * @param cacheRejected Whether the code cache rejected by compilation. 310 * @param result The compiled script. 311 * @return Returns JSVM funtions result code. 312 * {@link JSVM_OK } If the function executed successfully.\n 313 * @since 11 314 */ 315 JSVM_EXTERN JSVM_Status OH_JSVM_CompileScript(JSVM_Env env, 316 JSVM_Value script, 317 const uint8_t* cachedData, 318 size_t cacheDataLength, 319 bool eagerCompile, 320 bool* cacheRejected, 321 JSVM_Script* result); 322 323 /** 324 * @brief This function compiles a string of JavaScript code with the source code information 325 * and returns the compiled script. 326 * 327 * @param env The environment that the JSVM-API call is invoked under. 328 * @param script A JavaScript string containing the script to be compiled. 329 * @param cachedData Optional code cache data for the script. 330 * @param cacheDataLength The length of cachedData array. 331 * @param eagerCompile Whether to compile the script eagerly. 332 * @param cacheRejected Whether the code cache rejected by compilation. 333 * @param origin The information of source code. 334 * @param result The compiled script. 335 * @return Returns JSVM funtions result code. 336 * {@link JSVM_OK } If the function executed successfully.\n 337 * @since 12 338 */ 339 JSVM_EXTERN JSVM_Status OH_JSVM_CompileScriptWithOrigin(JSVM_Env env, 340 JSVM_Value script, 341 const uint8_t* cachedData, 342 size_t cacheDataLength, 343 bool eagerCompile, 344 bool* cacheRejected, 345 JSVM_ScriptOrigin* origin, 346 JSVM_Script* result); 347 348 /** 349 * @brief This function creates code cache for the compiled script. 350 * 351 * @param env The environment that the JSVM-API call is invoked under. 352 * @param script A compiled script to create code cache for. 353 * @param data The data of the code cache. 354 * @param length The length of the code cache data. 355 * @return Returns JSVM funtions result code. 356 * {@link JSVM_OK } If the function executed successfully.\n 357 * @since 11 358 */ 359 JSVM_EXTERN JSVM_Status OH_JSVM_CreateCodeCache(JSVM_Env env, 360 JSVM_Script script, 361 const uint8_t** data, 362 size_t* length); 363 364 /** 365 * @brief This function executes a string of JavaScript code and returns its result with the following caveats: 366 * Unlike eval, this function does not allow the script to access the current lexical scope, and therefore also 367 * does not allow to access the module scope, meaning that pseudo-globals such as require will not be available. 368 * The script can access the global scope. Function and var declarations in the script will be added to the 369 * global object. Variable declarations made using let and const will be visible globally, but will not be added 370 * to the global object.The value of this is global within the script. 371 * 372 * @param env The environment that the API is invoked under. 373 * @param script A JavaScript string containing the script to execute. 374 * @param result The value resulting from having executed the script. 375 * @since 11 376 */ 377 JSVM_EXTERN JSVM_Status OH_JSVM_RunScript(JSVM_Env env, 378 JSVM_Script script, 379 JSVM_Value* result); 380 381 /** 382 * @brief This API associates data with the currently running JSVM environment. data can later be retrieved 383 * using OH_JSVM_GetInstanceData(). 384 * 385 * @param env The environment that the JSVM-API call is invoked under. 386 * @param data The data item to make available to bindings of this instance. 387 * @param finalizeCb The function to call when the environment is being torn down. The function receives 388 * data so that it might free it. JSVM_Finalize provides more details. 389 * @param finalizeHint Optional hint to pass to the finalize callback during collection. 390 * @return Returns JSVM funtions result code. 391 * {@link JSVM_OK } If the function executed successfully.\n 392 * @since 11 393 */ 394 JSVM_EXTERN JSVM_Status OH_JSVM_SetInstanceData(JSVM_Env env, 395 void* data, 396 JSVM_Finalize finalizeCb, 397 void* finalizeHint); 398 399 /** 400 * @brief This API retrieves data that was previously associated with the currently running JSVM environment 401 * via OH_JSVM_SetInstanceData(). If no data is set, the call will succeed and data will be set to NULL. 402 * 403 * @param env The environment that the JSVM-API call is invoked under. 404 * @param data The data item that was previously associated with the currently running JSVM environment by 405 * a call to OH_JSVM_SetInstanceData(). 406 * @return Returns JSVM funtions result code. 407 * {@link JSVM_OK } If the function executed successfully.\n 408 * @since 11 409 */ 410 JSVM_EXTERN JSVM_Status OH_JSVM_GetInstanceData(JSVM_Env env, 411 void** data); 412 413 /** 414 * @brief This API retrieves a JSVM_ExtendedErrorInfo structure with information about the last error that 415 * occurred. 416 * 417 * @param env The environment that the JSVM-API call is invoked under. 418 * @param result The JSVM_ExtendedErrorInfo structure with more information about the error. 419 * @return Returns JSVM funtions result code. 420 * {@link JSVM_OK } If the function executed successfully.\n 421 * @since 11 422 */ 423 JSVM_EXTERN JSVM_Status OH_JSVM_GetLastErrorInfo(JSVM_Env env, 424 const JSVM_ExtendedErrorInfo** result); 425 426 /** 427 * @brief This API throws the JavaScript value provided. 428 * 429 * @param env The environment that the API is invoked under. 430 * @param error The JavaScript value to be thrown. 431 * @return Returns JSVM funtions result code. 432 * {@link JSVM_OK } If the function executed successfully.\n 433 * @since 11 434 */ 435 JSVM_EXTERN JSVM_Status OH_JSVM_Throw(JSVM_Env env, 436 JSVM_Value error); 437 438 /** 439 * @brief This API throws a JavaScript Error with the text provided. 440 * 441 * @param env The environment that the API is invoked under. 442 * @param code Optional error code to be set on the error. 443 * @param msg C string representing the text to be associated with the error. 444 * @return Returns JSVM funtions result code. 445 * {@link JSVM_OK } If the function executed successfully.\n 446 * @since 11 447 */ 448 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowError(JSVM_Env env, 449 const char* code, 450 const char* msg); 451 452 /** 453 * @brief This API throws a JavaScript TypeError with the text provided. 454 * 455 * @param env The environment that the API is invoked under. 456 * @param code Optional error code to be set on the error. 457 * @param msg C string representing the text to be associated with the error. 458 * @return Returns JSVM funtions result code. 459 * {@link JSVM_OK } If the function executed successfully.\n 460 * @since 11 461 */ 462 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowTypeError(JSVM_Env env, 463 const char* code, 464 const char* msg); 465 466 /** 467 * @brief This API throws a JavaScript RangeError with the text provided. 468 * 469 * @param env The environment that the API is invoked under. 470 * @param code Optional error code to be set on the error. 471 * @param msg C string representing the text to be associated with the error. 472 * @return Returns JSVM funtions result code. 473 * {@link JSVM_OK } If the function executed successfully.\n 474 * @since 11 475 */ 476 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowRangeError(JSVM_Env env, 477 const char* code, 478 const char* msg); 479 480 /** 481 * @brief This API throws a JavaScript SyntaxError with the text provided. 482 * 483 * @param env The environment that the API is invoked under. 484 * @param code Optional error code to be set on the error. 485 * @param msg C string representing the text to be associated with the error. 486 * @return Returns JSVM funtions result code. 487 * {@link JSVM_OK } If the function executed successfully.\n 488 * @since 11 489 */ 490 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowSyntaxError(JSVM_Env env, 491 const char* code, 492 const char* msg); 493 494 /** 495 * @brief This API queries a JSVM_Value to check if it represents an error object. 496 * 497 * @param env The environment that the API is invoked under. 498 * @param value The JSVM_Value to be checked. 499 * @param result Boolean value that is set to true if JSVM_Value represents an error, 500 * false otherwise. 501 * @return Returns JSVM funtions result code. 502 * {@link JSVM_OK } If the function executed successfully.\n 503 * @since 11 504 */ 505 JSVM_EXTERN JSVM_Status OH_JSVM_IsError(JSVM_Env env, 506 JSVM_Value value, 507 bool* result); 508 509 /** 510 * @brief This API returns a JavaScript Error with the text provided. 511 * 512 * @param env The environment that the API is invoked under. 513 * @param code Optional JSVM_Value with the string for the error code to be associated with the error. 514 * @param msg JSVM_Value that references a JavaScript string to be used as the message for the Error. 515 * @param result JSVM_Value representing the error created. 516 * @return Returns JSVM funtions result code. 517 * {@link JSVM_OK } If the function executed successfully.\n 518 * @since 11 519 */ 520 JSVM_EXTERN JSVM_Status OH_JSVM_CreateError(JSVM_Env env, 521 JSVM_Value code, 522 JSVM_Value msg, 523 JSVM_Value* result); 524 525 /** 526 * @brief This API returns a JavaScript TypeError with the text provided. 527 * 528 * @param env The environment that the API is invoked under. 529 * @param code Optional JSVM_Value with the string for the error code to be associated with the error. 530 * @param msg JSVM_Value that references a JavaScript string to be used as the message for the Error. 531 * @param result JSVM_Value representing the error created. 532 * @return Returns JSVM funtions result code. 533 * {@link JSVM_OK } If the function executed successfully.\n 534 * @since 11 535 */ 536 JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypeError(JSVM_Env env, 537 JSVM_Value code, 538 JSVM_Value msg, 539 JSVM_Value* result); 540 541 /** 542 * @brief This API returns a JavaScript RangeError with the text provided. 543 * 544 * @param env The environment that the API is invoked under. 545 * @param code Optional JSVM_Value with the string for the error code to be associated with the error. 546 * @param msg JSVM_Value that references a JavaScript string to be used as the message for the Error. 547 * @param result JSVM_Value representing the error created. 548 * @return Returns JSVM funtions result code. 549 * {@link JSVM_OK } If the function executed successfully.\n 550 * @since 11 551 */ 552 JSVM_EXTERN JSVM_Status OH_JSVM_CreateRangeError(JSVM_Env env, 553 JSVM_Value code, 554 JSVM_Value msg, 555 JSVM_Value* result); 556 557 /** 558 * @brief This API returns a JavaScript SyntaxError with the text provided. 559 * 560 * @param env The environment that the API is invoked under. 561 * @param code Optional JSVM_Value with the string for the error code to be associated with the error. 562 * @param msg JSVM_Value that references a JavaScript string to be used as the message for the Error. 563 * @param result JSVM_Value representing the error created. 564 * @return Returns JSVM funtions result code. 565 * {@link JSVM_OK } If the function executed successfully.\n 566 * @since 11 567 */ 568 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSyntaxError(JSVM_Env env, 569 JSVM_Value code, 570 JSVM_Value msg, 571 JSVM_Value* result); 572 573 /** 574 * @brief This API returns a JavaScript exception if one is pending, NULL otherwise. 575 * 576 * @param env The environment that the API is invoked under. 577 * @param result The exception if one is pending, NULL otherwise. 578 * @return Returns JSVM funtions result code. 579 * {@link JSVM_OK } If the function executed successfully.\n 580 * @since 11 581 */ 582 JSVM_EXTERN JSVM_Status OH_JSVM_GetAndClearLastException(JSVM_Env env, 583 JSVM_Value* result); 584 585 /** 586 * @brief This API returns true if an exception is pending, false otherwise. 587 * 588 * @param env The environment that the API is invoked under. 589 * @param result Boolean value that is set to true if an exception is pending. 590 * @return Returns JSVM funtions result code. 591 * {@link JSVM_OK } If the function executed successfully.\n 592 * @since 11 593 */ 594 JSVM_EXTERN JSVM_Status OH_JSVM_IsExceptionPending(JSVM_Env env, 595 bool* result); 596 597 /** 598 * @brief This API opens a new scope. 599 * 600 * @param env The environment that the API is invoked under. 601 * @param result JSVM_Value representing the new scope. 602 * @return Returns JSVM funtions result code. 603 * {@link JSVM_OK } If the function executed successfully.\n 604 * @since 11 605 */ 606 JSVM_EXTERN JSVM_Status OH_JSVM_OpenHandleScope(JSVM_Env env, 607 JSVM_HandleScope* result); 608 609 /** 610 * @brief This API closes the scope passed in. Scopes must be closed in the reverse 611 * order from which they were created. 612 * 613 * @param env The environment that the API is invoked under. 614 * @param scope JSVM_Value representing the scope to be closed. 615 * @return Returns JSVM funtions result code. 616 * {@link JSVM_OK } If the function executed successfully.\n 617 * @since 11 618 */ 619 JSVM_EXTERN JSVM_Status OH_JSVM_CloseHandleScope(JSVM_Env env, 620 JSVM_HandleScope scope); 621 622 /** 623 * @brief This API opens a new scope from which one object can be promoted to the outer scope. 624 * 625 * @param env The environment that the API is invoked under. 626 * @param result JSVM_Value representing the new scope. 627 * @return Returns JSVM funtions result code. 628 * {@link JSVM_OK } If the function executed successfully.\n 629 * @since 11 630 */ 631 JSVM_EXTERN JSVM_Status OH_JSVM_OpenEscapableHandleScope(JSVM_Env env, 632 JSVM_EscapableHandleScope* result); 633 634 /** 635 * @brief This API closes the scope passed in. Scopes must be closed in the reverse order 636 * from which they were created. 637 * 638 * @param env The environment that the API is invoked under. 639 * @param scope JSVM_Value representing the scope to be closed. 640 * @return Returns JSVM funtions result code. 641 * {@link JSVM_OK } If the function executed successfully.\n 642 * @since 11 643 */ 644 JSVM_EXTERN JSVM_Status OH_JSVM_CloseEscapableHandleScope(JSVM_Env env, 645 JSVM_EscapableHandleScope scope); 646 647 /** 648 * @brief This API promotes the handle to the JavaScript object so that it is valid for the lifetime 649 * of the outer scope. It can only be called once per scope. If it is called more than once an error 650 * will be returned. 651 * 652 * @param env The environment that the API is invoked under. 653 * @param scope JSVM_Value representing the current scope. 654 * @param escapee JSVM_Value representing the JavaScript Object to be escaped. 655 * @param result JSVM_Value representing the handle to the escaped Object in the outer scope. 656 * @return Returns JSVM funtions result code. 657 * {@link JSVM_OK } If the function executed successfully.\n 658 * @since 11 659 */ 660 JSVM_EXTERN JSVM_Status OH_JSVM_EscapeHandle(JSVM_Env env, 661 JSVM_EscapableHandleScope scope, 662 JSVM_Value escapee, 663 JSVM_Value* result); 664 665 /** 666 * @brief This API creates a new reference with the specified reference count to the value passed in. 667 * 668 * @param env The environment that the API is invoked under. 669 * @param value The JSVM_Value for which a reference is being created. 670 * @param initialRefcount Initial reference count for the new reference. 671 * @param result JSVM_Ref pointing to the new reference. 672 * @return Returns JSVM funtions result code. 673 * {@link JSVM_OK } If the function executed successfully.\n 674 * @since 11 675 */ 676 JSVM_EXTERN JSVM_Status OH_JSVM_CreateReference(JSVM_Env env, 677 JSVM_Value value, 678 uint32_t initialRefcount, 679 JSVM_Ref* result); 680 681 /** 682 * @brief his API deletes the reference passed in. 683 * 684 * @param env The environment that the API is invoked under. 685 * @param ref JSVM_Ref to be deleted. 686 * @return Returns JSVM funtions result code. 687 * {@link JSVM_OK } If the function executed successfully.\n 688 * @since 11 689 */ 690 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteReference(JSVM_Env env, 691 JSVM_Ref ref); 692 693 /** 694 * @brief his API increments the reference count for the reference passed in and 695 * returns the resulting reference count. 696 * 697 * @param env The environment that the API is invoked under. 698 * @param ref JSVM_Ref for which the reference count will be incremented. 699 * @param result The new reference count. 700 * @return Returns JSVM funtions result code. 701 * {@link JSVM_OK } If the function executed successfully.\n 702 * @since 11 703 */ 704 JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceRef(JSVM_Env env, 705 JSVM_Ref ref, 706 uint32_t* result); 707 708 /** 709 * @brief This API decrements the reference count for the reference passed in and 710 * returns the resulting reference count. 711 * 712 * @param env The environment that the API is invoked under. 713 * @param ref JSVM_Ref for which the reference count will be decremented. 714 * @param result The new reference count. 715 * @return Returns JSVM funtions result code. 716 * {@link JSVM_OK } If the function executed successfully.\n 717 * @since 11 718 */ 719 JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceUnref(JSVM_Env env, 720 JSVM_Ref ref, 721 uint32_t* result); 722 723 /** 724 * @brief If still valid, this API returns the JSVM_Value representing the 725 * JavaScript value associated with the JSVM_Ref. Otherwise, result will be NULL. 726 * 727 * @param env The environment that the API is invoked under. 728 * @param ref The JSVM_Ref for which the corresponding value is being requested. 729 * @param result The JSVM_Value referenced by the JSVM_Ref. 730 * @return Returns JSVM funtions result code. 731 * {@link JSVM_OK } If the function executed successfully.\n 732 * @since 11 733 */ 734 JSVM_EXTERN JSVM_Status OH_JSVM_GetReferenceValue(JSVM_Env env, 735 JSVM_Ref ref, 736 JSVM_Value* result); 737 738 /** 739 * @brief This API returns a JSVM-API value corresponding to a JavaScript Array type. 740 * 741 * @param env The environment that the API is invoked under. 742 * @param result A JSVM_Value representing a JavaScript Array. 743 * @return Returns JSVM funtions result code. 744 * {@link JSVM_OK } If the function executed successfully.\n 745 * @since 11 746 */ 747 JSVM_EXTERN JSVM_Status OH_JSVM_CreateArray(JSVM_Env env, 748 JSVM_Value* result); 749 750 751 /** 752 * @brief This API returns a JSVM-API value corresponding to a JavaScript Array type. The Array's length property 753 * is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated 754 * by the VM when the array is created. That behavior is left to the underlying VM implementation. 755 * 756 * @param env The environment that the API is invoked under. 757 * @param length The initial length of the Array. 758 * @param result A JSVM_Value representing a JavaScript Array. 759 * @return Returns JSVM funtions result code. 760 * {@link JSVM_OK } If the function executed successfully.\n 761 * @since 11 762 */ 763 JSVM_EXTERN JSVM_Status OH_JSVM_CreateArrayWithLength(JSVM_Env env, 764 size_t length, 765 JSVM_Value* result); 766 767 /** 768 * @brief This API returns a JSVM-API value corresponding to a JavaScript ArrayBuffer. ArrayBuffers are used to 769 * represent fixed-length binary data buffers. They are normally used as a backing-buffer for TypedArray objects. 770 * The ArrayBuffer allocated will have an underlying byte buffer whose size is determined by the length parameter 771 * that's passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to 772 * directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this 773 * buffer from JavaScript, a typed array or DataView object would need to be created. 774 * 775 * @param env The environment that the API is invoked under. 776 * @param byteLength The length in bytes of the array buffer to create. 777 * @param data Pointer to the underlying byte buffer of the ArrayBuffer.data can optionally be ignored by passing NULL. 778 * @param result A JSVM_Value representing a JavaScript Array. 779 * @return Returns JSVM funtions result code. 780 * {@link JSVM_OK } If the function executed successfully.\n 781 * @since 11 782 */ 783 JSVM_EXTERN JSVM_Status OH_JSVM_CreateArraybuffer(JSVM_Env env, 784 size_t byteLength, 785 void** data, 786 JSVM_Value* result); 787 788 /** 789 * @brief This API allocate the memory of array buffer backing store. 790 * 791 * @param byteLength size of backing store memory. 792 * @param initialized initialization status of the backing store memory. 793 * @param data pointer that recieve the backing store memory pointer. 794 * @return Returns JSVM funtions result code. 795 * Returns {@link JSVM_OK } if allocation succeed.\n 796 * Returns {@link JSVM_INVALID_ARG } if data is null pointer.\n 797 * Returns {@link JSVM_GENERIC_FAILURE } if allocation failed.\n 798 * @since 12 799 */ 800 JSVM_Status JSVM_CDECL OH_JSVM_AllocateArrayBufferBackingStoreData(size_t byteLength, 801 JSVM_InitializedFlag initialized, 802 void **data); 803 804 /** 805 * @brief This API release the memory of an array buffer backing store. 806 * 807 * @param data pointer to the backing store memory. 808 * @return Returns JSVM funtions result code. 809 * Returns {@link JSVM_OK } if run succeed.\n 810 * Returns {@link JSVM_INVALID_ARG } if data is null pointer.\n 811 * @since 12 812 */ 813 JSVM_Status JSVM_CDECL OH_JSVM_FreeArrayBufferBackingStoreData(void *data); 814 815 /** 816 * @brief This API create an array buffer using the backing store data. 817 * 818 * @param env The environment that the API is invoked under. 819 * @param data pointer to the backing store memory. 820 * @param backingStoreSize size of backing store memory. 821 * @param offset start position of the array buffer in the backing store memory. 822 * @param arrayBufferSize size of the array buffer. 823 * @param result pointer that recieve the array buffer. 824 * @return Returns JSVM funtions result code. 825 * Returns {@link JSVM_OK } if creation succeed.\n 826 * Returns {@link JSVM_INVALID_ARG } if any of the following condition reached:\n 827 * 1. offset + arrayBufferSize > backingStoreSize\n 828 * 2. backingStoreSize or arrayBufferSize equals zero 829 * 3. data or result is null pointer 830 * @since 12 831 */ 832 JSVM_Status JSVM_CDECL OH_JSVM_CreateArrayBufferFromBackingStoreData(JSVM_Env env, 833 void *data, 834 size_t backingStoreSize, 835 size_t offset, 836 size_t arrayBufferSize, 837 JSVM_Value *result); 838 839 /** 840 * @brief This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification. 841 * This API allocates a JavaScript Date object. 842 * 843 * @param env The environment that the API is invoked under. 844 * @param time ECMAScript time value in milliseconds since 01 January, 1970 UTC. 845 * @param result A JSVM_Value representing a JavaScript Date. 846 * @return Returns JSVM funtions result code. 847 * {@link JSVM_OK } If the function executed successfully.\n 848 * @since 11 849 */ 850 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDate(JSVM_Env env, 851 double time, 852 JSVM_Value* result); 853 854 /** 855 * @brief This API allocates a JavaScript value with external data attached to it. This is used to pass external 856 * data through JavaScript code, so it can be retrieved later by native code using OH_JSVM_GetValueExternal. 857 * The API adds a JSVM_Finalize callback which will be called when the JavaScript object just created has been garbage 858 * collected.The created value is not an object, and therefore does not support additional properties. It is considered 859 * a distinct value type calling OH_JSVM_Typeof() with an external value yields JSVM_EXTERNAL. 860 * 861 * @param env The environment that the API is invoked under. 862 * @param data Raw pointer to the external data. 863 * @param finalizeCb Optional callback to call when the external value is being collected. JSVM_Finalize provides 864 * more details. 865 * @param finalizeHint Optional hint to pass to the finalize callback during collection. 866 * @param result A JSVM_Value representing an external value. 867 * @return Returns JSVM funtions result code. 868 * {@link JSVM_OK } If the function executed successfully.\n 869 * @since 11 870 */ 871 JSVM_EXTERN JSVM_Status OH_JSVM_CreateExternal(JSVM_Env env, 872 void* data, 873 JSVM_Finalize finalizeCb, 874 void* finalizeHint, 875 JSVM_Value* result); 876 877 /** 878 * @brief This API allocates a default JavaScript Object. It is the equivalent of doing new Object() in JavaScript. 879 * 880 * @param env The environment that the API is invoked under. 881 * @param result A JSVM_Value representing a JavaScript Object. 882 * @return Returns JSVM funtions result code. 883 * {@link JSVM_OK } If the function executed successfully.\n 884 * @since 11 885 */ 886 JSVM_EXTERN JSVM_Status OH_JSVM_CreateObject(JSVM_Env env, 887 JSVM_Value* result); 888 889 /** 890 * @brief This API creates a JavaScript symbol value from a UTF8-encoded C string. 891 * 892 * @param env The environment that the API is invoked under. 893 * @param description Optional JSVM_Value which refers to a JavaScript string to be set as the description 894 * for the symbol. 895 * @param result A JSVM_Value representing a JavaScript symbol. 896 * @return Returns JSVM funtions result code. 897 * {@link JSVM_OK } If the function executed successfully.\n 898 * @since 11 899 */ 900 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSymbol(JSVM_Env env, 901 JSVM_Value description, 902 JSVM_Value* result); 903 904 /** 905 * @brief This API searches in the global registry for an existing symbol with the given description. 906 * If the symbol already exists it will be returned, otherwise a new symbol will be created in the registry. 907 * 908 * @param env The environment that the API is invoked under. 909 * @param utf8description UTF-8 C string representing the text to be used as the description for the symbol. 910 * @param length The length of the description string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 911 * @param result A JSVM_Value representing a JavaScript symbol. 912 * @return Returns JSVM funtions result code. 913 * {@link JSVM_OK } If the function executed successfully.\n 914 * @since 11 915 */ 916 JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env, 917 const char* utf8description, 918 size_t length, 919 JSVM_Value* result); 920 921 /** 922 * @brief This API creates a JavaScript TypedArray object over an existing ArrayBuffer. TypedArray 923 * objects provide an array-like view over an underlying data buffer where each element has the 924 * same underlying binary scalar datatype.It's required that (length * size_of_element) + byte_offset should 925 * be <= the size in bytes of the array passed in. If not, a RangeError exception is raised. 926 * 927 * @param env The environment that the API is invoked under. 928 * @param type Scalar datatype of the elements within the TypedArray. 929 * @param length Number of elements in the TypedArray. 930 * @param arraybuffer ArrayBuffer underlying the typed array. 931 * @param byteOffset The byte offset within the ArrayBuffer from which to start projecting the TypedArray. 932 * @param result A JSVM_Value representing a JavaScript TypedArray 933 * @return Returns JSVM funtions result code. 934 * {@link JSVM_OK } If the function executed successfully.\n 935 * @since 11 936 */ 937 JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, 938 JSVM_TypedarrayType type, 939 size_t length, 940 JSVM_Value arraybuffer, 941 size_t byteOffset, 942 JSVM_Value* result); 943 944 /** 945 * @brief This API creates a JavaScript DataView object over an existing ArrayBuffer. DataView 946 * objects provide an array-like view over an underlying data buffer, but one which allows items 947 * of different size and type in the ArrayBuffer.It is required that byte_length + byte_offset is 948 * less than or equal to the size in bytes of the array passed in. If not, a RangeError exception 949 * is raised. 950 * 951 * @param env The environment that the API is invoked under. 952 * @param length Number of elements in the DataView. 953 * @param arraybuffer ArrayBuffer underlying the DataView. 954 * @param byteOffset The byte offset within the ArrayBuffer from which to start projecting the DataView. 955 * @param result A JSVM_Value representing a JavaScript DataView. 956 * @return Returns JSVM funtions result code. 957 * {@link JSVM_OK } If the function executed successfully.\n 958 * @since 11 959 */ 960 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env, 961 size_t length, 962 JSVM_Value arraybuffer, 963 size_t byteOffset, 964 JSVM_Value* result); 965 966 /** 967 * @brief This API is used to convert from the C int32_t type to the JavaScript number type. 968 * 969 * @param env The environment that the API is invoked under. 970 * @param value Integer value to be represented in JavaScript. 971 * @param result A JSVM_Value representing a JavaScript number. 972 * @return Returns JSVM funtions result code. 973 * {@link JSVM_OK } If the function executed successfully.\n 974 * @since 11 975 */ 976 JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt32(JSVM_Env env, 977 int32_t value, 978 JSVM_Value* result); 979 980 /** 981 * @brief This API is used to convert from the C uint32_t type to the JavaScript number type. 982 * 983 * @param env The environment that the API is invoked under. 984 * @param value Unsigned integer value to be represented in JavaScript. 985 * @param result A JSVM_Value representing a JavaScript number. 986 * @return Returns JSVM funtions result code. 987 * {@link JSVM_OK } If the function executed successfully.\n 988 * @since 11 989 */ 990 JSVM_EXTERN JSVM_Status OH_JSVM_CreateUint32(JSVM_Env env, 991 uint32_t value, 992 JSVM_Value* result); 993 994 /** 995 * @brief This API is used to convert from the C int64_t type to the JavaScript number type. 996 * 997 * @param env The environment that the API is invoked under. 998 * @param value Integer value to be represented in JavaScript. 999 * @param result A JSVM_Value representing a JavaScript number. 1000 * @return Returns JSVM funtions result code. 1001 * {@link JSVM_OK } If the function executed successfully.\n 1002 * @since 11 1003 */ 1004 JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt64(JSVM_Env env, 1005 int64_t value, 1006 JSVM_Value* result); 1007 1008 /** 1009 * @brief This API is used to convert from the C double type to the JavaScript number type. 1010 * 1011 * @param env The environment that the API is invoked under. 1012 * @param value Double-precision value to be represented in JavaScript. 1013 * @param result A JSVM_Value representing a JavaScript number. 1014 * @return Returns JSVM funtions result code. 1015 * {@link JSVM_OK } If the function executed successfully.\n 1016 * @since 11 1017 */ 1018 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDouble(JSVM_Env env, 1019 double value, 1020 JSVM_Value* result); 1021 1022 /** 1023 * @brief This API converts the C int64_t type to the JavaScript BigInt type. 1024 * 1025 * @param env The environment that the API is invoked under. 1026 * @param value Integer value to be represented in JavaScript. 1027 * @param result A JSVM_Value representing a JavaScript BigInt. 1028 * @return Returns JSVM funtions result code. 1029 * {@link JSVM_OK } If the function executed successfully.\n 1030 * @since 11 1031 */ 1032 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintInt64(JSVM_Env env, 1033 int64_t value, 1034 JSVM_Value* result); 1035 1036 /** 1037 * @brief This API converts the C uint64_t type to the JavaScript BigInt type. 1038 * 1039 * @param env The environment that the API is invoked under. 1040 * @param value Unsigned integer value to be represented in JavaScript. 1041 * @param result A JSVM_Value representing a JavaScript BigInt. 1042 * @return Returns JSVM funtions result code. 1043 * {@link JSVM_OK } If the function executed successfully.\n 1044 * @since 11 1045 */ 1046 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintUint64(JSVM_Env env, 1047 uint64_t value, 1048 JSVM_Value* result); 1049 1050 /** 1051 * @brief This API converts an array of unsigned 64-bit words into a single BigInt value. 1052 * The resulting BigInt is calculated as (–1)sign_bit (words[0] × (264)0 + words[1] × (264)1 + …) 1053 * 1054 * @param env The environment that the API is invoked under. 1055 * @param signBit Determines if the resulting BigInt will be positive or negative. 1056 * @param wordCount The length of the words array. 1057 * @param words An array of uint64_t little-endian 64-bit words. 1058 * @param result A JSVM_Value representing a JavaScript BigInt. 1059 * @return Returns JSVM funtions result code. 1060 * {@link JSVM_OK } If the function executed successfully.\n 1061 * @since 11 1062 */ 1063 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env, 1064 int signBit, 1065 size_t wordCount, 1066 const uint64_t* words, 1067 JSVM_Value* result); 1068 1069 /** 1070 * @brief This API creates a JavaScript string value from an ISO-8859-1-encoded C 1071 * string. The native string is copied. 1072 * 1073 * @param env The environment that the API is invoked under. 1074 * @param str Character buffer representing an ISO-8859-1-encoded string. 1075 * @param length The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 1076 * @param result A JSVM_Value representing a JavaScript string. 1077 * @return Returns JSVM funtions result code. 1078 * {@link JSVM_OK } If the function executed successfully.\n 1079 * @since 11 1080 */ 1081 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, 1082 const char* str, 1083 size_t length, 1084 JSVM_Value* result); 1085 1086 /** 1087 * @brief This API creates a JavaScript string value from a UTF16-LE-encoded C 1088 * string. The native string is copied. 1089 * 1090 * @param env The environment that the API is invoked under. 1091 * @param str Character buffer representing a UTF16-LE-encoded string. 1092 * @param length The length of the string in two-byte code units, or JSVM_AUTO_LENGTH 1093 * if it is null-terminated. 1094 * @param result A JSVM_Value representing a JavaScript string. 1095 * @return Returns JSVM funtions result code. 1096 * {@link JSVM_OK } If the function executed successfully.\n 1097 * @since 11 1098 */ 1099 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, 1100 const char16_t* str, 1101 size_t length, 1102 JSVM_Value* result); 1103 1104 /** 1105 * @brief This API creates a JavaScript string value from a UTF8-encoded C 1106 * string. The native string is copied. 1107 * 1108 * @param env The environment that the API is invoked under. 1109 * @param str Character buffer representing a UTF8-encoded string. 1110 * @param length The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 1111 * @param result A JSVM_Value representing a JavaScript string. 1112 * @return Returns JSVM funtions result code. 1113 * {@link JSVM_OK } If the function executed successfully.\n 1114 * @since 11 1115 */ 1116 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf8(JSVM_Env env, 1117 const char* str, 1118 size_t length, 1119 JSVM_Value* result); 1120 1121 /** 1122 * @brief This API returns the length of an array. 1123 * 1124 * @param env The environment that the API is invoked under. 1125 * @param value JSVM_Value representing the JavaScript Array whose length is being queried. 1126 * @param result uint32 representing length of the array. 1127 * @return Returns JSVM funtions result code. 1128 * {@link JSVM_OK } If the function executed successfully.\n 1129 * @since 11 1130 */ 1131 JSVM_EXTERN JSVM_Status OH_JSVM_GetArrayLength(JSVM_Env env, 1132 JSVM_Value value, 1133 uint32_t* result); 1134 1135 /** 1136 * @brief This API is used to retrieve the underlying data buffer of an ArrayBuffer and its length. 1137 * 1138 * @param env The environment that the API is invoked under. 1139 * @param arraybuffer JSVM_Value representing the ArrayBuffer being queried. 1140 * @param data The underlying data buffer of the ArrayBuffer. If byte_length is 0, this may be NULL 1141 * or any other pointer value. 1142 * @param byteLength Length in bytes of the underlying data buffer. 1143 * @return Returns JSVM funtions result code. 1144 * {@link JSVM_OK } If the function executed successfully.\n 1145 * @since 11 1146 */ 1147 JSVM_EXTERN JSVM_Status OH_JSVM_GetArraybufferInfo(JSVM_Env env, 1148 JSVM_Value arraybuffer, 1149 void** data, 1150 size_t* byteLength); 1151 1152 /** 1153 * @brief This API returns the length of an array. 1154 * 1155 * @param env The environment that the API is invoked under. 1156 * @param object JSVM_Value representing JavaScript Object whose prototype to return. This returns 1157 * the equivalent of Object.getPrototypeOf (which is not the same as the function's prototype property). 1158 * @param result JSVM_Value representing prototype of the given object. 1159 * @return Returns JSVM funtions result code. 1160 * {@link JSVM_OK } If the function executed successfully.\n 1161 * @since 11 1162 */ 1163 JSVM_EXTERN JSVM_Status OH_JSVM_GetPrototype(JSVM_Env env, 1164 JSVM_Value object, 1165 JSVM_Value* result); 1166 1167 /** 1168 * @brief This API returns various properties of a typed array. 1169 * 1170 * @param env The environment that the API is invoked under. 1171 * @param typedarray JSVM_Value representing the TypedArray whose properties to query. 1172 * @param type Scalar datatype of the elements within the TypedArray. 1173 * @param length The number of elements in the TypedArray. 1174 * @param data The data buffer underlying the TypedArray adjusted by the byte_offset value so that it 1175 * points to the first element in the TypedArray. If the length of the array is 0, this may be NULL or 1176 * any other pointer value. 1177 * @param arraybuffer The ArrayBuffer underlying the TypedArray. 1178 * @param byteOffset The byte offset within the underlying native array at which the first element of 1179 * the arrays is located. The value for the data parameter has already been adjusted so that data points 1180 * to the first element in the array. Therefore, the first byte of the native array would be at data - byte_offset. 1181 * @return Returns JSVM funtions result code. 1182 * {@link JSVM_OK } If the function executed successfully.\n 1183 * @since 11 1184 */ 1185 JSVM_EXTERN JSVM_Status OH_JSVM_GetTypedarrayInfo(JSVM_Env env, 1186 JSVM_Value typedarray, 1187 JSVM_TypedarrayType* type, 1188 size_t* length, 1189 void** data, 1190 JSVM_Value* arraybuffer, 1191 size_t* byteOffset); 1192 1193 /** 1194 * @brief Any of the out parameters may be NULL if that property is unneeded. 1195 * This API returns various properties of a DataView. 1196 * 1197 * @param env The environment that the API is invoked under. 1198 * @param dataview JSVM_Value representing the DataView whose properties to query. 1199 * @param bytelength Number of bytes in the DataView. 1200 * @param data The data buffer underlying the DataView. 1201 * If byte_length is 0, this may be NULL or any other pointer value. 1202 * @param arraybuffer ArrayBuffer underlying the DataView. 1203 * @param byteOffset The byte offset within the data buffer from which to start projecting the DataView. 1204 * @return Returns JSVM funtions result code. 1205 * {@link JSVM_OK } If the function executed successfully.\n 1206 * @since 11 1207 */ 1208 JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, 1209 JSVM_Value dataview, 1210 size_t* bytelength, 1211 void** data, 1212 JSVM_Value* arraybuffer, 1213 size_t* byteOffset); 1214 1215 /** 1216 * @brief Returns JSVM_OK if the function executed successfully. If a non-date JSVM_Value is 1217 * passed in it returns JSVM_date_expected.This API returns the C double 1218 * primitive of time value for the given JavaScript Date. 1219 * 1220 * @param env The environment that the API is invoked under. 1221 * @param value JSVM_Value representing a JavaScript Date. 1222 * @param result Time value as a double represented as milliseconds 1223 * since midnight at the beginning of 01 January, 1970 UTC. 1224 * @return Returns JSVM funtions result code. 1225 * {@link JSVM_OK } If the function executed successfully.\n 1226 * {@link JSVM_DATE_EXPECTED } If a non-date JSVM_Value is passed in it.\n 1227 * @since 11 1228 */ 1229 JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env, 1230 JSVM_Value value, 1231 double* result); 1232 1233 /** 1234 * @brief This API returns the C boolean primitive equivalent of the given JavaScript Boolean. 1235 * 1236 * @param env The environment that the API is invoked under. 1237 * @param value JSVM_Value representing JavaScript Boolean. 1238 * @param result C boolean primitive equivalent of the given JavaScript Boolean. 1239 * @return Returns JSVM funtions result code. 1240 * {@link JSVM_OK } If the function executed successfully.\n 1241 * {@link JSVM_BOOLEAN_EXPECTED }If a non-boolean JSVM_Value is passed in it.\n 1242 * @since 11 1243 */ 1244 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBool(JSVM_Env env, 1245 JSVM_Value value, 1246 bool* result); 1247 1248 /** 1249 * @brief This API returns the C double primitive equivalent of the given JavaScript number. 1250 * 1251 * @param env The environment that the API is invoked under. 1252 * @param value JSVM_Value representing JavaScript number. 1253 * @param result C double primitive equivalent of the given JavaScript number. 1254 * @return Returns JSVM funtions result code. 1255 * {@link JSVM_OK } If the function executed successfully.\n 1256 * {@link JSVM_NUMBER_EXPECTED } If a non-number JSVM_Value is passed in.\n 1257 * @since 11 1258 */ 1259 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueDouble(JSVM_Env env, 1260 JSVM_Value value, 1261 double* result); 1262 1263 /** 1264 * @brief This API returns the C int64_t primitive equivalent of the given JavaScript BigInt. 1265 * If needed it will truncate the value, setting lossless to false. 1266 * 1267 * @param env The environment that the API is invoked under. 1268 * @param value JSVM_Value representing JavaScript BigInt. 1269 * @param result C int64_t primitive equivalent of the given JavaScript BigInt. 1270 * @param lossless Indicates whether the BigInt value was converted losslessly. 1271 * @return Returns JSVM funtions result code. 1272 * {@link JSVM_OK } If the function executed successfully.\n 1273 * {@link JSVM_BIGINT_EXPECTED } If a non-BigInt is passed in it.\n 1274 * @since 11 1275 */ 1276 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintInt64(JSVM_Env env, 1277 JSVM_Value value, 1278 int64_t* result, 1279 bool* lossless); 1280 1281 /** 1282 * @brief This API returns the C uint64_t primitive equivalent of the given JavaScript BigInt. 1283 * If needed it will truncate the value, setting lossless to false. 1284 * 1285 * @param env The environment that the API is invoked under. 1286 * @param value JSVM_Value representing JavaScript BigInt. 1287 * @param result C uint64_t primitive equivalent of the given JavaScript BigInt. 1288 * @param lossless Indicates whether the BigInt value was converted losslessly. 1289 * @return Returns JSVM funtions result code. 1290 * {@link JSVM_OK } If the function executed successfully.\n 1291 * {@link JSVM_BIGINT_EXPECTED } If a non-BigInt is passed in it.\n 1292 * @since 11 1293 */ 1294 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintUint64(JSVM_Env env, 1295 JSVM_Value value, 1296 uint64_t* result, 1297 bool* lossless); 1298 1299 /** 1300 * @brief This API converts a single BigInt value into a sign bit, 64-bit little-endian array, and the number 1301 * of elements in the array. signBit and words may be both set to NULL, in order to get only wordCount. 1302 * 1303 * @param env The environment that the API is invoked under. 1304 * @param value JSVM_Value representing JavaScript BigInt. 1305 * @param signBit Integer representing if the JavaScript BigInt is positive or negative. 1306 * @param wordCount Must be initialized to the length of the words array. Upon return, it will be set to 1307 * the actual number of words that would be needed to store this BigInt. 1308 * @param words Pointer to a pre-allocated 64-bit word array. 1309 * @return Returns JSVM funtions result code. 1310 * {@link JSVM_OK } If the function executed successfully.\n 1311 * @since 11 1312 */ 1313 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintWords(JSVM_Env env, 1314 JSVM_Value value, 1315 int* signBit, 1316 size_t* wordCount, 1317 uint64_t* words); 1318 1319 /** 1320 * @brief This API retrieves the external data pointer that was previously passed to OH_JSVM_CreateExternal(). 1321 * 1322 * @param env The environment that the API is invoked under. 1323 * @param value JSVM_Value representing JavaScript external value. 1324 * @param result Pointer to the data wrapped by the JavaScript external value. 1325 * @return Returns JSVM funtions result code. 1326 * {@link JSVM_OK } If the function executed successfully.\n 1327 * {@link JSVM_INVALID_ARG } If a non-external JSVM_Value is passed in it.\n 1328 * @since 11 1329 */ 1330 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueExternal(JSVM_Env env, 1331 JSVM_Value value, 1332 void** result); 1333 1334 /** 1335 * @brief This API returns the C int32 primitive equivalent of the given JavaScript number. 1336 * 1337 * @param env The environment that the API is invoked under. 1338 * @param value JSVM_Value representing JavaScript number. 1339 * @param result C int32 primitive equivalent of the given JavaScript number. 1340 * @return Returns JSVM funtions result code. 1341 * {@link JSVM_OK } If the function executed successfully.\n 1342 * {@link JSVM_NUMBER_EXPECTED } If a non-number JSVM_Value is passed in.\n 1343 * @since 11 1344 */ 1345 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt32(JSVM_Env env, 1346 JSVM_Value value, 1347 int32_t* result); 1348 1349 /** 1350 * @brief This API returns the C int64 primitive equivalent of the given JavaScript number. 1351 * 1352 * @param env The environment that the API is invoked under. 1353 * @param value JSVM_Value representing JavaScript number. 1354 * @param result C int64 primitive equivalent of the given JavaScript number. 1355 * @return Returns JSVM funtions result code. 1356 * {@link JSVM_OK } If the function executed successfully.\n 1357 * {@link JSVM_NUMBER_EXPECTED } If a non-number JSVM_Value is passed in.\n 1358 * @since 11 1359 */ 1360 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt64(JSVM_Env env, 1361 JSVM_Value value, 1362 int64_t* result); 1363 1364 /** 1365 * @brief This API returns the ISO-8859-1-encoded string corresponding the value passed in. 1366 * 1367 * @param env The environment that the API is invoked under. 1368 * @param value JSVM_Value representing JavaScript string. 1369 * @param buf Buffer to write the ISO-8859-1-encoded string into. If NULL is passed in, the 1370 * length of the string in bytes and excluding the null terminator is returned in result. 1371 * @param bufsize Size of the destination buffer. When this value is insufficient, the returned string 1372 * is truncated and null-terminated. 1373 * @param result Number of bytes copied into the buffer, excluding the null terminator. 1374 * @return Returns JSVM funtions result code. 1375 * {@link JSVM_OK } If the function executed successfully.\n 1376 * {@link JSVM_STRING_EXPECTED } If a non-string JSVM_Value is passed in.\n 1377 * @since 11 1378 */ 1379 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringLatin1(JSVM_Env env, 1380 JSVM_Value value, 1381 char* buf, 1382 size_t bufsize, 1383 size_t* result); 1384 1385 /** 1386 * @brief This API returns the UTF8-encoded string corresponding the value passed in. 1387 * 1388 * @param env The environment that the API is invoked under. 1389 * @param value JSVM_Value representing JavaScript string. 1390 * @param buf Buffer to write the UTF8-encoded string into. If NULL is passed in, the length 1391 * of the string in bytes and excluding the null terminator is returned in result. 1392 * @param bufsize Size of the destination buffer. When this value is insufficient, the returned 1393 * string is truncated and null-terminated. 1394 * @param result Number of bytes copied into the buffer, excluding the null terminator. 1395 * @return Returns JSVM funtions result code. 1396 * {@link JSVM_OK } If the function executed successfully.\n 1397 * {@link JSVM_STRING_EXPECTED } If a non-string JSVM_Value is passed in.\n 1398 * @since 11 1399 */ 1400 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf8(JSVM_Env env, 1401 JSVM_Value value, 1402 char* buf, 1403 size_t bufsize, 1404 size_t* result); 1405 1406 /** 1407 * @brief This API returns the UTF16-encoded string corresponding the value passed in. 1408 * 1409 * @param env The environment that the API is invoked under. 1410 * @param value JSVM_Value representing JavaScript string. 1411 * @param buf Buffer to write the UTF16-LE-encoded string into. If NULL is passed in, 1412 * the length of the string in 2-byte code units and excluding the null terminator is returned. 1413 * @param bufsize Size of the destination buffer. When this value is insufficient, 1414 * the returned string is truncated and null-terminated. 1415 * @param result Number of 2-byte code units copied into the buffer, excluding the null terminator. 1416 * @return Returns JSVM funtions result code. 1417 * {@link JSVM_OK } If the function executed successfully.\n 1418 * {@link JSVM_STRING_EXPECTED } If a non-string JSVM_Value is passed in.\n 1419 * @since 11 1420 */ 1421 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf16(JSVM_Env env, 1422 JSVM_Value value, 1423 char16_t* buf, 1424 size_t bufsize, 1425 size_t* result); 1426 1427 /** 1428 * @brief This API returns the C primitive equivalent of the given JSVM_Value as a uint32_t. 1429 * 1430 * @param env The environment that the API is invoked under. 1431 * @param value JSVM_Value representing JavaScript number. 1432 * @param result C primitive equivalent of the given JSVM_Value as a uint32_t. 1433 * @return Returns JSVM funtions result code. 1434 * {@link JSVM_OK } If the function executed successfully.\n 1435 * {@link JSVM_NUMBER_EXPECTED } If a non-number JSVM_Value is passed in it.\n 1436 * @since 11 1437 */ 1438 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueUint32(JSVM_Env env, 1439 JSVM_Value value, 1440 uint32_t* result); 1441 1442 /** 1443 * @brief This API is used to return the JavaScript singleton object that is used to represent the given boolean value. 1444 * 1445 * @param env The environment that the API is invoked under. 1446 * @param value The value of the boolean to retrieve. 1447 * @param result JSVM_Value representing JavaScript Boolean singleton to retrieve. 1448 * @return Returns JSVM funtions result code. 1449 * {@link JSVM_OK } If the function executed successfully.\n 1450 * @since 11 1451 */ 1452 JSVM_EXTERN JSVM_Status OH_JSVM_GetBoolean(JSVM_Env env, 1453 bool value, 1454 JSVM_Value* result); 1455 1456 /** 1457 * @brief This API returns the global object. 1458 * 1459 * @param env The environment that the API is invoked under. 1460 * @param result JSVM_Value representing JavaScript global object. 1461 * @return Returns JSVM funtions result code. 1462 * {@link JSVM_OK } If the function executed successfully.\n 1463 * @since 11 1464 */ 1465 JSVM_EXTERN JSVM_Status OH_JSVM_GetGlobal(JSVM_Env env, 1466 JSVM_Value* result); 1467 1468 /** 1469 * @brief This API returns the null object. 1470 * 1471 * @param env The environment that the API is invoked under. 1472 * @param result JSVM_Value representing JavaScript null object. 1473 * @return Returns JSVM funtions result code. 1474 * {@link JSVM_OK } If the function executed successfully.\n 1475 * @since 11 1476 */ 1477 JSVM_EXTERN JSVM_Status OH_JSVM_GetNull(JSVM_Env env, 1478 JSVM_Value* result); 1479 1480 /** 1481 * @brief This API returns the Undefined object. 1482 * 1483 * @param env The environment that the API is invoked under. 1484 * @param result JSVM_Value representing JavaScript Undefined value. 1485 * @return Returns JSVM funtions result code. 1486 * {@link JSVM_OK } If the function executed successfully.\n 1487 * @since 11 1488 */ 1489 JSVM_EXTERN JSVM_Status OH_JSVM_GetUndefined(JSVM_Env env, 1490 JSVM_Value* result); 1491 1492 /** 1493 * @brief This API implements the abstract operation ToBoolean() 1494 * 1495 * @param env The environment that the API is invoked under. 1496 * @param value The JavaScript value to coerce. 1497 * @param result JSVM_Value representing the coerced JavaScript Boolean. 1498 * @return Returns JSVM funtions result code. 1499 * {@link JSVM_OK } If the function executed successfully.\n 1500 * @since 11 1501 */ 1502 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBool(JSVM_Env env, 1503 JSVM_Value value, 1504 JSVM_Value* result); 1505 1506 /** 1507 * @brief This API implements the abstract operation ToNumber() as defined. This 1508 * function potentially runs JS code if the passed-in value is an object. 1509 * 1510 * @param env The environment that the API is invoked under. 1511 * @param value The JavaScript value to coerce. 1512 * @param result JSVM_Value representing the coerced JavaScript number. 1513 * @return Returns JSVM funtions result code. 1514 * {@link JSVM_OK } If the function executed successfully.\n 1515 * @since 11 1516 */ 1517 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToNumber(JSVM_Env env, 1518 JSVM_Value value, 1519 JSVM_Value* result); 1520 1521 /** 1522 * @brief This API implements the abstract operation ToObject(). 1523 * 1524 * @param env The environment that the API is invoked under. 1525 * @param value The JavaScript value to coerce. 1526 * @param result JSVM_Value representing the coerced JavaScript Object. 1527 * @return Returns JSVM funtions result code. 1528 * {@link JSVM_OK } If the function executed successfully.\n 1529 * @since 11 1530 */ 1531 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToObject(JSVM_Env env, 1532 JSVM_Value value, 1533 JSVM_Value* result); 1534 1535 /** 1536 * @brief This API implements the abstract operation ToString().This 1537 * function potentially runs JS code if the passed-in value is an object. 1538 * 1539 * @param env The environment that the API is invoked under. 1540 * @param value The JavaScript value to coerce. 1541 * @param result JSVM_Value representing the coerced JavaScript string. 1542 * @return Returns JSVM funtions result code. 1543 * {@link JSVM_OK } If the function executed successfully.\n 1544 * @since 11 1545 */ 1546 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToString(JSVM_Env env, 1547 JSVM_Value value, 1548 JSVM_Value* result); 1549 1550 /** 1551 * @brief This API represents behavior similar to invoking the typeof Operator 1552 * on the object as defined. However, there are some differences:It has support 1553 * for detecting an External value.It detects null as a separate type, while 1554 * ECMAScript typeof would detect object.If value has a type that is invalid, 1555 * an error is returned. 1556 * 1557 * @param env The environment that the API is invoked under. 1558 * @param value The JavaScript value whose type to query. 1559 * @param result The type of the JavaScript value. 1560 * @return Returns JSVM funtions result code. 1561 * {@link JSVM_OK } If the function executed successfully.\n 1562 * @since 11 1563 */ 1564 JSVM_EXTERN JSVM_Status OH_JSVM_Typeof(JSVM_Env env, 1565 JSVM_Value value, 1566 JSVM_ValueType* result); 1567 1568 /** 1569 * @brief This API represents invoking the instanceof Operator on the object. 1570 * 1571 * @param env The environment that the API is invoked under. 1572 * @param object The JavaScript value to check. 1573 * @param constructor The JavaScript function object of the constructor function 1574 * to check against. 1575 * @param result Boolean that is set to true if object instanceof constructor is true. 1576 * @return Returns JSVM funtions result code. 1577 * {@link JSVM_OK } If the function executed successfully.\n 1578 * @since 11 1579 */ 1580 JSVM_EXTERN JSVM_Status OH_JSVM_Instanceof(JSVM_Env env, 1581 JSVM_Value object, 1582 JSVM_Value constructor, 1583 bool* result); 1584 1585 /** 1586 * @brief This API represents invoking the IsArray operation on the object 1587 * 1588 * @param env The environment that the API is invoked under. 1589 * @param value The JavaScript value to check. 1590 * @param result Whether the given object is an array. 1591 * @return Returns JSVM funtions result code. 1592 * {@link JSVM_OK } If the function executed successfully.\n 1593 * @since 11 1594 */ 1595 JSVM_EXTERN JSVM_Status OH_JSVM_IsArray(JSVM_Env env, 1596 JSVM_Value value, 1597 bool* result); 1598 1599 /** 1600 * @brief This API checks if the Object passed in is an array buffer. 1601 * 1602 * @param env The environment that the API is invoked under. 1603 * @param value The JavaScript value to check. 1604 * @param result Whether the given object is an ArrayBuffer. 1605 * @return Returns JSVM funtions result code. 1606 * {@link JSVM_OK } If the function executed successfully.\n 1607 * @since 11 1608 */ 1609 JSVM_EXTERN JSVM_Status OH_JSVM_IsArraybuffer(JSVM_Env env, 1610 JSVM_Value value, 1611 bool* result); 1612 1613 /** 1614 * @brief This API checks if the Object passed in is a date. 1615 * 1616 * @param env The environment that the API is invoked under. 1617 * @param value The JavaScript value to check. 1618 * @param isDate Whether the given JSVM_Value represents a JavaScript Date object. 1619 * @return Returns JSVM funtions result code. 1620 * {@link JSVM_OK } If the function executed successfully.\n 1621 * @since 11 1622 */ 1623 JSVM_EXTERN JSVM_Status OH_JSVM_IsDate(JSVM_Env env, 1624 JSVM_Value value, 1625 bool* isDate); 1626 1627 /** 1628 * @brief This API checks if the Object passed in is a typed array. 1629 * 1630 * @param env The environment that the API is invoked under. 1631 * @param value The JavaScript value to check. 1632 * @param result Whether the given JSVM_Value represents a TypedArray. 1633 * @return Returns JSVM funtions result code. 1634 * {@link JSVM_OK } If the function executed successfully.\n 1635 * @since 11 1636 */ 1637 JSVM_EXTERN JSVM_Status OH_JSVM_IsTypedarray(JSVM_Env env, 1638 JSVM_Value value, 1639 bool* result); 1640 1641 /** 1642 * @brief This API checks if the Object passed in is a DataView. 1643 * 1644 * @param env The environment that the API is invoked under. 1645 * @param value The JavaScript value to check. 1646 * @param result Whether the given JSVM_Value represents a DataView. 1647 * @return Returns JSVM funtions result code. 1648 * {@link JSVM_OK } If the function executed successfully.\n 1649 * @since 11 1650 */ 1651 JSVM_EXTERN JSVM_Status OH_JSVM_IsDataview(JSVM_Env env, 1652 JSVM_Value value, 1653 bool* result); 1654 1655 /** 1656 * @brief This API represents the invocation of the Strict Equality algorithm. 1657 * 1658 * @param env The environment that the API is invoked under. 1659 * @param lhs The JavaScript value to check. 1660 * @param rhs The JavaScript value to check against. 1661 * @param result Whether the two JSVM_Value objects are equal. 1662 * @return Returns JSVM funtions result code. 1663 * {@link JSVM_OK } If the function executed successfully.\n 1664 * @since 11 1665 */ 1666 JSVM_EXTERN JSVM_Status OH_JSVM_StrictEquals(JSVM_Env env, 1667 JSVM_Value lhs, 1668 JSVM_Value rhs, 1669 bool* result); 1670 1671 /** 1672 * @brief This API represents the invocation of the Relaxed Equality algorithm. 1673 * Returns true as long as the values are equal, regardless of type. 1674 * 1675 * @param env The environment that the API is invoked under. 1676 * @param lhs The JavaScript value to check. 1677 * @param rhs The JavaScript value to check against. 1678 * @param result Whether the two JSVM_Value objects are relaxed equal. 1679 * @return Returns JSVM funtions result code. 1680 * {@link JSVM_OK } If the function executed successfully.\n 1681 * @since 12 1682 */ 1683 JSVM_EXTERN JSVM_Status OH_JSVM_Equals(JSVM_Env env, 1684 JSVM_Value lhs, 1685 JSVM_Value rhs, 1686 bool* result); 1687 1688 /** 1689 * @brief This API represents the invocation of the ArrayBuffer detach operation. 1690 * 1691 * @param env The environment that the API is invoked under. 1692 * @param arraybuffer The JavaScript ArrayBuffer to be detached. 1693 * @return Returns JSVM funtions result code. 1694 * {@link JSVM_OK } If the function executed successfully.\n 1695 * {@link JSVM_DETACHABLE_ARRAYBUFFER_EXPECTED } If a non-detachable ArrayBuffer is passed in it.\n 1696 * @since 11 1697 */ 1698 JSVM_EXTERN JSVM_Status OH_JSVM_DetachArraybuffer(JSVM_Env env, 1699 JSVM_Value arraybuffer); 1700 1701 /** 1702 * @brief This API represents the invocation of the ArrayBuffer IsDetachedBuffer operation. 1703 * 1704 * @param env The environment that the API is invoked under. 1705 * @param value The JavaScript ArrayBuffer to be checked. 1706 * @param result Whether the arraybuffer is detached. 1707 * @return Returns JSVM funtions result code. 1708 * {@link JSVM_OK } If the function executed successfully.\n 1709 * @since 11 1710 */ 1711 JSVM_EXTERN JSVM_Status OH_JSVM_IsDetachedArraybuffer(JSVM_Env env, 1712 JSVM_Value value, 1713 bool* result); 1714 1715 /** 1716 * @brief This API returns the names of the enumerable properties of object as an array of 1717 * strings. The properties of object whose key is a symbol will not be included. 1718 * 1719 * @param env The environment that the API is invoked under. 1720 * @param object The object from which to retrieve the properties. 1721 * @param result A JSVM_Value representing an array of JavaScript values that represent 1722 * the property names of the object. The API can be used to iterate over result using 1723 * OH_JSVM_GetArrayLength and OH_JSVM_GetElement. 1724 * @return Returns JSVM funtions result code. 1725 * {@link JSVM_OK } If the function executed successfully.\n 1726 * @since 11 1727 */ 1728 JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env, 1729 JSVM_Value object, 1730 JSVM_Value* result); 1731 1732 /** 1733 * @brief This API returns an array containing the names of the available properties 1734 * of this object. 1735 * 1736 * @param env The environment that the API is invoked under. 1737 * @param object The object from which to retrieve the properties. 1738 * @param keyMode Whether to retrieve prototype properties as well. 1739 * @param keyFilter Which properties to retrieve (enumerable/readable/writable). 1740 * @param keyConversion Whether to convert numbered property keys to strings. 1741 * @param result A JSVM_Value representing an array of JavaScript values 1742 * that represent the property names of the object. OH_JSVM_GetArrayLength and 1743 * OH_JSVM_GetElement can be used to iterate over result. 1744 * @return Returns JSVM funtions result code. 1745 * {@link JSVM_OK } If the function executed successfully.\n 1746 * @since 11 1747 */ 1748 JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env, 1749 JSVM_Value object, 1750 JSVM_KeyCollectionMode keyMode, 1751 JSVM_KeyFilter keyFilter, 1752 JSVM_KeyConversion keyConversion, 1753 JSVM_Value* result); 1754 1755 /** 1756 * @brief This API set a property on the Object passed in. 1757 * 1758 * @param env The environment that the API is invoked under. 1759 * @param object The object on which to set the property. 1760 * @param key The name of the property to set. 1761 * @param value The property value. 1762 * @return Returns JSVM funtions result code. 1763 * {@link JSVM_OK } If the function executed successfully.\n 1764 * @since 11 1765 */ 1766 JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, 1767 JSVM_Value object, 1768 JSVM_Value key, 1769 JSVM_Value value); 1770 1771 /** 1772 * @brief This API gets the requested property from the Object passed in. 1773 * 1774 * @param env The environment that the API is invoked under. 1775 * @param object The object from which to retrieve the property. 1776 * @param key The name of the property to retrieve. 1777 * @param result The value of the property. 1778 * @return Returns JSVM funtions result code. 1779 * {@link JSVM_OK } If the function executed successfully.\n 1780 * @since 11 1781 */ 1782 JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, 1783 JSVM_Value object, 1784 JSVM_Value key, 1785 JSVM_Value* result); 1786 1787 /** 1788 * @brief This API checks if the Object passed in has the named property. 1789 * 1790 * @param env The environment that the API is invoked under. 1791 * @param object The object to query. 1792 * @param key The name of the property whose existence to check. 1793 * @param result Whether the property exists on the object or not. 1794 * @return Returns JSVM funtions result code. 1795 * {@link JSVM_OK } If the function executed successfully.\n 1796 * @since 11 1797 */ 1798 JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, 1799 JSVM_Value object, 1800 JSVM_Value key, 1801 bool* result); 1802 1803 /** 1804 * @brief This API attempts to delete the key own property from object. 1805 * 1806 * @param env The environment that the API is invoked under. 1807 * @param object The object to query. 1808 * @param key The name of the property to delete. 1809 * @param result Whether the property deletion succeeded or not. result 1810 * can optionally be ignored by passing NULL. 1811 * @return Returns JSVM funtions result code. 1812 * {@link JSVM_OK } If the function executed successfully.\n 1813 * @since 11 1814 */ 1815 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env, 1816 JSVM_Value object, 1817 JSVM_Value key, 1818 bool* result); 1819 1820 /** 1821 * @brief This API checks if the Object passed in has the named own property. 1822 * key must be a string or a symbol, or an error will be thrown. JSVM-API will 1823 * not perform any conversion between data types. 1824 * 1825 * @param env The environment that the API is invoked under. 1826 * @param object The object to query. 1827 * @param key The name of the own property whose existence to check. 1828 * @param result Whether the own property exists on the object or not. 1829 * @return Returns JSVM funtions result code. 1830 * {@link JSVM_OK } If the function executed successfully.\n 1831 * @since 11 1832 */ 1833 JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, 1834 JSVM_Value object, 1835 JSVM_Value key, 1836 bool* result); 1837 1838 /** 1839 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1840 * a JSVM_Value created from the string passed in as utf8name. 1841 * 1842 * @param env The environment that the API is invoked under. 1843 * @param object The object on which to set the property. 1844 * @param utf8name The name of the property to set. 1845 * @param value The property value. 1846 * @return Returns JSVM funtions result code. 1847 * {@link JSVM_OK } If the function executed successfully.\n 1848 * @since 11 1849 */ 1850 JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, 1851 JSVM_Value object, 1852 const char* utf8name, 1853 JSVM_Value value); 1854 1855 /** 1856 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1857 * a JSVM_Value created from the string passed in as utf8name. 1858 * 1859 * @param env The environment that the API is invoked under. 1860 * @param object The object from which to retrieve the property. 1861 * @param utf8name The name of the property to get. 1862 * @param result The value of the property. 1863 * @return Returns JSVM funtions result code. 1864 * {@link JSVM_OK } If the function executed successfully.\n 1865 * @since 11 1866 */ 1867 JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, 1868 JSVM_Value object, 1869 const char* utf8name, 1870 JSVM_Value* result); 1871 1872 /** 1873 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1874 * a JSVM_Value created from the string passed in as utf8name. 1875 * 1876 * @param env The environment that the API is invoked under. 1877 * @param object The object to query. 1878 * @param utf8name The name of the property whose existence to check. 1879 * @param result Whether the property exists on the object or not. 1880 * @return Returns JSVM funtions result code. 1881 * {@link JSVM_OK } If the function executed successfully.\n 1882 * @since 11 1883 */ 1884 JSVM_EXTERN JSVM_Status OH_JSVM_HasNamedProperty(JSVM_Env env, 1885 JSVM_Value object, 1886 const char* utf8name, 1887 bool* result); 1888 1889 /** 1890 * @brief This API sets an element on the Object passed in. 1891 * 1892 * @param env The environment that the API is invoked under. 1893 * @param object The object from which to set the properties. 1894 * @param index The index of the property to set. 1895 * @param value The property value. 1896 * @return Returns JSVM funtions result code. 1897 * {@link JSVM_OK } If the function executed successfully.\n 1898 * @since 11 1899 */ 1900 JSVM_EXTERN JSVM_Status OH_JSVM_SetElement(JSVM_Env env, 1901 JSVM_Value object, 1902 uint32_t index, 1903 JSVM_Value value); 1904 1905 /** 1906 * @brief This API gets the element at the requested index. 1907 * 1908 * @param env The environment that the API is invoked under. 1909 * @param object The object from which to retrieve the property. 1910 * @param index The index of the property to get. 1911 * @param result The value of the property. 1912 * @return Returns JSVM funtions result code. 1913 * {@link JSVM_OK } If the function executed successfully.\n 1914 * @since 11 1915 */ 1916 JSVM_EXTERN JSVM_Status OH_JSVM_GetElement(JSVM_Env env, 1917 JSVM_Value object, 1918 uint32_t index, 1919 JSVM_Value* result); 1920 1921 /** 1922 * @brief This API returns if the Object passed in has an element 1923 * at the requested index. 1924 * 1925 * @param env The environment that the API is invoked under. 1926 * @param object The object to query. 1927 * @param index The index of the property whose existence to check. 1928 * @param result Whether the property exists on the object or not. 1929 * @return Returns JSVM funtions result code. 1930 * {@link JSVM_OK } If the function executed successfully.\n 1931 * @since 11 1932 */ 1933 JSVM_EXTERN JSVM_Status OH_JSVM_HasElement(JSVM_Env env, 1934 JSVM_Value object, 1935 uint32_t index, 1936 bool* result); 1937 1938 /** 1939 * @brief This API attempts to delete the specified index from object. 1940 * 1941 * @param env The environment that the API is invoked under. 1942 * @param object The object to query. 1943 * @param index The index of the property to delete. 1944 * @param result Whether the element deletion succeeded or not. result 1945 * can optionally be ignored by passing NULL. 1946 * @return Returns JSVM funtions result code. 1947 * {@link JSVM_OK } If the function executed successfully.\n 1948 * @since 11 1949 */ 1950 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, 1951 JSVM_Value object, 1952 uint32_t index, 1953 bool* result); 1954 1955 /** 1956 * @brief This method allows the efficient definition of multiple properties 1957 * on a given object. The properties are defined using property descriptors. 1958 * Given an array of such property descriptors, this API will set the properties 1959 * on the object one at a time, as defined by DefineOwnProperty(). 1960 * 1961 * @param env The environment that the API is invoked under. 1962 * @param object The object from which to retrieve the properties. 1963 * @param propertyCount The number of elements in the properties array. 1964 * @param properties The array of property descriptors. 1965 * @return Returns JSVM funtions result code. 1966 * {@link JSVM_OK } If the function executed successfully.\n 1967 * @since 11 1968 */ 1969 JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env, 1970 JSVM_Value object, 1971 size_t propertyCount, 1972 const JSVM_PropertyDescriptor* properties); 1973 1974 /** 1975 * @brief This method freezes a given object. This prevents new properties 1976 * from being added to it, existing properties from being removed, prevents 1977 * changing the enumerability, configurability, or writability of existing 1978 * properties, and prevents the values of existing properties from being changed. 1979 * It also prevents the object's prototype from being changed. 1980 * 1981 * @param env The environment that the API is invoked under. 1982 * @param object The object to freeze. 1983 * @return Returns JSVM funtions result code. 1984 * {@link JSVM_OK } If the function executed successfully.\n 1985 * @since 11 1986 */ 1987 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectFreeze(JSVM_Env env, 1988 JSVM_Value object); 1989 1990 /** 1991 * @brief This method seals a given object. This prevents new properties 1992 * from being added to it, as well as marking all existing properties as non-configurable. 1993 * 1994 * @param env The environment that the API is invoked under. 1995 * @param object The object to seal. 1996 * @return Returns JSVM funtions result code. 1997 * {@link JSVM_OK } If the function executed successfully.\n 1998 * @since 11 1999 */ 2000 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectSeal(JSVM_Env env, 2001 JSVM_Value object); 2002 2003 /** 2004 * @brief This method allows a JavaScript function object to be called from 2005 * a native add-on. This is the primary mechanism of calling back from the 2006 * add-on's native code into JavaScript. 2007 * 2008 * @param env The environment that the API is invoked under. 2009 * @param recv The this value passed to the called function. 2010 * @param func JSVM_Value representing the JavaScript function to be invoked. 2011 * @param argc The count of elements in the argv array. 2012 * @param argv Array of JSVM_values representing JavaScript values passed in as arguments to the function. 2013 * @param result JSVM_Value representing the JavaScript object returned. 2014 * @return Returns JSVM funtions result code. 2015 * {@link JSVM_OK } If the function executed successfully.\n 2016 * @since 11 2017 */ 2018 JSVM_EXTERN JSVM_Status OH_JSVM_CallFunction(JSVM_Env env, 2019 JSVM_Value recv, 2020 JSVM_Value func, 2021 size_t argc, 2022 const JSVM_Value* argv, 2023 JSVM_Value* result); 2024 2025 /** 2026 * @brief This API allows an add-on author to create a function object in native 2027 * code. This is the primary mechanism to allow calling into the add-on's native 2028 * code from JavaScript.The newly created function is not automatically visible 2029 * from script after this call. Instead, a property must be explicitly set on any 2030 * object that is visible to JavaScript, in order for the function to be accessible 2031 * from script. 2032 * 2033 * @param env The environment that the API is invoked under. 2034 * @param utf8name Optional name of the function encoded as UTF8. This is visible 2035 * within JavaScript as the new function object's name property. 2036 * @param length The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 2037 * is null-terminated. 2038 * @param cb The native function which should be called when this function 2039 * object is invoked and data. JSVM_Callback provides more details. 2040 * @param result JSVM_Value representing the JavaScript function object for the newly 2041 * created function. 2042 * @return Returns JSVM funtions result code. 2043 * {@link JSVM_OK } If the function executed successfully.\n 2044 * @since 11 2045 */ 2046 JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunction(JSVM_Env env, 2047 const char* utf8name, 2048 size_t length, 2049 JSVM_Callback cb, 2050 JSVM_Value* result); 2051 2052 /** 2053 * @brief This method is used within a callback function to retrieve details about 2054 * the call like the arguments and the this pointer from a given callback info. 2055 * 2056 * @param env The environment that the API is invoked under. 2057 * @param cbinfo The callback info passed into the callback function. 2058 * @param argc Specifies the length of the provided argv array and receives the 2059 * actual count of arguments. argc can optionally be ignored by passing NULL. 2060 * @param argv C array of JSVM_values to which the arguments will be copied. If 2061 * there are more arguments than the provided count, only the requested number of 2062 * arguments are copied. If there are fewer arguments provided than claimed, the 2063 * rest of argv is filled with JSVM_Value values that represent undefined. argv 2064 * can optionally be ignored by passing NULL. 2065 * @param thisArg Receives the JavaScript this argument for the call. thisArg 2066 * can optionally be ignored by passing NULL. 2067 * @param data Receives the data pointer for the callback. data can optionally 2068 * be ignored by passing NULL. 2069 * @return Returns JSVM funtions result code. 2070 * {@link JSVM_OK } If the function executed successfully.\n 2071 * @since 11 2072 */ 2073 JSVM_EXTERN JSVM_Status OH_JSVM_GetCbInfo(JSVM_Env env, 2074 JSVM_CallbackInfo cbinfo, 2075 size_t* argc, 2076 JSVM_Value* argv, 2077 JSVM_Value* thisArg, 2078 void** data); 2079 2080 /** 2081 * @brief This API returns the new.target of the constructor call. If the 2082 * current callback is not a constructor call, the result is NULL. 2083 * 2084 * @param env The environment that the API is invoked under. 2085 * @param cbinfo The callback info passed into the callback function. 2086 * @param result The new.target of the constructor call. 2087 * @return Returns JSVM funtions result code. 2088 * {@link JSVM_OK } If the function executed successfully.\n 2089 * @since 11 2090 */ 2091 JSVM_EXTERN JSVM_Status OH_JSVM_GetNewTarget(JSVM_Env env, 2092 JSVM_CallbackInfo cbinfo, 2093 JSVM_Value* result); 2094 2095 /** 2096 * @brief his method is used to instantiate a new JavaScript value using 2097 * a given JSVM_Value that represents the constructor for the object. 2098 * 2099 * @param env The environment that the API is invoked under. 2100 * @param constructor JSVM_Value representing the JavaScript function to be invoked as a constructor. 2101 * @param argc The count of elements in the argv array. 2102 * @param argv Array of JavaScript values as JSVM_Value representing the arguments to 2103 * the constructor. If argc is zero this parameter may be omitted by passing in NULL. 2104 * @param result JSVM_Value representing the JavaScript object returned, which 2105 * in this case is the constructed object. 2106 * @return Returns JSVM funtions result code. 2107 * {@link JSVM_OK } If the function executed successfully.\n 2108 * @since 11 2109 */ 2110 JSVM_EXTERN JSVM_Status OH_JSVM_NewInstance(JSVM_Env env, 2111 JSVM_Value constructor, 2112 size_t argc, 2113 const JSVM_Value* argv, 2114 JSVM_Value* result); 2115 2116 /** 2117 * @brief When wrapping a C++ class, the C++ constructor callback passed via constructor 2118 * should be a static method on the class that calls the actual class constructor, then 2119 * wraps the new C++ instance in a JavaScript object, and returns the wrapper object. 2120 * 2121 * @param env The environment that the API is invoked under. 2122 * @param utf8name Name of the JavaScript constructor function. For clarity, it is 2123 * recommended to use the C++ class name when wrapping a C++ class. 2124 * @param length The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 2125 * is null-terminated. 2126 * @param constructor Struct include callback function that handles constructing instances of the class. 2127 * When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback 2128 * signature. A C++ class constructor cannot be used. 2129 * Include Optional data to be passed to the constructor callback as the data 2130 * property of the callback info. JSVM_Callback provides more details. 2131 * @param propertyCount Number of items in the properties array argument. 2132 * @param properties Array of property descriptors describing static and instance data 2133 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 2134 * @param result A JSVM_Value representing the constructor function for the class. 2135 * @return Returns JSVM funtions result code. 2136 * {@link JSVM_OK } If the function executed successfully.\n 2137 * @since 11 2138 */ 2139 JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, 2140 const char* utf8name, 2141 size_t length, 2142 JSVM_Callback constructor, 2143 size_t propertyCount, 2144 const JSVM_PropertyDescriptor* properties, 2145 JSVM_Value* result); 2146 2147 /** 2148 * @brief Wraps a native instance in a JavaScript object. The native instance can 2149 * be retrieved later using OH_JSVM_Unwrap(). 2150 * 2151 * @param env The environment that the API is invoked under. 2152 * @param jsObject The JavaScript object that will be the wrapper for the native object. 2153 * @param nativeObject The native instance that will be wrapped in the JavaScript object. 2154 * @param finalizeCb Optional native callback that can be used to free the native instance 2155 * when the JavaScript object has been garbage-collected. 2156 * @param finalizeHint Optional contextual hint that is passed to the finalize callback. 2157 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 2158 * @param result Optional reference to the wrapped object. 2159 * @return Returns JSVM funtions result code. 2160 * {@link JSVM_OK } If the function executed successfully.\n 2161 * @since 11 2162 */ 2163 JSVM_EXTERN JSVM_Status OH_JSVM_Wrap(JSVM_Env env, 2164 JSVM_Value jsObject, 2165 void* nativeObject, 2166 JSVM_Finalize finalizeCb, 2167 void* finalizeHint, 2168 JSVM_Ref* result); 2169 2170 /** 2171 * @brief When JavaScript code invokes a method or property accessor on the class, the corresponding 2172 * JSVM_Callback is invoked. If the callback is for an instance method or accessor, then the this 2173 * argument to the callback is the wrapper object; the wrapped C++ instance that is the target of 2174 * the call can be obtained then by calling OH_JSVM_Unwrap() on the wrapper object. 2175 * 2176 * @param env The environment that the API is invoked under. 2177 * @param jsObject The object associated with the native instance. 2178 * @param result Pointer to the wrapped native instance. 2179 * @return Returns JSVM funtions result code. 2180 * {@link JSVM_OK } If the function executed successfully.\n 2181 * @since 11 2182 */ 2183 JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, 2184 JSVM_Value jsObject, 2185 void** result); 2186 2187 /** 2188 * @brief Retrieves a native instance that was previously wrapped in the JavaScript object jsObject 2189 * using OH_JSVM_Wrap() and removes the wrapping. If a finalize callback was associated with the wrapping, 2190 * it will no longer be called when the JavaScript object becomes garbage-collected. 2191 * 2192 * @param env The environment that the API is invoked under. 2193 * @param jsObject The object associated with the native instance. 2194 * @param result Pointer to the wrapped native instance. 2195 * @return Returns JSVM funtions result code. 2196 * {@link JSVM_OK } If the function executed successfully.\n 2197 * @since 11 2198 */ 2199 JSVM_EXTERN JSVM_Status OH_JSVM_RemoveWrap(JSVM_Env env, 2200 JSVM_Value jsObject, 2201 void** result); 2202 2203 /** 2204 * @brief Associates the value of the typeTag pointer with the JavaScript object or external. 2205 * OH_JSVM_CheckObjectTypeTag() can then be used to compare the tag that was attached to the 2206 * object with one owned by the addon to ensure that the object has the right type. 2207 * If the object already has an associated type tag, this API will return JSVM_INVALID_ARG. 2208 * 2209 * @param env The environment that the API is invoked under. 2210 * @param value The JavaScript object or external to be marked. 2211 * @param typeTag The tag with which the object is to be marked. 2212 * @return Returns JSVM funtions result code. 2213 * {@link JSVM_OK } If the function executed successfully.\n 2214 * {@link JSVM_INVALID_ARG } If the object already has an associated type tag.\n 2215 * @since 11 2216 */ 2217 JSVM_EXTERN JSVM_Status OH_JSVM_TypeTagObject(JSVM_Env env, 2218 JSVM_Value value, 2219 const JSVM_TypeTag* typeTag); 2220 2221 /** 2222 * @brief Compares the pointer given as typeTag with any that can be found on js object. 2223 * If no tag is found on js object or, if a tag is found but it does not match typeTag, 2224 * then result is set to false. If a tag is found and it matches typeTag, then result is set to true. 2225 * 2226 * @param env The environment that the API is invoked under. 2227 * @param value The JavaScript object or external whose type tag to examine. 2228 * @param typeTag The tag with which to compare any tag found on the object. 2229 * @param result Whether the type tag given matched the type tag on the object. false is also returned 2230 * if no type tag was found on the object. 2231 * @return Returns JSVM funtions result code. 2232 * {@link JSVM_OK } If the function executed successfully.\n 2233 * @since 11 2234 */ 2235 JSVM_EXTERN JSVM_Status OH_JSVM_CheckObjectTypeTag(JSVM_Env env, 2236 JSVM_Value value, 2237 const JSVM_TypeTag* typeTag, 2238 bool* result); 2239 2240 /** 2241 * @brief This API can be called multiple times on a single JavaScript object. 2242 * 2243 * @param env The environment that the API is invoked under. 2244 * @param jsObject The JavaScript object to which the native data will be attached. 2245 * @param finalizeData Optional data to be passed to finalizeCb. 2246 * @param finalizeCb Native callback that will be used to free the native data when the 2247 * JavaScript object has been garbage-collected. JSVM_Finalize provides more details. 2248 * @param finalizeHint Optional contextual hint that is passed to the finalize callback. 2249 * @param result Optional reference to the JavaScript object. 2250 * @return Returns JSVM funtions result code. 2251 * {@link JSVM_OK } If the function executed successfully.\n 2252 * @since 11 2253 */ 2254 JSVM_EXTERN JSVM_Status OH_JSVM_AddFinalizer(JSVM_Env env, 2255 JSVM_Value jsObject, 2256 void* finalizeData, 2257 JSVM_Finalize finalizeCb, 2258 void* finalizeHint, 2259 JSVM_Ref* result); 2260 2261 /** 2262 * @brief This API returns the highest JSVM-API version supported by the JSVM runtime. 2263 * 2264 * JSVM-API is planned to be additive such that newer releases of JSVM may support additional 2265 * API functions. In order to allow an addon to use a newer function when running with versions 2266 * of JSVM that support it, while providing fallback behavior when running with JSVM 2267 * versions that don't support it. 2268 * @param env The environment that the API is invoked under. 2269 * @param result The highest version of JSVM-API supported. 2270 * @return Returns JSVM funtions result code. 2271 * {@link JSVM_OK } If the function executed successfully.\n 2272 * @since 11 2273 */ 2274 JSVM_EXTERN JSVM_Status OH_JSVM_GetVersion(JSVM_Env env, 2275 uint32_t* result); 2276 2277 /** 2278 * @brief Return information of the VM. 2279 * 2280 * @param result The information of the VM. 2281 * @return Returns JSVM funtions result code. 2282 * {@link JSVM_OK } If the function executed successfully.\n 2283 * @since 11 2284 */ 2285 JSVM_EXTERN JSVM_Status OH_JSVM_GetVMInfo(JSVM_VMInfo* result); 2286 2287 /** 2288 * @brief This function gives V8 an indication of the amount of externally 2289 * allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript 2290 * object that points to its own memory allocated by a native addon). Registering 2291 * externally allocated memory will trigger global garbage collections more often 2292 * than it would otherwise. 2293 * 2294 * @param env The environment that the API is invoked under. 2295 * @param changeInBytes The change in externally allocated memory that is kept 2296 * alive by JavaScript objects. 2297 * @param result The adjusted value 2298 * @return Returns JSVM funtions result code. 2299 * {@link JSVM_OK } If the function executed successfully.\n 2300 * @since 11 2301 */ 2302 JSVM_EXTERN JSVM_Status OH_JSVM_AdjustExternalMemory(JSVM_Env env, 2303 int64_t changeInBytes, 2304 int64_t* result); 2305 2306 /** 2307 * @brief This function notifies the VM that the system is running low on memory 2308 * and optionally triggers a garbage collection. 2309 * 2310 * @param env The environment that the API is invoked under. 2311 * @param level The memory pressure level set to the current VM. 2312 * @return Returns JSVM funtions result code. 2313 * {@link JSVM_OK } If the function executed successfully.\n 2314 * @since 11 2315 */ 2316 JSVM_EXTERN JSVM_Status OH_JSVM_MemoryPressureNotification(JSVM_Env env, 2317 JSVM_MemoryPressureLevel level); 2318 2319 /** 2320 * @brief This API creates a deferred object and a JavaScript promise. 2321 * 2322 * @param env The environment that the API is invoked under. 2323 * @param deferred A newly created deferred object which can later be 2324 * passed to OH_JSVM_ResolveDeferred() or OH_JSVM_RejectDeferred() to resolve 2325 * resp. reject the associated promise. 2326 * @param promise The JavaScript promise associated with the deferred object. 2327 * @return Returns JSVM funtions result code. 2328 * {@link JSVM_OK } If the function executed successfully.\n 2329 * @since 11 2330 */ 2331 JSVM_EXTERN JSVM_Status OH_JSVM_CreatePromise(JSVM_Env env, 2332 JSVM_Deferred* deferred, 2333 JSVM_Value* promise); 2334 2335 /** 2336 * @brief This API resolves a JavaScript promise by way of the deferred object with 2337 * which it is associated. Thus, it can only be used to resolve JavaScript promises 2338 * for which the corresponding deferred object is available. This effectively means 2339 * that the promise must have been created using OH_JSVM_CreatePromise() and the deferred 2340 * object returned from that call must have been retained in order to be passed to this API. 2341 * 2342 * @param env The environment that the API is invoked under. 2343 * @param deferred The deferred object whose associated promise to resolve. 2344 * @param resolution The value with which to resolve the promise. 2345 * @return Returns JSVM funtions result code. 2346 * {@link JSVM_OK } If the function executed successfully.\n 2347 * @since 11 2348 */ 2349 JSVM_EXTERN JSVM_Status OH_JSVM_ResolveDeferred(JSVM_Env env, 2350 JSVM_Deferred deferred, 2351 JSVM_Value resolution); 2352 2353 /** 2354 * @brief This API rejects a JavaScript promise by way of the deferred object with 2355 * which it is associated. Thus, it can only be used to reject JavaScript promises 2356 * for which the corresponding deferred object is available. This effectively means 2357 * that the promise must have been created using OH_JSVM_CreatePromise() and the deferred 2358 * object returned from that call must have been retained in order to be passed to this API. 2359 * 2360 * @param env The environment that the API is invoked under. 2361 * @param deferred The deferred object whose associated promise to resolve. 2362 * @param rejection The value with which to reject the promise. 2363 * @return Returns JSVM funtions result code. 2364 * {@link JSVM_OK } If the function executed successfully.\n 2365 * @since 11 2366 */ 2367 JSVM_EXTERN JSVM_Status OH_JSVM_RejectDeferred(JSVM_Env env, 2368 JSVM_Deferred deferred, 2369 JSVM_Value rejection); 2370 2371 /** 2372 * @brief This API return indicating whether promise is a native promise object. 2373 * @param env The environment that the API is invoked under. 2374 * @param value The value to examine 2375 * @param isPromise Flag indicating whether promise is a native promise object 2376 * @return Returns JSVM funtions result code. 2377 * {@link JSVM_OK } If the function executed successfully.\n 2378 * @since 11 2379 */ 2380 JSVM_EXTERN JSVM_Status OH_JSVM_IsPromise(JSVM_Env env, 2381 JSVM_Value value, 2382 bool* isPromise); 2383 2384 /** 2385 * @brief This API register a resolution/rejection handler with a promise. 2386 * @param env The environment that the API is invoked under. 2387 * @param promise The promise to be handled. 2388 * @param onFulfilled The function to be invoked if promise is resolved. 2389 * @param onRejected The function to be invoked if promise is rejected. 2390 * @param result Another promise returned from promise then/catch method. 2391 * @return Returns JSVM functions result code. 2392 * {@link JSVM_OK } if the API succeeded. \n 2393 * {@link JSVM_INVALID_ARG } if the arguments are invalid. \n 2394 * {@link JSVM_INVALID_TYPE } if the arguments are invalid Javascript type. \n 2395 * {@link JSVM_PENDING_EXCEPTION} if an exception occurs. \n 2396 * {@link JSVM_GENERIC_FAILURE} if the API failed. \n 2397 * 2398 * @since 18 2399 */ 2400 JSVM_EXTERN JSVM_Status OH_JSVM_PromiseRegisterHandler(JSVM_Env env, 2401 JSVM_Value promise, 2402 JSVM_Value onFulfilled, 2403 JSVM_Value onRejected, 2404 JSVM_Value* result); 2405 2406 /** 2407 * @brief This API parses a JSON string and returns it as value if successful. 2408 * @param env The environment that the API is invoked under. 2409 * @param jsonString The string to parse. 2410 * @param result The parse value if successful. 2411 * @return Returns JSVM funtions result code. 2412 * {@link JSVM_OK } If the function executed successfully.\n 2413 * @since 11 2414 */ 2415 JSVM_EXTERN JSVM_Status OH_JSVM_JsonParse(JSVM_Env env, 2416 JSVM_Value jsonString, 2417 JSVM_Value* result); 2418 2419 /** 2420 * @brief This API stringifies the object and returns it as string if successful. 2421 * @param env The environment that the API is invoked under. 2422 * @param jsonObject The object to stringify. 2423 * @param result The string if successfully stringified. 2424 * @return Returns JSVM funtions result code. 2425 * {@link JSVM_OK } If the function executed successfully.\n 2426 * @since 11 2427 */ 2428 JSVM_EXTERN JSVM_Status OH_JSVM_JsonStringify(JSVM_Env env, 2429 JSVM_Value jsonObject, 2430 JSVM_Value* result); 2431 2432 /** 2433 * @brief This API create the startup snapshot of the VM. 2434 * @param vm The environment that the API is invoked under. 2435 * @param contextCount The object to stringify. 2436 * @param contexts The array of contexts to add to the snapshot. 2437 * @param blobData The snapshot data. 2438 * @param blobSize The size of snapshot data. 2439 * @return Returns JSVM funtions result code. 2440 * {@link JSVM_OK } If the function executed successfully.\n 2441 * @since 11 2442 */ 2443 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSnapshot(JSVM_VM vm, 2444 size_t contextCount, 2445 const JSVM_Env* contexts, 2446 const char** blobData, 2447 size_t* blobSize); 2448 2449 /** 2450 * @brief This function returns a set of statistics data of the heap of the VM. 2451 * 2452 * @param vm The VM whose heap statistics are returned. 2453 * @param result The heap statistics data. 2454 * @return Returns JSVM funtions result code. 2455 * Returns {@link JSVM_OK } in all cases.\n 2456 * @since 12 2457 */ 2458 JSVM_EXTERN JSVM_Status OH_JSVM_GetHeapStatistics(JSVM_VM vm, 2459 JSVM_HeapStatistics* result); 2460 2461 /** 2462 * @brief This function creates and starts a CPU profiler. 2463 * 2464 * @param vm The VM to start CPU profiler for. 2465 * @param result The pointer to the CPU profiler. 2466 * @return Returns JSVM funtions result code. 2467 * Returns {@link JSVM_OK } in all cases.\n 2468 * @since 12 2469 */ 2470 JSVM_EXTERN JSVM_Status OH_JSVM_StartCpuProfiler(JSVM_VM vm, 2471 JSVM_CpuProfiler* result); 2472 2473 /** 2474 * @brief This function stops the CPU profiler and output to the stream. 2475 * 2476 * @param vm THe VM to start CPU profiler for. 2477 * @param profiler The CPU profiler to stop. 2478 * @param stream The output stream callback for receiving the data. 2479 * @param streamData Optional data to be passed to the stream callback. 2480 * @return Returns JSVM funtions result code. 2481 * Returns {@link JSVM_OK } in all cases.\n 2482 * @since 12 2483 */ 2484 JSVM_EXTERN JSVM_Status OH_JSVM_StopCpuProfiler(JSVM_VM vm, 2485 JSVM_CpuProfiler profiler, 2486 JSVM_OutputStream stream, 2487 void* streamData); 2488 2489 /** 2490 * @brief This funciton takes the current heap snapshot and output to the stream. 2491 * 2492 * @param vm The VM whose heap snapshot is taken. 2493 * @param stream The output stream callback for receiving the data. 2494 * @param streamData Optional data to be passed to the stream callback. 2495 * @return Returns JSVM funtions result code. 2496 * Returns {@link JSVM_OK } in all cases.\n 2497 * @since 12 2498 */ 2499 JSVM_EXTERN JSVM_Status OH_JSVM_TakeHeapSnapshot(JSVM_VM vm, 2500 JSVM_OutputStream stream, 2501 void* streamData); 2502 2503 /** 2504 * @brief This functiong activates insepctor on host and port. 2505 * 2506 * @param env The environment that the API is invoked under. 2507 * @param host The host to listen to for inspector connections. 2508 * @param port The port to listen to for inspector connections. 2509 * @return Returns JSVM funtions result code. 2510 * Returns {@link JSVM_OK } if the function executed successfully.\n 2511 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 2512 * @since 12 2513 */ 2514 JSVM_EXTERN JSVM_Status OH_JSVM_OpenInspector(JSVM_Env env, 2515 const char* host, 2516 uint16_t port); 2517 2518 /** 2519 * @brief This function attempts to close all remaining inspector connections. 2520 * 2521 * @param env The environment that the API is invoked under. 2522 * @return Returns JSVM funtions result code. 2523 * Returns {@link JSVM_OK } if the function executed successfully.\n 2524 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 2525 * @since 12 2526 */ 2527 JSVM_EXTERN JSVM_Status OH_JSVM_CloseInspector(JSVM_Env env); 2528 2529 /** 2530 * @brief This function will block until a client (existing or connected later) 2531 * has sent Runtime.runIfWaitingForDebugger command. 2532 * 2533 * @param env The environment that the API is invoked under. 2534 * @param breakNextLine Whether break on the next line of JavaScript code. 2535 * @return Returns JSVM funtions result code. 2536 * Returns {@link JSVM_OK } if the function executed successfully.\n 2537 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 2538 * @since 12 2539 */ 2540 JSVM_EXTERN JSVM_Status OH_JSVM_WaitForDebugger(JSVM_Env env, 2541 bool breakNextLine); 2542 2543 /** 2544 * @brief Define a JavaScript class with given class name, constructor, properties, callback handlers for 2545 * property operations including get, set, delete, enum etc., and call as function callback. 2546 * 2547 * @param env The environment that the API is invoked under. 2548 * @param utf8name Name of the JavaScript constructor function. For clarity, it is 2549 * recommended to use the C++ class name when wrapping a C++ class. 2550 * @param length The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 2551 * is null-terminated. 2552 * @param constructor Struct include callback function that handles constructing instances of the class. 2553 * When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback 2554 * signature. A C++ class constructor cannot be used. 2555 * Include Optional data to be passed to the constructor callback as the data 2556 * property of the callback info. JSVM_Callback provides more details. 2557 * @param propertyCount Number of items in the properties array argument. 2558 * @param properties Array of property descriptors describing static and instance data 2559 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 2560 * @param propertyHandlerCfg The instance object triggers the corresponding callback function. 2561 * @param callAsFunctionCallback Calling an instance object as a function will trigger this callback. 2562 * @param result A JSVM_Value representing the constructor function for the class. 2563 * @return Returns JSVM funtions result code. 2564 * {@link JSVM_OK } If the function executed successfully.\n 2565 * @since 12 2566 */ 2567 JSVM_EXTERN JSVM_Status OH_JSVM_DefineClassWithPropertyHandler(JSVM_Env env, 2568 const char* utf8name, 2569 size_t length, 2570 JSVM_Callback constructor, 2571 size_t propertyCount, 2572 const JSVM_PropertyDescriptor* properties, 2573 JSVM_PropertyHandlerCfg propertyHandlerCfg, 2574 JSVM_Callback callAsFunctionCallback, 2575 JSVM_Value* result); 2576 2577 /** 2578 * @brief Determines whether the current thread holds the lock for the specified environment. 2579 * Only threads that hold locks can use the environment. 2580 * 2581 * @param env The environment that the API is invoked under. 2582 * @param isLocked Flag indicating whether the current thread holds the lock for the specified environment. 2583 * @return Returns JSVM funtions result code. 2584 * {@link JSVM_OK } If the function executed successfully.\n 2585 * @since 12 2586 */ 2587 JSVM_EXTERN JSVM_Status OH_JSVM_IsLocked(JSVM_Env env, 2588 bool* isLocked); 2589 2590 /** 2591 * @brief Acquire the lock for the specified environment. Only threads that hold locks can use the environment. 2592 * 2593 * @param env The environment that the API is invoked under. 2594 * @return Returns JSVM funtions result code. 2595 * {@link JSVM_OK } If the function executed successfully.\n 2596 * @since 12 2597 */ 2598 JSVM_EXTERN JSVM_Status OH_JSVM_AcquireLock(JSVM_Env env); 2599 2600 /** 2601 * @brief Release the lock for the specified environment. Only threads that hold locks can use the environment. 2602 * 2603 * @param env The environment that the API is invoked under. 2604 * @return Returns JSVM funtions result code. 2605 * {@link JSVM_OK } If the function executed successfully.\n 2606 * @since 12 2607 */ 2608 JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseLock(JSVM_Env env); 2609 2610 /** 2611 * @brief Starts the running of the task queue inside the VM. 2612 * This task queue can be executed by an external event loop. 2613 * 2614 * @param vm The VM instance on which to start the task queue. 2615 * @param result Whether the task queue was successfully started. 2616 * @return Returns JSVM funtions result code. 2617 * {@link JSVM_OK } If the function executed successfully.\n 2618 * @since 12 2619 */ 2620 JSVM_EXTERN JSVM_Status OH_JSVM_PumpMessageLoop(JSVM_VM vm, 2621 bool* result); 2622 2623 /** 2624 * @brief Check to see if there are any microtasks waiting in the queue, and if there are, execute them. 2625 * 2626 * @param vm The VM instance on which to check microtasks. 2627 * @return Returns JSVM funtions result code. 2628 * {@link JSVM_OK } If the function executed successfully.\n 2629 * @since 12 2630 */ 2631 JSVM_EXTERN JSVM_Status OH_JSVM_PerformMicrotaskCheckpoint(JSVM_VM vm); 2632 2633 /** 2634 * @brief This API checks if the value passed in is callable. 2635 * 2636 * @param env The VM instance on which to check microtasks. 2637 * @param value The JavaScript value to check. 2638 * @param isCallable Whether the given value is callable. 2639 * @return Returns JSVM funtions result code. 2640 * {@link JSVM_OK } If the function executed successfully.\n 2641 * @since 12 2642 */ 2643 JSVM_EXTERN JSVM_Status OH_JSVM_IsCallable(JSVM_Env env, 2644 JSVM_Value value, 2645 bool* isCallable); 2646 2647 /** 2648 * @brief This API checks if the value passed in is undefined. 2649 * This equals to `value === undefined` in JS. 2650 * 2651 * @param env The VM instance on which to check microtasks. 2652 * @param value The JavaScript value to check. 2653 * @param isUndefined Whether the given value is Undefined. 2654 * @return Returns JSVM funtions result code. 2655 * {@link JSVM_OK } This API will not trigger any exception.\n 2656 * @since 12 2657 */ 2658 JSVM_EXTERN JSVM_Status OH_JSVM_IsUndefined(JSVM_Env env, 2659 JSVM_Value value, 2660 bool* isUndefined); 2661 2662 /** 2663 * @brief This API checks if the value passed in is a null object. 2664 * This equals to `value === null` in JS. 2665 * 2666 * @param env The VM instance on which to check microtasks. 2667 * @param value The JavaScript value to check. 2668 * @param isNull Whether the given value is Null. 2669 * @return Only returns JSVM funtions result code. 2670 * {@link JSVM_OK } This API will not trigger any exception.\n 2671 * @since 12 2672 */ 2673 JSVM_EXTERN JSVM_Status OH_JSVM_IsNull(JSVM_Env env, 2674 JSVM_Value value, 2675 bool* isNull); 2676 2677 /** 2678 * @brief This API checks if the value passed in is either a null or an undefined object. 2679 * This is equivalent to `value == null` in JS. 2680 * 2681 * @param env The VM instance on which to check microtasks. 2682 * @param value The JavaScript value to check. 2683 * @param isNullOrUndefined Whether the given value is Null or Undefined. 2684 * @return Only returns JSVM funtions result code. 2685 * {@link JSVM_OK } This API will not trigger any exception.\n 2686 * @since 12 2687 */ 2688 JSVM_EXTERN JSVM_Status OH_JSVM_IsNullOrUndefined(JSVM_Env env, 2689 JSVM_Value value, 2690 bool* isNullOrUndefined); 2691 2692 /** 2693 * @brief This API checks if the value passed in is a boolean. 2694 * This equals to `typeof value === 'boolean'` in JS. 2695 * 2696 * @param env The VM instance on which to check microtasks. 2697 * @param value The JavaScript value to check. 2698 * @param isBoolean Whether the given value is Boolean. 2699 * @return Only returns JSVM funtions result code. 2700 * {@link JSVM_OK } This API will not trigger any exception.\n 2701 * @since 12 2702 */ 2703 JSVM_EXTERN JSVM_Status OH_JSVM_IsBoolean(JSVM_Env env, 2704 JSVM_Value value, 2705 bool* isBoolean); 2706 2707 /** 2708 * @brief This API checks if the value passed in is a number. 2709 * This equals to `typeof value === 'number'` in JS. 2710 * 2711 * @param env The VM instance on which to check microtasks. 2712 * @param value The JavaScript value to check. 2713 * @param isNumber Whether the given value is Number. 2714 * @return Only returns JSVM funtions result code. 2715 * {@link JSVM_OK } This API will not trigger any exception.\n 2716 * @since 12 2717 */ 2718 JSVM_EXTERN JSVM_Status OH_JSVM_IsNumber(JSVM_Env env, 2719 JSVM_Value value, 2720 bool* isNumber); 2721 2722 /** 2723 * @brief This API checks if the value passed in is a string. 2724 * This equals to `typeof value === 'string'` in JS. 2725 * 2726 * @param env The VM instance on which to check microtasks. 2727 * @param value The JavaScript value to check. 2728 * @param isString Whether the given value is String. 2729 * @return Only returns JSVM funtions result code. 2730 * {@link JSVM_OK } This API will not trigger any exception.\n 2731 * @since 12 2732 */ 2733 JSVM_EXTERN JSVM_Status OH_JSVM_IsString(JSVM_Env env, 2734 JSVM_Value value, 2735 bool* isString); 2736 2737 /** 2738 * @brief This API checks if the value passed in is a symbol. 2739 * This equals to `typeof value === 'symbol'` in JS. 2740 * 2741 * @param env The VM instance on which to check microtasks. 2742 * @param value The JavaScript value to check. 2743 * @param isSymbol Whether the given value is Symbol. 2744 * @return Only returns JSVM funtions result code. 2745 * {@link JSVM_OK } This API will not trigger any exception.\n 2746 * @since 12 2747 */ 2748 JSVM_EXTERN JSVM_Status OH_JSVM_IsSymbol(JSVM_Env env, 2749 JSVM_Value value, 2750 bool* isSymbol); 2751 2752 /** 2753 * @brief This API checks if the value passed in is a function. 2754 * This equals to `typeof value === 'function'` in JS. 2755 * 2756 * @param env The VM instance on which to check microtasks. 2757 * @param value The JavaScript value to check. 2758 * @param isFunction Whether the given value is Function. 2759 * @return Only returns JSVM funtions result code. 2760 * {@link JSVM_OK } This API will not trigger any exception.\n 2761 * @since 12 2762 */ 2763 JSVM_EXTERN JSVM_Status OH_JSVM_IsFunction(JSVM_Env env, 2764 JSVM_Value value, 2765 bool* isFunction); 2766 2767 /** 2768 * @brief This API checks if the value passed in is an object. 2769 * 2770 * @param env The VM instance on which to check microtasks. 2771 * @param value The JavaScript value to check. 2772 * @param isObject Whether the given value is Object. 2773 * @return Only returns JSVM funtions result code. 2774 * {@link JSVM_OK } This API will not trigger any exception.\n 2775 * @since 12 2776 */ 2777 JSVM_EXTERN JSVM_Status OH_JSVM_IsObject(JSVM_Env env, 2778 JSVM_Value value, 2779 bool* isObject); 2780 2781 /** 2782 * @brief This API checks if the value passed in is a bigInt. 2783 * This equals to `typeof value === 'bigint'` in JS. 2784 * 2785 * @param env The VM instance on which to check microtasks. 2786 * @param value The JavaScript value to check. 2787 * @param isBigInt Whether the given value is BigInt. 2788 * @return Only returns JSVM funtions result code. 2789 * {@link JSVM_OK } This API will not trigger any exception.\n 2790 * @since 12 2791 */ 2792 JSVM_EXTERN JSVM_Status OH_JSVM_IsBigInt(JSVM_Env env, 2793 JSVM_Value value, 2794 bool* isBigInt); 2795 2796 /** 2797 * @brief This API returns a JSVM-API value corresponding to a JavaScript Map type. 2798 * 2799 * @param env The environment that the API is invoked under. 2800 * @param result A JSVM_Value representing a JavaScript Map. 2801 * @return Only returns JSVM function's result code. 2802 * {@link JSVM_OK } If the API succeeded.\n 2803 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2804 * @since 12 2805 */ 2806 JSVM_Status JSVM_CDECL OH_JSVM_CreateMap(JSVM_Env env, JSVM_Value* result); 2807 2808 /** 2809 * @brief This API checks if the value passed in is a Map. 2810 * 2811 * @param env The environment that the API is invoked under. 2812 * @param value The JavaScript value to check. 2813 * @param isMap Whether the given value is Map. 2814 * @return Only returns JSVM function's result code. 2815 * {@link JSVM_OK } If the API succeeded.\n 2816 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2817 * @since 12 2818 */ 2819 JSVM_Status JSVM_CDECL OH_JSVM_IsMap(JSVM_Env env, 2820 JSVM_Value value, 2821 bool* isMap); 2822 2823 /** 2824 * @brief This API returns a JSVM-API value corresponding to a JavaScript Set type. 2825 * 2826 * @param env The environment that the API is invoked under. 2827 * @param result A JSVM_Value representing a JavaScript Set. 2828 * @return Returns JSVM function's result code. 2829 * {@link JSVM_OK } If the API succeeded.\n 2830 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2831 * @since 12 2832 */ 2833 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSet(JSVM_Env env, 2834 JSVM_Value* result); 2835 2836 /** 2837 * @brief This API checks if the value passed in is a Set. 2838 * 2839 * @param env The environment that the API is invoked under. 2840 * @param value The JavaScript value to check. 2841 * @param isSet Whether the given value is Set. 2842 * @return Returns JSVM function's result code. 2843 * {@link JSVM_OK } If the API succeeded.\n 2844 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2845 * @since 12 2846 */ 2847 JSVM_EXTERN JSVM_Status OH_JSVM_IsSet(JSVM_Env env, 2848 JSVM_Value value, 2849 bool* isSet); 2850 2851 /** 2852 * @brief This function compiles a string of JavaScript code with the compile options 2853 * and returns the compiled script. 2854 * 2855 * @param env The environment that the JSVM-API call is invoked under. 2856 * @param script A JavaScript string containing the script to be compiled. 2857 * @param optionCount length of option array. 2858 * @param options Compile options to be passed. 2859 * @param result The compiled script. 2860 * @return Returns JSVM functions result code 2861 * {@link JSVM_OK } if the API succeeded. \n 2862 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2863 * @since 12 2864 */ 2865 JSVM_EXTERN JSVM_Status OH_JSVM_CompileScriptWithOptions(JSVM_Env env, 2866 JSVM_Value script, 2867 size_t optionCount, 2868 JSVM_CompileOptions options[], 2869 JSVM_Script* result); 2870 2871 /** 2872 * @brief This API implements the abstract operation ToBigInt(). 2873 * 2874 * @param env The environment that the API is invoked under. 2875 * @param value The JavaScript value to coerce. 2876 * @param result JSVM_Value representing the coerced JavaScript BigInt. 2877 * @return Returns JSVM function's result code. 2878 * {@link JSVM_OK } If the API succeeded. 2879 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2880 * {@link JSVM_BIGINT_EXPECTED} If the JavaScript value fails to coerce.\n 2881 * @since 12 2882 */ 2883 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBigInt(JSVM_Env env, 2884 JSVM_Value value, 2885 JSVM_Value* result); 2886 2887 /** 2888 * @brief This API checks if the value passed in is a regExp. 2889 * This equals to `value instanceof RegExp` in JS. 2890 * 2891 * @param env The environment that the API is invoked under. 2892 * @param value The JavaScript value to check. 2893 * @param result Whether the given value is RegExp. 2894 * @return Returns JSVM function's result code. 2895 * {@link JSVM_OK } If the API succeeded.\n 2896 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2897 * @since 12 2898 */ 2899 JSVM_EXTERN JSVM_Status OH_JSVM_IsRegExp(JSVM_Env env, 2900 JSVM_Value value, 2901 bool* result); 2902 2903 2904 /** 2905 * @brief This API checks if the value passed in is a constructor. 2906 * 2907 * @param env The environment that the API is invoked under. 2908 * @param value The JavaScript value to check. 2909 * @param isConstructor Whether the given value is Constructor. 2910 * @return Only returns JSVM function's result code. 2911 * {@link JSVM_OK } If the API succeeded.\n 2912 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2913 * @since 12 2914 */ 2915 JSVM_Status JSVM_CDECL OH_JSVM_IsConstructor(JSVM_Env env, 2916 JSVM_Value value, 2917 bool* isConstructor); 2918 2919 /** 2920 * @brief This API returns the JavaScript value of the regular expression 2921 * corresponding to the input. 2922 * The interface may throw an exception. 2923 * 2924 * @param env The environment that the API is invoked under. 2925 * @param value The JavaScript string to convert to a regular expression. 2926 * @param flags Regular expression flag bits. 2927 * @param result A JSVM_Value representing a JavaScript RegExp. 2928 * @return Only returns JSVM function's result code. 2929 * {@link JSVM_OK } If the API succeeded.\n 2930 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2931 * {@link JSVM_STRING_EXPECTED } If the value of 'value' is not a string.\n 2932 * {@link JSVM_GENERIC_FAILURE } If create RegExp failed.\n 2933 * {@link JSVM_PENDING_EXCEPTION } If the API throws an exception during runtime.\n 2934 * @since 12 2935 */ 2936 JSVM_Status JSVM_CDECL OH_JSVM_CreateRegExp(JSVM_Env env, 2937 JSVM_Value value, 2938 JSVM_RegExpFlags flags, 2939 JSVM_Value* result); 2940 2941 /** 2942 * @brief This API returns the Object prototype. 2943 * 2944 * @param env The environment that the API is invoked under. 2945 * @param object JSVM_Value representing JavaScript Object whose prototype to return. This returns 2946 * the equivalent of Object.getPrototypeOf (which is not the same as the function's prototype property). 2947 * @param result JSVM_Value representing prototype of the given object. 2948 * @return Returns JSVM function's result code. 2949 * {@link JSVM_OK } If the API succeeded.\n 2950 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2951 * @since 12 2952 */ 2953 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectGetPrototypeOf(JSVM_Env env, 2954 JSVM_Value object, 2955 JSVM_Value* result); 2956 2957 /** 2958 * @brief This API set the prototype on the Object passed in. 2959 * 2960 * @param env The environment that the API is invoked under. 2961 * @param object The object on which to set the prototype. 2962 * @param prototype The prototype value. 2963 * @return Returns JSVM function's result code. 2964 * {@link JSVM_OK } If the API succeeded.\n 2965 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2966 * @since 12 2967 */ 2968 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectSetPrototypeOf(JSVM_Env env, 2969 JSVM_Value object, 2970 JSVM_Value prototype); 2971 2972 /** 2973 * @brief Creates a function with a given script as its body. 2974 * 2975 * @param env The environment that the API is invoked under. 2976 * @param funcName A string containing the function's name. Pass NULL to create an anonymous function. 2977 * @param length The length of the funcName in bytes, or JSVM_AUTO_LENGTH if it 2978 * is null-terminated. 2979 * @param argc The count of elements in the argv array. 2980 * @param argv Array of JSVM_Values representing JavaScript strings passed in as arguments to the function. 2981 * @param script A JavaScript string containing the script to use as the function's body. 2982 * @param result JSVM_Value representing the JavaScript function object for the newly 2983 * created function. 2984 * @return Returns JSVM function's result code. 2985 * {@link JSVM_OK } If the API succeeded. 2986 * {@link JSVM_INVALID_ARG } If the input parameter is invalid.\n 2987 * {@link JSVM_GENERIC_FAILURE} If the input script fails to be compiled.\n 2988 * @since 12 2989 */ 2990 JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunctionWithScript(JSVM_Env env, 2991 const char* funcName, 2992 size_t length, 2993 size_t argc, 2994 const JSVM_Value* argv, 2995 JSVM_Value script, 2996 JSVM_Value* result); 2997 2998 /** 2999 * @brief This function keep persistently save a JSVM_Script and extend its lifecycle 3000 * beyond the current scope. 3001 * 3002 * @param env The environment that the API is invoked under. 3003 * @param script A JavaScript string containing the script to be retained. 3004 * @return Returns JSVM functions result code 3005 * {@link JSVM_OK } if the API succeeded. \n 3006 * {@link JSVM_INVALID_ARG } if the script is empty or already retained. \n 3007 * @since 12 3008 */ 3009 JSVM_EXTERN JSVM_Status OH_JSVM_RetainScript(JSVM_Env env, JSVM_Script script); 3010 3011 /** 3012 * @brief This function release the script retained by OH_JSVM_RetainScript 3013 * 3014 * @param env The environment that the API is invoked under. 3015 * @param script A JavaScript string containing the script to be retained. 3016 * @return Returns JSVM functions result code 3017 * {@link JSVM_OK } if the API succeeded. \n 3018 * {@link JSVM_INVALID_ARG } if the script is empty or not retained. \n 3019 * @since 12 3020 */ 3021 JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseScript(JSVM_Env env, JSVM_Script script); 3022 3023 /** 3024 * @brief This function activates insepctor with pid and alias it. 3025 * 3026 * @param env The environment that the API is invoked under. 3027 * @param pid A process id to identify the inspector connection. 3028 * @param name An alias for the inspector that under a specific pid. 3029 * default name is jsvm if a nullptr is passed in. 3030 * @return Returns JSVM funtions result code. 3031 * Returns {@link JSVM_OK } if the function executed successfully.\n 3032 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 3033 * @since 12 3034 */ 3035 JSVM_EXTERN JSVM_Status OH_JSVM_OpenInspectorWithName(JSVM_Env env, 3036 int pid, 3037 const char* name); 3038 3039 /** 3040 * @brief Compile WebAssembly bytecode into a WebAssembly module. 3041 * If WebAssembly cache provided, deserialization will be performed. 3042 * 3043 * @param env The environment that the API is invoked under. 3044 * @param wasmBytecode WebAssembly bytecode. 3045 * @param wasmBytecodeLength WebAssembly bytecode length in byte. 3046 * @param cacheData Optional WebAssembly cache. 3047 * @param cacheDataLength Optional WebAssembly cache length in byte. 3048 * @param cacheRejected Output parameter representing whether the provided cacheData is rejected. 3049 * @param wasmModule Output parameter representing compiled WebAssembly module. 3050 * @return Returns JSVM funtions result code. 3051 * Returns {@link JSVM_OK } if the function executed successfully.\n 3052 * Returns {@link JSVM_INVALID_ARG } if any of env, wasmBytecode is NULL, or data length is invalid.\n 3053 * Returns {@link JSVM_GENERIC_FAILURE } if compile failed.\n 3054 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 3055 * Returns {@link JSVM_JIT_MODE_EXPECTED } if run in jitless mode.\n 3056 * 3057 * @since 12 3058 */ 3059 JSVM_EXTERN JSVM_Status OH_JSVM_CompileWasmModule(JSVM_Env env, 3060 const uint8_t *wasmBytecode, 3061 size_t wasmBytecodeLength, 3062 const uint8_t *cacheData, 3063 size_t cacheDataLength, 3064 bool *cacheRejected, 3065 JSVM_Value *wasmModule); 3066 3067 /** 3068 * @brief Compile the function with the specified index in the WebAssembly module 3069 * into the specified optimization level. 3070 * 3071 * @param env The environment that the API is invoked under. 3072 * @param wasmModule The WebAssembly module to which the function to compiled belongs. 3073 * @param functionIndex The index of the function to be compiled, should never be out of range. 3074 * @param optLevel Optimization level the function will be compiled with. 3075 * @return Returns JSVM funtions result code. 3076 * Returns {@link JSVM_OK } if the function executed successfully.\n 3077 * Returns {@link JSVM_INVALID_ARG } if env is NULL, or wasmModule is NULL or is not a WebAssembly module.\n 3078 * Returns {@link JSVM_GENERIC_FAILURE } if functionIndex out of range or compile failed.\n 3079 * Returns {@link JSVM_PENDING_EXCEPTION } if an exception occurs.\n 3080 * Returns {@link JSVM_JIT_MODE_EXPECTED } if run in jitless mode.\n 3081 * 3082 * @since 12 3083 */ 3084 JSVM_EXTERN JSVM_Status OH_JSVM_CompileWasmFunction(JSVM_Env env, 3085 JSVM_Value wasmModule, 3086 uint32_t functionIndex, 3087 JSVM_WasmOptLevel optLevel); 3088 3089 /** 3090 * @brief Check whether the given JSVM_Value is a WebAssembly module. 3091 * 3092 * @param env The environment that the API is invoked under. 3093 * @param value The JavaScript value to check. 3094 * @param result Whether the given value is a WebAssembly module. 3095 * @return Returns JSVM funtions result code. 3096 * Returns {@link JSVM_OK } if the function executed successfully.\n 3097 * Returns {@link JSVM_INVALID_ARG } if any of the input arguments is NULL.\n 3098 * 3099 * @since 12 3100 */ 3101 JSVM_EXTERN JSVM_Status OH_JSVM_IsWasmModuleObject(JSVM_Env env, 3102 JSVM_Value value, 3103 bool* result); 3104 3105 /** 3106 * @brief Create cache for compiled WebAssembly module. 3107 * 3108 * @param env The environment that the API is invoked under. 3109 * @param wasmModule The compiled WebAssembly module. 3110 * @param data Output parameter representing generated WebAssembly module cache. 3111 * @param length Output parameter representing byte length of generated WebAssembly module cache. 3112 * @return Returns JSVM funtions result code. 3113 * Returns {@link JSVM_OK } if the function executed successfully.\n 3114 * Returns {@link JSVM_INVALID_ARG } if any of the input arguments is NULL.\n 3115 * Returns {@link JSVM_GENERIC_FAILURE } if create wasm cache failed.\n 3116 * Returns {@link JSVM_JIT_MODE_EXPECTED } if run in jitless mode.\n 3117 * 3118 * @since 12 3119 */ 3120 JSVM_EXTERN JSVM_Status OH_JSVM_CreateWasmCache(JSVM_Env env, 3121 JSVM_Value wasmModule, 3122 const uint8_t** data, 3123 size_t* length); 3124 3125 /** 3126 * @brief Release cache data with specified cache type. 3127 * 3128 * @param env The environment that the API is invoked under. 3129 * @param cacheData The cache data to be released, double free is undefined behaviors. 3130 * @param cacheType The type of cache data. 3131 * @return Returns JSVM funtions result code. 3132 * Returns {@link JSVM_OK } if the function executed successfully.\n 3133 * Returns {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL or cacheType is illegal.\n 3134 * 3135 * @since 12 3136 */ 3137 JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseCache(JSVM_Env env, 3138 const uint8_t* cacheData, 3139 JSVM_CacheType cacheType); 3140 3141 /** 3142 * @brief This API creates an external JavaScript string value from an ISO-8859-1-encoded C 3143 * string. The native string is copied when failed to create external string. 3144 * 3145 * @param env The environment that the API is invoked under. 3146 * @param str Character buffer representing an ISO-8859-1-encoded string. 3147 * @param length The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 3148 * @param finalizeCallback Optional callback to call when the external value is being collected. 3149 * JSVM_Finalize provides more details. 3150 * @param finalizeHint Optional hint to pass to the finalize callback during collection. 3151 * @param result A JSVM_Value representing a JavaScript external string. 3152 * @param copied flag indicate whether the external string is successfully created, 3153 * true for faild to create external ones and fall back to non-external strings, false for success. 3154 * @return Returns JSVM funtions result code. 3155 * {@link JSVM_OK } if the function executed successfully.\n 3156 * {@link JSVM_INVALID_ARG } if one of env, str and copied is NULL.\n 3157 * @since 18 3158 */ 3159 JSVM_EXTERN JSVM_Status OH_JSVM_CreateExternalStringLatin1(JSVM_Env env, 3160 char* str, 3161 size_t length, 3162 JSVM_Finalize finalizeCallback, 3163 void* finalizeHint, 3164 JSVM_Value* result, 3165 bool* copied); 3166 3167 /** 3168 * @brief This API creates an external JavaScript string value from an UTF16-LE-encoded C 3169 * string. The native string is copied when failed to create external string. 3170 * 3171 * @param env The environment that the API is invoked under. 3172 * @param str Character buffer representing an UTF16-LE-encoded string. 3173 * @param length The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 3174 * @param finalizeCallback Optional callback to call when the external value is being collected. 3175 * JSVM_Finalize provides more details. 3176 * @param finalizeHint Optional hint to pass to the finalize callback during collection. 3177 * @param result A JSVM_Value representing a JavaScript external string. 3178 * @param copied flag indicate whether the external string is successfully created, 3179 * true for faild to create external ones and fall back to non-external strings, false for success. 3180 * @return Returns JSVM funtions result code. 3181 * {@link JSVM_OK } if the function executed successfully.\n 3182 * {@link JSVM_INVALID_ARG } if one of env, str and copied is NULL.\n 3183 * @since 18 3184 */ 3185 3186 JSVM_EXTERN JSVM_Status OH_JSVM_CreateExternalStringUtf16(JSVM_Env env, 3187 char16_t* str, 3188 size_t length, 3189 JSVM_Finalize finalizeCallback, 3190 void* finalizeHint, 3191 JSVM_Value* result, 3192 bool* copied); 3193 3194 /** 3195 * @brief This API creates a JavaScript private key. 3196 * 3197 * @param env The environment that the API is invoked under. 3198 * @param description Optional JSVM_Value which refers to a JavaScript string to be set as the description 3199 * for the private key. 3200 * @param result A JSVM_Data representing a JavaScript private key. 3201 * @return Returns JSVM funtions result code. 3202 * {@link JSVM_OK } if the function executed successfully.\n 3203 * {@link JSVM_INVALID_ARG } if env or result is NULL.\n 3204 * {@link JSVM_STRING_EXPECTED } if the description is not a string.\n 3205 * @since 18 3206 */ 3207 JSVM_EXTERN JSVM_Status OH_JSVM_CreatePrivate(JSVM_Env env, 3208 JSVM_Value description, 3209 JSVM_Data* result); 3210 3211 /** 3212 * @brief This API set a private property on the Object passed in. 3213 * 3214 * @param env The environment that the API is invoked under. 3215 * @param object The object on which to set the private property. 3216 * @param key The private key of the property. 3217 * @param value The private property value. 3218 * @return Returns JSVM funtions result code. 3219 * {@link JSVM_OK } if the function executed successfully.\n 3220 * {@link JSVM_INVALID_ARG } if any of the arguments is NULL or the key is not a private key.\n 3221 * {@link JSVM_OBJECT_EXPECTED } object passed in is not a real object.\n 3222 * {@link JSVM_GENERIC_FAILURE } if failed to set the private key but no exception is pending.\n 3223 * {@link JSVM_PENDING_EXCPTION } if an exception occurs.\n 3224 * @since 18 3225 */ 3226 JSVM_EXTERN JSVM_Status OH_JSVM_SetPrivate(JSVM_Env env, 3227 JSVM_Value object, 3228 JSVM_Data key, 3229 JSVM_Value value); 3230 3231 /** 3232 * @brief This API gets the requested private property from the Object passed in. 3233 * 3234 * @param env The environment that the API is invoked under. 3235 * @param object The object from which to retrieve the private property. 3236 * @param key The private key of the property. 3237 * @param result The value of the private property. 3238 * @return Returns JSVM funtions result code. 3239 * {@link JSVM_OK } if the function executed successfully.\n 3240 * {@link JSVM_INVALID_ARG } if any of the arguments is NULL or the key is not a private key.\n 3241 * {@link JSVM_OBJECT_EXPECTED } object passed in is not a real object.\n 3242 * {@link JSVM_GENERIC_FAILURE } if failed to get the private key but no exception is pending.\n 3243 * {@link JSVM_PENDING_EXCPTION } if an exception occurs.\n 3244 * @since 18 3245 */ 3246 JSVM_EXTERN JSVM_Status OH_JSVM_GetPrivate(JSVM_Env env, 3247 JSVM_Value object, 3248 JSVM_Data key, 3249 JSVM_Value *result); 3250 3251 /** 3252 * @brief This API attempts to delete the property of the private key from object. 3253 * 3254 * @param env The environment that the API is invoked under. 3255 * @param object The object to query. 3256 * @param key The private key of the property to delete. 3257 * @return Returns JSVM funtions result code. 3258 * {@link JSVM_OK } if the function executed successfully.\n 3259 * {@link JSVM_INVALID_ARG } if any of the arguments is NULL or the key is not a private key.\n 3260 * {@link JSVM_OBJECT_EXPECTED } object passed in is not a real object.\n 3261 * {@link JSVM_GENERIC_FAILURE } if failed to delete the private key but no exception is pending.\n 3262 * {@link JSVM_PENDING_EXCPTION } if an exception occurs.\n 3263 * @since 18 3264 */ 3265 JSVM_EXTERN JSVM_Status OH_JSVM_DeletePrivate(JSVM_Env env, 3266 JSVM_Value object, 3267 JSVM_Data key); 3268 3269 /** 3270 * @brief This API creates a new reference with the specified reference count to the data passed in. 3271 * 3272 * @param env The environment that the API is invoked under. 3273 * @param data The JSVM_Data for which a reference is being created. 3274 * @param initialRefcount Initial reference count for the new reference. 3275 * @param result JSVM_Ref pointing to the new reference. 3276 * @return Returns JSVM funtions result code. 3277 * {@link JSVM_OK } if the function executed successfully.\n 3278 * {@link JSVM_INVALID_ARG } if any parameter is null or the value of initialRefcount is 0.\n 3279 * @since 18 3280 */ 3281 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataReference(JSVM_Env env, 3282 JSVM_Data data, 3283 uint32_t initialRefcount, 3284 JSVM_Ref* result); 3285 3286 /** 3287 * @brief If still valid, this API returns the JSVM_Data representing the 3288 * JavaScript data associated with the JSVM_Ref. Otherwise, result will be NULL. 3289 * 3290 * @param env The environment that the API is invoked under. 3291 * @param ref The JSVM_Ref for which the corresponding value is being requested. 3292 * @param result The JSVM_Data referenced by the JSVM_Ref. 3293 * @return Returns JSVM funtions result code. 3294 * {@link JSVM_OK } if the function executed successfully.\n 3295 * {@link JSVM_INVALID_ARG } if any parameter is null or the ref is not a reference to JSVM_Data.\n 3296 * 3297 * @since 18 3298 */ 3299 JSVM_EXTERN JSVM_Status OH_JSVM_GetReferenceData(JSVM_Env env, 3300 JSVM_Ref ref, 3301 JSVM_Data* result); 3302 3303 /** 3304 * @brief Check whether the given JSVM_Value is a BigInt Object. 3305 * 3306 * @param env The environment that the API is invoked under. 3307 * @param value The JavaScript value to check. 3308 * @param result Whether the given value is a BigInt Object. 3309 * @return Returns JSVM funtions result code. 3310 * {@link JSVM_OK } if the function executed successfully.\n 3311 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3312 * 3313 * @since 18 3314 */ 3315 JSVM_EXTERN JSVM_Status OH_JSVM_IsBigIntObject(JSVM_Env env, 3316 JSVM_Value value, 3317 bool* result); 3318 3319 /** 3320 * @brief Check whether the given JSVM_Value is a Boolean Object. 3321 * 3322 * @param env The environment that the API is invoked under. 3323 * @param value The JavaScript value to check. 3324 * @param result Whether the given value is a Boolean Object. 3325 * @return Returns JSVM funtions result code. 3326 * {@link JSVM_OK } if the function executed successfully.\n 3327 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3328 * 3329 * @since 18 3330 */ 3331 JSVM_EXTERN JSVM_Status OH_JSVM_IsBooleanObject(JSVM_Env env, 3332 JSVM_Value value, 3333 bool* result); 3334 3335 /** 3336 * @brief Check whether the given JSVM_Value is a String Object. 3337 * 3338 * @param env The environment that the API is invoked under. 3339 * @param value The JavaScript value to check. 3340 * @param result Whether the given value is a String Object. 3341 * @return Returns JSVM funtions result code. 3342 * {@link JSVM_OK } if the function executed successfully.\n 3343 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3344 * 3345 * @since 18 3346 */ 3347 JSVM_EXTERN JSVM_Status OH_JSVM_IsStringObject(JSVM_Env env, 3348 JSVM_Value value, 3349 bool* result); 3350 3351 /** 3352 * @brief Check whether the given JSVM_Value is a Number Object. 3353 * 3354 * @param env The environment that the API is invoked under. 3355 * @param value The JavaScript value to check. 3356 * @param result Whether the given value is a Number Object. 3357 * @return Returns JSVM funtions result code. 3358 * {@link JSVM_OK } if the function executed successfully.\n 3359 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3360 * 3361 * @since 18 3362 */ 3363 JSVM_EXTERN JSVM_Status OH_JSVM_IsNumberObject(JSVM_Env env, 3364 JSVM_Value value, 3365 bool* result); 3366 3367 /** 3368 * @brief Check whether the given JSVM_Value is a Symbol Object. 3369 * 3370 * @param env The environment that the API is invoked under. 3371 * @param value The JavaScript value to check. 3372 * @param result Whether the given value is a Symbol Object. 3373 * @return Returns JSVM funtions result code. 3374 * {@link JSVM_OK } if the function executed successfully.\n 3375 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3376 * 3377 * @since 18 3378 */ 3379 JSVM_EXTERN JSVM_Status OH_JSVM_IsSymbolObject(JSVM_Env env, 3380 JSVM_Value value, 3381 bool* result); 3382 3383 /** 3384 * @brief This API returns the Symbol.asyncIterator of Well-Known Symbols. 3385 * 3386 * @param env The environment that the API is invoked under. 3387 * @param result The Symbol.asyncIterator of Well-Known Symbols. 3388 * @return Returns JSVM funtions result code. 3389 * {@link JSVM_OK } if the function executed successfully.\n 3390 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3391 * 3392 * @since 18 3393 */ 3394 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolAsyncIterator(JSVM_Env env, JSVM_Value* result); 3395 3396 /** 3397 * @brief This API returns the Symbol.hasInstance of Well-Known Symbols. 3398 * 3399 * @param env The environment that the API is invoked under. 3400 * @param result The Symbol.hasInstance of Well-Known Symbols. 3401 * @return Returns JSVM funtions result code. 3402 * {@link JSVM_OK } if the function executed successfully.\n 3403 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3404 * 3405 * @since 18 3406 */ 3407 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolHasInstance(JSVM_Env env, JSVM_Value* result); 3408 3409 /** 3410 * @brief This API returns the Symbol.isConcatSpreadable of Well-Known Symbols 3411 * 3412 * @param env The environment that the API is invoked under. 3413 * @param result The Symbol.isConcatSpreadable of Well-Known Symbols. 3414 * @return Returns JSVM funtions result code. 3415 * {@link JSVM_OK } if the function executed successfully.\n 3416 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3417 * 3418 * @since 18 3419 */ 3420 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolIsConcatSpreadable(JSVM_Env env, JSVM_Value* result); 3421 3422 /** 3423 * @brief This API returns the Symbol.match of Well-Known Symbols 3424 * 3425 * @param env The environment that the API is invoked under. 3426 * @param result The Symbol.match of Well-Known Symbols. 3427 * @return Returns JSVM funtions result code. 3428 * {@link JSVM_OK } if the function executed successfully.\n 3429 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3430 * 3431 * @since 18 3432 */ 3433 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolMatch(JSVM_Env env, JSVM_Value* result); 3434 3435 /** 3436 * @brief This API returns the Symbol.replace of Well-Known Symbols 3437 * 3438 * @param env The environment that the API is invoked under. 3439 * @param result The Symbol.replace of Well-Known Symbols. 3440 * @return Returns JSVM funtions result code. 3441 * {@link JSVM_OK } if the function executed successfully.\n 3442 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3443 * 3444 * @since 18 3445 */ 3446 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolReplace(JSVM_Env env, JSVM_Value* result); 3447 3448 /** 3449 * @brief This API returns the Symbol.search of Well-Known Symbols 3450 * 3451 * @param env The environment that the API is invoked under. 3452 * @param result The Symbol.search of Well-Known Symbols. 3453 * @return Returns JSVM funtions result code. 3454 * {@link JSVM_OK } if the function executed successfully.\n 3455 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3456 * 3457 * @since 18 3458 */ 3459 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolSearch(JSVM_Env env, JSVM_Value* result); 3460 3461 /** 3462 * @brief This API returns the Symbol.split of Well-Known Symbols 3463 * 3464 * @param env The environment that the API is invoked under. 3465 * @param result The Symbol.split of Well-Known Symbols. 3466 * @return Returns JSVM funtions result code. 3467 * {@link JSVM_OK } if the function executed successfully.\n 3468 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3469 * 3470 * @since 18 3471 */ 3472 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolSplit(JSVM_Env env, JSVM_Value* result); 3473 3474 /** 3475 * @brief This API returns the Symbol.toPrimitive of Well-Known Symbols 3476 * 3477 * @param env The environment that the API is invoked under. 3478 * @param result The Symbol.toPrimitive of Well-Known Symbols. 3479 * @return Returns JSVM funtions result code. 3480 * {@link JSVM_OK } if the function executed successfully.\n 3481 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3482 * 3483 * @since 18 3484 */ 3485 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolToPrimitive(JSVM_Env env, JSVM_Value* result); 3486 3487 /** 3488 * @brief This API returns the Symbol.unscopables of Well-Known Symbols 3489 * 3490 * @param env The environment that the API is invoked under. 3491 * @param result The Symbol.unscopables of Well-Known Symbols. 3492 * @return Returns JSVM funtions result code. 3493 * {@link JSVM_OK } if the function executed successfully.\n 3494 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3495 * 3496 * @since 18 3497 */ 3498 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolUnscopables(JSVM_Env env, JSVM_Value* result); 3499 3500 /** 3501 * @brief This API returns the Symbol.toStringTag of Well-Known Symbols 3502 * 3503 * @param env The environment that the API is invoked under. 3504 * @param result The Symbol.toStringTag of Well-Known Symbols. 3505 * @return Returns JSVM funtions result code. 3506 * {@link JSVM_OK } if the function executed successfully.\n 3507 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3508 * 3509 * @since 18 3510 */ 3511 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolToStringTag(JSVM_Env env, JSVM_Value* result); 3512 3513 /** 3514 * @brief This API returns the Symbol.iterator of Well-Known Symbols 3515 * 3516 * @param env The environment that the API is invoked under. 3517 * @param result The Symbol.iterator of Well-Known Symbols. 3518 * @return Returns JSVM funtions result code. 3519 * {@link JSVM_OK } if the function executed successfully.\n 3520 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL.\n 3521 * 3522 * @since 18 3523 */ 3524 JSVM_EXTERN JSVM_Status OH_JSVM_GetSymbolIterator(JSVM_Env env, JSVM_Value* result); 3525 3526 /** 3527 * @brief Trace start with specified categories for all JSVM VM.(Non-thread-safe) 3528 * 3529 * @param count The count of trace categories. 3530 * @param categories Select internal trace events for tracing by categories. 3531 * @param tag User-defined tag of trace data. 3532 * @param eventsCount Number of trace events. 3533 * @return Returns JSVM funtions result code. 3534 * {@link JSVM_OK } if the function executed successfully.\n 3535 * {@link JSVM_INVALID_ARG } if categories or count is illegal.\n 3536 * 3537 * @since 18 3538 */ 3539 JSVM_EXTERN JSVM_Status OH_JSVM_TraceStart(size_t count, const JSVM_TraceCategory* categories, 3540 const char* tag, size_t eventsCount); 3541 3542 /** 3543 * @brief Trace stop for specified categories for all JSVM VM.(Non-thread-safe) 3544 * 3545 * @param stream The output stream callback for receiving the data. 3546 * @param streamData Data passed to the stream callback. 3547 * @return Returns JSVM funtions result code. 3548 * {@link JSVM_OK } if the function executed successfully.\n 3549 * {@link JSVM_INVALID_ARG } if stream or streamData is NULL\n 3550 * 3551 * @since 18 3552 */ 3553 JSVM_EXTERN JSVM_Status OH_JSVM_TraceStop(JSVM_OutputStream stream, void* streamData); 3554 3555 /** 3556 * @brief Set Handler For OOM Error. If this function is invoked repeatedly, 3557 * only the last time takes effect. When handler is null, the previous setting is canceled. 3558 * 3559 * @param vm The environment that the API is invoked under. 3560 * @param handler The handler for OOM Error. 3561 * @return Returns JSVM funtions result code. 3562 * {@link JSVM_OK } if the function executed successfully.\n 3563 * {@link JSVM_INVALID_ARG } if vm is NULL.\n 3564 * 3565 * @since 18 3566 */ 3567 JSVM_EXTERN JSVM_Status OH_JSVM_SetHandlerForOOMError(JSVM_VM vm, 3568 JSVM_HandlerForOOMError handler); 3569 3570 /** 3571 * @brief This API is used to enable/disable the given debug option for a certain JSVM_Env. 3572 * 3573 * @param env The environment that the API is invoked under. 3574 * @param debugOption The debug option to be changed. 3575 * @param isEnabled Whether to enable or disable the debug option. 3576 * @return Returns JSVM funtions result code. 3577 * {@link JSVM_OK } if the function executed successfully.\n 3578 * {@link JSVM_INVALID_ARG } if env is NULL.\n 3579 * 3580 * @since 20 3581 */ 3582 JSVM_EXTERN JSVM_Status OH_JSVM_SetDebugOption(JSVM_Env env, JSVM_DebugOption debugOption, bool isEnabled); 3583 3584 /** 3585 * @brief Set Handler For Fatal Error. If this function is invoked repeatedly, 3586 * only the last time takes effect. When handler is null, the previous setting is canceled. 3587 * 3588 * @param vm The environment that the API is invoked under. 3589 * @param handler The handler for Fatal Error. 3590 * @return Returns JSVM funtions result code. 3591 * {@link JSVM_OK } if the function executed successfully.\n 3592 * {@link JSVM_INVALID_ARG } if vm is NULL.\n 3593 * 3594 * @since 18 3595 */ 3596 JSVM_EXTERN JSVM_Status OH_JSVM_SetHandlerForFatalError(JSVM_VM vm, 3597 JSVM_HandlerForFatalError handler); 3598 3599 /** 3600 * @brief Set Handler For Promise Reject. If this function is invoked repeatedly, 3601 * only the last time takes effect. When handler is null, the previous setting is canceled. 3602 * 3603 * @param vm The environment that the API is invoked under. 3604 * @param handler The handler for Promise Reject. 3605 * @return Returns JSVM funtions result code. 3606 * {@link JSVM_OK } if the function executed successfully.\n 3607 * {@link JSVM_INVALID_ARG } if vm is NULL.\n 3608 * 3609 * @since 18 3610 */ 3611 JSVM_EXTERN JSVM_Status OH_JSVM_SetHandlerForPromiseReject(JSVM_VM vm, 3612 JSVM_HandlerForPromiseReject handler); 3613 3614 /** 3615 * @brief When wrapping a C++ class, the C++ constructor callback passed via constructor 3616 * should be a static method on the class that calls the actual class constructor, then 3617 * wraps the new C++ instance in a JavaScript object according to the different Options 3618 * passed in, and returns the wrapper object. 3619 * 3620 * @param env The environment that the API is invoked under. 3621 * @param utf8name Name of the JavaScript constructor function. For clarity, it is 3622 * recommended to use the C++ class name when wrapping a C++ class. 3623 * @param length The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 3624 * is null-terminated. 3625 * @param constructor Struct include callback function that handles constructing instances of the class. 3626 * When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback 3627 * signature. A C++ class constructor cannot be used. 3628 * Include Optional data to be passed to the constructor callback as the data 3629 * property of the callback info. JSVM_Callback provides more details. 3630 * @param propertyCount Number of items in the properties array argument. 3631 * @param properties Array of property descriptors describing static and instance data 3632 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 3633 * @param parentClass The parent-class of the currently defined class. 3634 * @param option_count Number of items in an option array argument. 3635 * @param options DefineClass options to be passed. 3636 * @param result A JSVM_Value representing the constructor function for the class. 3637 * @return Returns JSVM functions result code. 3638 * {@link JSVM_OK } if the function executed successfully. \n 3639 * {@link JSVM_INVALID_ARG } if any of the pointer arguments is NULL. \n 3640 * {@link JSVM_GENERIC_FAILURE} if the input utf8name | constructor | properties is invalid. \n 3641 * @since 18 3642 */ 3643 JSVM_EXTERN JSVM_Status OH_JSVM_DefineClassWithOptions(JSVM_Env env, 3644 const char* utf8name, 3645 size_t length, 3646 JSVM_Callback constructor, 3647 size_t propertyCount, 3648 const JSVM_PropertyDescriptor* properties, 3649 JSVM_Value parentClass, 3650 size_t option_count, 3651 JSVM_DefineClassOptions options[], 3652 JSVM_Value* result); 3653 3654 /** 3655 * @brief Add VM GC Callback. 3656 * 3657 * @param vm The environment that the API is invoked under. 3658 * @param triggerTime The timing of GC callback trigger. 3659 * @param handler When Trigger gc, the callback function will be called. 3660 * @param gcType The type of gc. 3661 * @param userData The native pointer data. 3662 * @return Returns JSVM funtions result code. 3663 * {@link JSVM_OK } if the function executed successfully.\n 3664 * {@link JSVM_INVALID_ARG } if the vm or the handler is NULL or the handler has been added before.\n 3665 * 3666 * @since 18 3667 */ 3668 JSVM_EXTERN JSVM_Status OH_JSVM_AddHandlerForGC(JSVM_VM vm, 3669 JSVM_CBTriggerTimeForGC triggerTime, 3670 JSVM_HandlerForGC handler, 3671 JSVM_GCType gcType, 3672 void* userData); 3673 3674 /** 3675 * @brief Remove VM GC Callback. 3676 * 3677 * @param vm The environment that the API is invoked under. 3678 * @param triggerTime The timing of GC callback trigger. 3679 * @param handler When Trigger gc, the callback function will be called. 3680 * @param userData The native pointer data. 3681 * @return Returns JSVM funtions result code. 3682 * {@link JSVM_OK } if the function executed successfully.\n 3683 * {@link JSVM_INVALID_ARG } if the vm or the handler is NULL, or the handler has been removed, 3684 * or the handler has never been added.\n 3685 * 3686 * @since 18 3687 */ 3688 JSVM_EXTERN JSVM_Status OH_JSVM_RemoveHandlerForGC(JSVM_VM vm, 3689 JSVM_CBTriggerTimeForGC triggerTime, 3690 JSVM_HandlerForGC handler, 3691 void* userData); 3692 EXTERN_C_END 3693 /** @} */ 3694 #endif /* ARK_RUNTIME_JSVM_JSVM_H */ 3695 3696