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