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 * @brief This function creates code cache for the compiled script. 268 * 269 * @param env: The environment that the JSVM-API call is invoked under. 270 * @param script: A compiled script to create code cache for. 271 * @param data: The data of the code cache. 272 * @param length: The length of the code cache data. 273 * @return Returns JSVM_OK if the API succeeded. 274 * @since 11 275 */ 276 JSVM_EXTERN JSVM_Status OH_JSVM_CreateCodeCache(JSVM_Env env, 277 JSVM_Script script, 278 const uint8_t** data, 279 size_t* length); 280 281 /** 282 * @brief This function executes a string of JavaScript code and returns its result with the following caveats: 283 * Unlike eval, this function does not allow the script to access the current lexical scope, and therefore also 284 * does not allow to access the module scope, meaning that pseudo-globals such as require will not be available. 285 * The script can access the global scope. Function and var declarations in the script will be added to the 286 * global object. Variable declarations made using let and const will be visible globally, but will not be added 287 * to the global object.The value of this is global within the script. 288 * 289 * @param env: The environment that the API is invoked under. 290 * @param script: A JavaScript string containing the script to execute. 291 * @param result: The value resulting from having executed the script. 292 * @since 11 293 */ 294 JSVM_EXTERN JSVM_Status OH_JSVM_RunScript(JSVM_Env env, 295 JSVM_Script script, 296 JSVM_Value* result); 297 298 /** 299 * @brief This API associates data with the currently running JSVM environment. data can later be retrieved 300 * using OH_JSVM_GetInstanceData(). 301 * 302 * @param env: The environment that the JSVM-API call is invoked under. 303 * @param data: The data item to make available to bindings of this instance. 304 * @param finalizeCb: The function to call when the environment is being torn down. The function receives 305 * data so that it might free it. JSVM_Finalize provides more details. 306 * @param finalizeHint: Optional hint to pass to the finalize callback during collection. 307 * @return Returns JSVM_OK if the API succeeded. 308 * @since 11 309 */ 310 JSVM_EXTERN JSVM_Status OH_JSVM_SetInstanceData(JSVM_Env env, 311 void* data, 312 JSVM_Finalize finalizeCb, 313 void* finalizeHint); 314 315 /** 316 * @brief This API retrieves data that was previously associated with the currently running JSVM environment 317 * via OH_JSVM_SetInstanceData(). If no data is set, the call will succeed and data will be set to NULL. 318 * 319 * @param env: The environment that the JSVM-API call is invoked under. 320 * @param data: The data item that was previously associated with the currently running JSVM environment by 321 * a call to OH_JSVM_SetInstanceData(). 322 * @return Returns JSVM_OK if the API succeeded. 323 * @since 11 324 */ 325 JSVM_EXTERN JSVM_Status OH_JSVM_GetInstanceData(JSVM_Env env, 326 void** data); 327 328 /** 329 * @brief This API retrieves a JSVM_ExtendedErrorInfo structure with information about the last error that 330 * occurred. 331 * 332 * @param env: The environment that the JSVM-API call is invoked under. 333 * @param result: The JSVM_ExtendedErrorInfo structure with more information about the error. 334 * @return Returns JSVM_OK if the API succeeded. 335 * @since 11 336 */ 337 JSVM_EXTERN JSVM_Status OH_JSVM_GetLastErrorInfo(JSVM_Env env, 338 const JSVM_ExtendedErrorInfo** result); 339 340 /** 341 * @brief This API throws the JavaScript value provided. 342 * 343 * @param env: The environment that the API is invoked under. 344 * @param error: The JavaScript value to be thrown. 345 * @return Returns JSVM_OK if the API succeeded. 346 * @since 11 347 */ 348 JSVM_EXTERN JSVM_Status OH_JSVM_Throw(JSVM_Env env, 349 JSVM_Value error); 350 351 /** 352 * @brief This API throws a JavaScript Error with the text provided. 353 * 354 * @param env: The environment that the API is invoked under. 355 * @param code: Optional error code to be set on the error. 356 * @param msg: C string representing the text to be associated with the error. 357 * @return Returns JSVM_OK if the API succeeded. 358 * @since 11 359 */ 360 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowError(JSVM_Env env, 361 const char* code, 362 const char* msg); 363 364 /** 365 * @brief This API throws a JavaScript TypeError with the text provided. 366 * 367 * @param env: The environment that the API is invoked under. 368 * @param code: Optional error code to be set on the error. 369 * @param msg: C string representing the text to be associated with the error. 370 * @return Returns JSVM_OK if the API succeeded. 371 * @since 11 372 */ 373 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowTypeError(JSVM_Env env, 374 const char* code, 375 const char* msg); 376 377 /** 378 * @brief This API throws a JavaScript RangeError with the text provided. 379 * 380 * @param env: The environment that the API is invoked under. 381 * @param code: Optional error code to be set on the error. 382 * @param msg: C string representing the text to be associated with the error. 383 * @return Returns JSVM_OK if the API succeeded. 384 * @since 11 385 */ 386 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowRangeError(JSVM_Env env, 387 const char* code, 388 const char* msg); 389 390 /** 391 * @brief This API throws a JavaScript SyntaxError with the text provided. 392 * 393 * @param env: The environment that the API is invoked under. 394 * @param code: Optional error code to be set on the error. 395 * @param msg: C string representing the text to be associated with the error. 396 * @return Returns JSVM_OK if the API succeeded. 397 * @since 11 398 */ 399 JSVM_EXTERN JSVM_Status OH_JSVM_ThrowSyntaxError(JSVM_Env env, 400 const char* code, 401 const char* msg); 402 403 /** 404 * @brief This API queries a JSVM_Value to check if it represents an error object. 405 * 406 * @param env: The environment that the API is invoked under. 407 * @param value: The JSVM_Value to be checked. 408 * @param result: Boolean value that is set to true if JSVM_Value represents an error, 409 * false otherwise. 410 * @return Returns JSVM_OK if the API succeeded. 411 * @since 11 412 */ 413 JSVM_EXTERN JSVM_Status OH_JSVM_IsError(JSVM_Env env, 414 JSVM_Value value, 415 bool* result); 416 417 /** 418 * @brief This API returns a JavaScript Error with the text provided. 419 * 420 * @param env: The environment that the API is invoked under. 421 * @param code: Optional JSVM_Value with the string for the error code to be associated with the error. 422 * @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error. 423 * @param result: JSVM_Value representing the error created. 424 * @return Returns JSVM_OK if the API succeeded. 425 * @since 11 426 */ 427 JSVM_EXTERN JSVM_Status OH_JSVM_CreateError(JSVM_Env env, 428 JSVM_Value code, 429 JSVM_Value msg, 430 JSVM_Value* result); 431 432 /** 433 * @brief This API returns a JavaScript TypeError with the text provided. 434 * 435 * @param env: The environment that the API is invoked under. 436 * @param code: Optional JSVM_Value with the string for the error code to be associated with the error. 437 * @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error. 438 * @param result: JSVM_Value representing the error created. 439 * @return Returns JSVM_OK if the API succeeded. 440 * @since 11 441 */ 442 JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypeError(JSVM_Env env, 443 JSVM_Value code, 444 JSVM_Value msg, 445 JSVM_Value* result); 446 447 /** 448 * @brief This API returns a JavaScript RangeError with the text provided. 449 * 450 * @param env: The environment that the API is invoked under. 451 * @param code: Optional JSVM_Value with the string for the error code to be associated with the error. 452 * @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error. 453 * @param result: JSVM_Value representing the error created. 454 * @return Returns JSVM_OK if the API succeeded. 455 * @since 11 456 */ 457 JSVM_EXTERN JSVM_Status OH_JSVM_CreateRangeError(JSVM_Env env, 458 JSVM_Value code, 459 JSVM_Value msg, 460 JSVM_Value* result); 461 462 /** 463 * @brief This API returns a JavaScript SyntaxError with the text provided. 464 * 465 * @param env: The environment that the API is invoked under. 466 * @param code: Optional JSVM_Value with the string for the error code to be associated with the error. 467 * @param msg: JSVM_Value that references a JavaScript string to be used as the message for the Error. 468 * @param result: JSVM_Value representing the error created. 469 * @return Returns JSVM_OK if the API succeeded. 470 * @since 11 471 */ 472 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSyntaxError(JSVM_Env env, 473 JSVM_Value code, 474 JSVM_Value msg, 475 JSVM_Value* result); 476 477 /** 478 * @brief This API returns a JavaScript exception if one is pending, NULL otherwise. 479 * 480 * @param env: The environment that the API is invoked under. 481 * @param result: The exception if one is pending, NULL otherwise. 482 * @return Returns JSVM_OK if the API succeeded. 483 * @since 11 484 */ 485 JSVM_EXTERN JSVM_Status OH_JSVM_GetAndClearLastException(JSVM_Env env, 486 JSVM_Value* result); 487 488 /** 489 * @brief This API returns true if an exception is pending, false otherwise. 490 * 491 * @param env: The environment that the API is invoked under. 492 * @param result: Boolean value that is set to true if an exception is pending. 493 * @return Returns JSVM_OK if the API succeeded. 494 * @since 11 495 */ 496 JSVM_EXTERN JSVM_Status OH_JSVM_IsExceptionPending(JSVM_Env env, 497 bool* result); 498 499 /** 500 * @brief This API opens a new scope. 501 * 502 * @param env: The environment that the API is invoked under. 503 * @param result: JSVM_Value representing the new scope. 504 * @return Returns JSVM_OK if the API succeeded. 505 * @since 11 506 */ 507 JSVM_EXTERN JSVM_Status OH_JSVM_OpenHandleScope(JSVM_Env env, 508 JSVM_HandleScope* result); 509 510 /** 511 * @brief This API closes the scope passed in. Scopes must be closed in the reverse 512 * order from which they were created. 513 * 514 * @param env: The environment that the API is invoked under. 515 * @param scope: JSVM_Value representing the scope to be closed. 516 * @return Returns JSVM_OK if the API succeeded. 517 * @since 11 518 */ 519 JSVM_EXTERN JSVM_Status OH_JSVM_CloseHandleScope(JSVM_Env env, 520 JSVM_HandleScope scope); 521 522 /** 523 * @brief This API opens a new scope from which one object can be promoted to the outer scope. 524 * 525 * @param env: The environment that the API is invoked under. 526 * @param result: JSVM_Value representing the new scope. 527 * @return Returns JSVM_OK if the API succeeded. 528 * @since 11 529 */ 530 JSVM_EXTERN JSVM_Status OH_JSVM_OpenEscapableHandleScope(JSVM_Env env, 531 JSVM_EscapableHandleScope* result); 532 533 /** 534 * @brief This API closes the scope passed in. Scopes must be closed in the reverse order 535 * from which they were created. 536 * 537 * @param env: The environment that the API is invoked under. 538 * @param scope: JSVM_Value representing the scope to be closed. 539 * @return Returns JSVM_OK if the API succeeded. 540 * @since 11 541 */ 542 JSVM_EXTERN JSVM_Status OH_JSVM_CloseEscapableHandleScope(JSVM_Env env, 543 JSVM_EscapableHandleScope scope); 544 545 /** 546 * @brief This API promotes the handle to the JavaScript object so that it is valid for the lifetime 547 * of the outer scope. It can only be called once per scope. If it is called more than once an error 548 * will be returned. 549 * 550 * @param env: The environment that the API is invoked under. 551 * @param scope: JSVM_Value representing the current scope. 552 * @param escapee: JSVM_Value representing the JavaScript Object to be escaped. 553 * @param result: JSVM_Value representing the handle to the escaped Object in the outer scope. 554 * @return Returns JSVM_OK if the API succeeded. 555 * @since 11 556 */ 557 JSVM_EXTERN JSVM_Status OH_JSVM_EscapeHandle(JSVM_Env env, 558 JSVM_EscapableHandleScope scope, 559 JSVM_Value escapee, 560 JSVM_Value* result); 561 562 /** 563 * @brief This API creates a new reference with the specified reference count to the value passed in. 564 * 565 * @param env: The environment that the API is invoked under. 566 * @param value: The JSVM_Value for which a reference is being created. 567 * @param initialRefcount: Initial reference count for the new reference. 568 * @param result: JSVM_Ref pointing to the new reference. 569 * @return Returns JSVM_OK if the API succeeded. 570 * @since 11 571 */ 572 JSVM_EXTERN JSVM_Status OH_JSVM_CreateReference(JSVM_Env env, 573 JSVM_Value value, 574 uint32_t initialRefcount, 575 JSVM_Ref* result); 576 577 /** 578 * @brief his API deletes the reference passed in. 579 * 580 * @param env: The environment that the API is invoked under. 581 * @param ref: JSVM_Ref to be deleted. 582 * @return Returns JSVM_OK if the API succeeded. 583 * @since 11 584 */ 585 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteReference(JSVM_Env env, 586 JSVM_Ref ref); 587 588 /** 589 * @brief his API increments the reference count for the reference passed in and 590 * returns the resulting reference count. 591 * 592 * @param env: The environment that the API is invoked under. 593 * @param ref: JSVM_Ref for which the reference count will be incremented. 594 * @param result: The new reference count. 595 * @return Returns JSVM_OK if the API succeeded. 596 * @since 11 597 */ 598 JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceRef(JSVM_Env env, 599 JSVM_Ref ref, 600 uint32_t* result); 601 602 /** 603 * @brief This API decrements the reference count for the reference passed in and 604 * returns the resulting reference count. 605 * 606 * @param env: The environment that the API is invoked under. 607 * @param ref: JSVM_Ref for which the reference count will be decremented. 608 * @param result: The new reference count. 609 * @return Returns JSVM_OK if the API succeeded. 610 * @since 11 611 */ 612 JSVM_EXTERN JSVM_Status OH_JSVM_ReferenceUnref(JSVM_Env env, 613 JSVM_Ref ref, 614 uint32_t* result); 615 616 /** 617 * @brief If still valid, this API returns the JSVM_Value representing the 618 * JavaScript value associated with the JSVM_Ref. Otherwise, result will be NULL. 619 * 620 * @param env: The environment that the API is invoked under. 621 * @param ref: The JSVM_Ref for which the corresponding value is being requested. 622 * @param result: The JSVM_Value referenced by the JSVM_Ref. 623 * @return Returns JSVM_OK if the API succeeded. 624 * @since 11 625 */ 626 JSVM_EXTERN JSVM_Status OH_JSVM_GetReferenceValue(JSVM_Env env, 627 JSVM_Ref ref, 628 JSVM_Value* result); 629 630 /** 631 * @brief This API returns a JSVM-API value corresponding to a JavaScript Array type. 632 * 633 * @param env: The environment that the API is invoked under. 634 * @param result: A JSVM_Value representing a JavaScript Array. 635 * @return Returns JSVM_OK if the API succeeded. 636 * @since 11 637 */ 638 JSVM_EXTERN JSVM_Status OH_JSVM_CreateArray(JSVM_Env env, 639 JSVM_Value* result); 640 641 642 /** 643 * @brief This API returns a JSVM-API value corresponding to a JavaScript Array type. The Array's length property 644 * is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated 645 * by the VM when the array is created. That behavior is left to the underlying VM implementation. 646 * 647 * @param env: The environment that the API is invoked under. 648 * @param length: The initial length of the Array. 649 * @param result: A JSVM_Value representing a JavaScript Array. 650 * @return Returns JSVM_OK if the API succeeded. 651 * @since 11 652 */ 653 JSVM_EXTERN JSVM_Status OH_JSVM_CreateArrayWithLength(JSVM_Env env, 654 size_t length, 655 JSVM_Value* result); 656 657 /** 658 * @brief This API returns a JSVM-API value corresponding to a JavaScript ArrayBuffer. ArrayBuffers are used to 659 * represent fixed-length binary data buffers. They are normally used as a backing-buffer for TypedArray objects. 660 * The ArrayBuffer allocated will have an underlying byte buffer whose size is determined by the length parameter 661 * that's passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to 662 * directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this 663 * buffer from JavaScript, a typed array or DataView object would need to be created. 664 * 665 * @param env: The environment that the API is invoked under. 666 * @param byteLength: The length in bytes of the array buffer to create. 667 * @param data: Pointer to the underlying byte buffer of the ArrayBuffer.data can optionally be ignored by passing NULL. 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_CreateArraybuffer(JSVM_Env env, 673 size_t byteLength, 674 void** data, 675 JSVM_Value* result); 676 677 /** 678 * @brief This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification. 679 * This API allocates a JavaScript Date object. 680 * 681 * @param env: The environment that the API is invoked under. 682 * @param time: ECMAScript time value in milliseconds since 01 January, 1970 UTC. 683 * @param result: A JSVM_Value representing a JavaScript Date. 684 * @return Returns JSVM_OK if the API succeeded. 685 * @since 11 686 */ 687 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDate(JSVM_Env env, 688 double time, 689 JSVM_Value* result); 690 691 /** 692 * @brief This API allocates a JavaScript value with external data attached to it. This is used to pass external 693 * data through JavaScript code, so it can be retrieved later by native code using OH_JSVM_GetValueExternal. 694 * The API adds a JSVM_Finalize callback which will be called when the JavaScript object just created has been garbage 695 * collected.The created value is not an object, and therefore does not support additional properties. It is considered 696 * a distinct value type: calling OH_JSVM_Typeof() with an external value yields JSVM_EXTERNAL. 697 * 698 * @param env: The environment that the API is invoked under. 699 * @param data: Raw pointer to the external data. 700 * @param finalizeCb: Optional callback to call when the external value is being collected. JSVM_Finalize provides 701 * more details. 702 * @param finalizeHint: Optional hint to pass to the finalize callback during collection. 703 * @param result: A JSVM_Value representing an external value. 704 * @return Returns JSVM_OK if the API succeeded. 705 * @since 11 706 */ 707 JSVM_EXTERN JSVM_Status OH_JSVM_CreateExternal(JSVM_Env env, 708 void* data, 709 JSVM_Finalize finalizeCb, 710 void* finalizeHint, 711 JSVM_Value* result); 712 713 /** 714 * @brief This API allocates a default JavaScript Object. It is the equivalent of doing new Object() in JavaScript. 715 * 716 * @param env: The environment that the API is invoked under. 717 * @param result: A JSVM_Value representing a JavaScript Object. 718 * @return Returns JSVM_OK if the API succeeded. 719 * @since 11 720 */ 721 JSVM_EXTERN JSVM_Status OH_JSVM_CreateObject(JSVM_Env env, 722 JSVM_Value* result); 723 724 /** 725 * @brief This API creates a JavaScript symbol value from a UTF8-encoded C string. 726 * 727 * @param env: The environment that the API is invoked under. 728 * @param description: Optional JSVM_Value which refers to a JavaScript string to be set as the description 729 * for the symbol. 730 * @param result: A JSVM_Value representing a JavaScript symbol. 731 * @return Returns JSVM_OK if the API succeeded. 732 * @since 11 733 */ 734 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSymbol(JSVM_Env env, 735 JSVM_Value description, 736 JSVM_Value* result); 737 738 /** 739 * @brief This API searches in the global registry for an existing symbol with the given description. 740 * If the symbol already exists it will be returned, otherwise a new symbol will be created in the registry. 741 * 742 * @param env: The environment that the API is invoked under. 743 * @param utf8description: UTF-8 C string representing the text to be used as the description for the symbol. 744 * @param length: The length of the description string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 745 * @param result: A JSVM_Value representing a JavaScript symbol. 746 * @return Returns JSVM_OK if the API succeeded. 747 * @since 11 748 */ 749 JSVM_EXTERN JSVM_Status OH_JSVM_SymbolFor(JSVM_Env env, 750 const char* utf8description, 751 size_t length, 752 JSVM_Value* result); 753 754 /** 755 * @brief This API creates a JavaScript TypedArray object over an existing ArrayBuffer. TypedArray 756 * objects provide an array-like view over an underlying data buffer where each element has the 757 * same underlying binary scalar datatype.It's required that (length * size_of_element) + byte_offset should 758 * be <= the size in bytes of the array passed in. If not, a RangeError exception is raised. 759 * 760 * @param env: The environment that the API is invoked under. 761 * @param type: Scalar datatype of the elements within the TypedArray. 762 * @param length: Number of elements in the TypedArray. 763 * @param arraybuffer: ArrayBuffer underlying the typed array. 764 * @param byteOffset: The byte offset within the ArrayBuffer from which to start projecting the TypedArray. 765 * @param result: A JSVM_Value representing a JavaScript TypedArray 766 * @return Returns JSVM_OK if the API succeeded. 767 * @since 11 768 */ 769 JSVM_EXTERN JSVM_Status OH_JSVM_CreateTypedarray(JSVM_Env env, 770 JSVM_TypedarrayType type, 771 size_t length, 772 JSVM_Value arraybuffer, 773 size_t byteOffset, 774 JSVM_Value* result); 775 776 /** 777 * @brief This API creates a JavaScript DataView object over an existing ArrayBuffer. DataView 778 * objects provide an array-like view over an underlying data buffer, but one which allows items 779 * of different size and type in the ArrayBuffer.It is required that byte_length + byte_offset is 780 * less than or equal to the size in bytes of the array passed in. If not, a RangeError exception 781 * is raised. 782 * 783 * @param env: The environment that the API is invoked under. 784 * @param length: Number of elements in the DataView. 785 * @param arraybuffer: ArrayBuffer underlying the DataView. 786 * @param byteOffset: The byte offset within the ArrayBuffer from which to start projecting the DataView. 787 * @param result:A JSVM_Value representing a JavaScript DataView. 788 * @return Returns JSVM_OK if the API succeeded. 789 * @since 11 790 */ 791 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDataview(JSVM_Env env, 792 size_t length, 793 JSVM_Value arraybuffer, 794 size_t byteOffset, 795 JSVM_Value* result); 796 797 /** 798 * @brief This API is used to convert from the C int32_t type to the JavaScript number type. 799 * 800 * @param env: The environment that the API is invoked under. 801 * @param value: Integer value to be represented in JavaScript. 802 * @param result: A JSVM_Value representing a JavaScript number. 803 * @return Returns JSVM_OK if the API succeeded. 804 * @since 11 805 */ 806 JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt32(JSVM_Env env, 807 int32_t value, 808 JSVM_Value* result); 809 810 /** 811 * @brief This API is used to convert from the C uint32_t type to the JavaScript number type. 812 * 813 * @param env: The environment that the API is invoked under. 814 * @param value: Unsigned integer value to be represented in JavaScript. 815 * @param result: A JSVM_Value representing a JavaScript number. 816 * @return Returns JSVM_OK if the API succeeded. 817 * @since 11 818 */ 819 JSVM_EXTERN JSVM_Status OH_JSVM_CreateUint32(JSVM_Env env, 820 uint32_t value, 821 JSVM_Value* result); 822 823 /** 824 * @brief This API is used to convert from the C int64_t type to the JavaScript number type. 825 * 826 * @param env: The environment that the API is invoked under. 827 * @param value: Integer value to be represented in JavaScript. 828 * @param result: A JSVM_Value representing a JavaScript number. 829 * @return Returns JSVM_OK if the API succeeded. 830 * @since 11 831 */ 832 JSVM_EXTERN JSVM_Status OH_JSVM_CreateInt64(JSVM_Env env, 833 int64_t value, 834 JSVM_Value* result); 835 836 /** 837 * @brief This API is used to convert from the C double type to the JavaScript number type. 838 * 839 * @param env: The environment that the API is invoked under. 840 * @param value: Double-precision value to be represented in JavaScript. 841 * @param result: A JSVM_Value representing a JavaScript number. 842 * @return Returns JSVM_OK if the API succeeded. 843 * @since 11 844 */ 845 JSVM_EXTERN JSVM_Status OH_JSVM_CreateDouble(JSVM_Env env, 846 double value, 847 JSVM_Value* result); 848 849 /** 850 * @brief This API converts the C int64_t type to the JavaScript BigInt type. 851 * 852 * @param env: The environment that the API is invoked under. 853 * @param value: Integer value to be represented in JavaScript. 854 * @param result: A JSVM_Value representing a JavaScript BigInt. 855 * @return Returns JSVM_OK if the API succeeded. 856 * @since 11 857 */ 858 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintInt64(JSVM_Env env, 859 int64_t value, 860 JSVM_Value* result); 861 862 /** 863 * @brief This API converts the C uint64_t type to the JavaScript BigInt type. 864 * 865 * @param env: The environment that the API is invoked under. 866 * @param value: Unsigned integer value to be represented in JavaScript. 867 * @param result: A JSVM_Value representing a JavaScript BigInt. 868 * @return Returns JSVM_OK if the API succeeded. 869 * @since 11 870 */ 871 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintUint64(JSVM_Env env, 872 uint64_t value, 873 JSVM_Value* result); 874 875 /** 876 * @brief This API converts an array of unsigned 64-bit words into a single BigInt value. 877 * The resulting BigInt is calculated as: (–1)sign_bit (words[0] × (264)0 + words[1] × (264)1 + …) 878 * 879 * @param env: The environment that the API is invoked under. 880 * @param signBit: Determines if the resulting BigInt will be positive or negative. 881 * @param wordCount: The length of the words array. 882 * @param words: An array of uint64_t little-endian 64-bit words. 883 * @param result: A JSVM_Value representing a JavaScript BigInt. 884 * @return Returns JSVM_OK if the API succeeded. 885 * @since 11 886 */ 887 JSVM_EXTERN JSVM_Status OH_JSVM_CreateBigintWords(JSVM_Env env, 888 int signBit, 889 size_t wordCount, 890 const uint64_t* words, 891 JSVM_Value* result); 892 893 /** 894 * @brief This API creates a JavaScript string value from an ISO-8859-1-encoded C 895 * string. The native string is copied. 896 * 897 * @param env: The environment that the API is invoked under. 898 * @param str: Character buffer representing an ISO-8859-1-encoded string. 899 * @param length: The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 900 * @param result: A JSVM_Value representing a JavaScript string. 901 * @return Returns JSVM_OK if the API succeeded. 902 * @since 11 903 */ 904 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringLatin1(JSVM_Env env, 905 const char* str, 906 size_t length, 907 JSVM_Value* result); 908 909 /** 910 * @brief This API creates a JavaScript string value from a UTF16-LE-encoded C 911 * string. The native string is copied. 912 * 913 * @param env: The environment that the API is invoked under. 914 * @param str: Character buffer representing a UTF16-LE-encoded string. 915 * @param length: The length of the string in two-byte code units, or JSVM_AUTO_LENGTH 916 * if it is null-terminated. 917 * @param result: A JSVM_Value representing a JavaScript string. 918 * @return Returns JSVM_OK if the API succeeded. 919 * @since 11 920 */ 921 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf16(JSVM_Env env, 922 const char16_t* str, 923 size_t length, 924 JSVM_Value* result); 925 926 /** 927 * @brief This API creates a JavaScript string value from a UTF8-encoded C 928 * string. The native string is copied. 929 * 930 * @param env: The environment that the API is invoked under. 931 * @param str: Character buffer representing a UTF8-encoded string. 932 * @param length: The length of the string in bytes, or JSVM_AUTO_LENGTH if it is null-terminated. 933 * @param result: A JSVM_Value representing a JavaScript string. 934 * @return Returns JSVM_OK if the API succeeded. 935 * @since 11 936 */ 937 JSVM_EXTERN JSVM_Status OH_JSVM_CreateStringUtf8(JSVM_Env env, 938 const char* str, 939 size_t length, 940 JSVM_Value* result); 941 942 /** 943 * @brief This API returns the length of an array. 944 * 945 * @param env: The environment that the API is invoked under. 946 * @param value: JSVM_Value representing the JavaScript Array whose length is being queried. 947 * @param result: uint32 representing length of the array. 948 * @return Returns JSVM_OK if the API succeeded. 949 * @since 11 950 */ 951 JSVM_EXTERN JSVM_Status OH_JSVM_GetArrayLength(JSVM_Env env, 952 JSVM_Value value, 953 uint32_t* result); 954 955 /** 956 * @brief This API is used to retrieve the underlying data buffer of an ArrayBuffer and its length. 957 * 958 * @param env: The environment that the API is invoked under. 959 * @param arraybuffer: JSVM_Value representing the ArrayBuffer being queried. 960 * @param data: The underlying data buffer of the ArrayBuffer. If byte_length is 0, this may be NULL 961 * or any other pointer value. 962 * @param byteLength: Length in bytes of the underlying data buffer. 963 * @return Returns JSVM_OK if the API succeeded. 964 * @since 11 965 */ 966 JSVM_EXTERN JSVM_Status OH_JSVM_GetArraybufferInfo(JSVM_Env env, 967 JSVM_Value arraybuffer, 968 void** data, 969 size_t* byteLength); 970 971 /** 972 * @brief This API returns the length of an array. 973 * 974 * @param env: The environment that the API is invoked under. 975 * @param object: JSVM_Value representing JavaScript Object whose prototype to return. This returns 976 * the equivalent of Object.getPrototypeOf (which is not the same as the function's prototype property). 977 * @param result: JSVM_Value representing prototype of the given object. 978 * @return Returns JSVM_OK if the API succeeded. 979 * @since 11 980 */ 981 JSVM_EXTERN JSVM_Status OH_JSVM_GetPrototype(JSVM_Env env, 982 JSVM_Value object, 983 JSVM_Value* result); 984 985 /** 986 * @brief This API returns various properties of a typed array. 987 * 988 * @param env: The environment that the API is invoked under. 989 * @param typedarray: JSVM_Value representing the TypedArray whose properties to query. 990 * @param type: Scalar datatype of the elements within the TypedArray. 991 * @param length: The number of elements in the TypedArray. 992 * @param data: The data buffer underlying the TypedArray adjusted by the byte_offset value so that it 993 * points to the first element in the TypedArray. If the length of the array is 0, this may be NULL or 994 * any other pointer value. 995 * @param arraybuffer: The ArrayBuffer underlying the TypedArray. 996 * @param byteOffset: The byte offset within the underlying native array at which the first element of 997 * the arrays is located. The value for the data parameter has already been adjusted so that data points 998 * to the first element in the array. Therefore, the first byte of the native array would be at data - byte_offset. 999 * @return Returns JSVM_OK if the API succeeded. 1000 * @since 11 1001 */ 1002 JSVM_EXTERN JSVM_Status OH_JSVM_GetTypedarrayInfo(JSVM_Env env, 1003 JSVM_Value typedarray, 1004 JSVM_TypedarrayType* type, 1005 size_t* length, 1006 void** data, 1007 JSVM_Value* arraybuffer, 1008 size_t* byteOffset); 1009 1010 /** 1011 * @brief Any of the out parameters may be NULL if that property is unneeded. 1012 * This API returns various properties of a DataView. 1013 * 1014 * @param env: The environment that the API is invoked under. 1015 * @param dataview: JSVM_Value representing the DataView whose properties to query. 1016 * @param bytelength: Number of bytes in the DataView. 1017 * @param data: The data buffer underlying the DataView. 1018 * If byte_length is 0, this may be NULL or any other pointer value. 1019 * @param arraybuffer: ArrayBuffer underlying the DataView. 1020 * @param byteOffset: The byte offset within the data buffer from which to start projecting the DataView. 1021 * @return Returns JSVM_OK if the API succeeded. 1022 * @since 11 1023 */ 1024 JSVM_EXTERN JSVM_Status OH_JSVM_GetDataviewInfo(JSVM_Env env, 1025 JSVM_Value dataview, 1026 size_t* bytelength, 1027 void** data, 1028 JSVM_Value* arraybuffer, 1029 size_t* byteOffset); 1030 1031 /** 1032 * @brief Returns JSVM_OK if the API succeeded. If a non-date JSVM_Value is 1033 * passed in it returns JSVM_date_expected.This API returns the C double 1034 * primitive of time value for the given JavaScript Date. 1035 * 1036 * @param env: The environment that the API is invoked under. 1037 * @param value: JSVM_Value representing a JavaScript Date. 1038 * @param result: Time value as a double represented as milliseconds 1039 * since midnight at the beginning of 01 January, 1970 UTC. 1040 * @return Returns JSVM_OK if the API succeeded. 1041 * @since 11 1042 */ 1043 JSVM_EXTERN JSVM_Status OH_JSVM_GetDateValue(JSVM_Env env, 1044 JSVM_Value value, 1045 double* result); 1046 1047 /** 1048 * @brief This API returns the C boolean primitive equivalent of the given JavaScript Boolean. 1049 * 1050 * @param env: The environment that the API is invoked under. 1051 * @param value: JSVM_Value representing JavaScript Boolean. 1052 * @param result: C boolean primitive equivalent of the given JavaScript Boolean. 1053 * @return Returns JSVM_OK if the API succeeded. 1054 * If a non-boolean JSVM_Value is passed in it returns JSVM_BOOLEAN_EXPECTED. 1055 * @since 11 1056 */ 1057 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBool(JSVM_Env env, 1058 JSVM_Value value, 1059 bool* result); 1060 1061 /** 1062 * @brief This API returns the C double primitive equivalent of the given JavaScript number. 1063 * 1064 * @param env: The environment that the API is invoked under. 1065 * @param value: JSVM_Value representing JavaScript number. 1066 * @param result: C double primitive equivalent of the given JavaScript number. 1067 * @return Returns JSVM_OK if the API succeeded. 1068 * If a non-number JSVM_Value is passed in it returns JSVM_NUMBER_EXPECTED. 1069 * @since 11 1070 */ 1071 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueDouble(JSVM_Env env, 1072 JSVM_Value value, 1073 double* result); 1074 1075 /** 1076 * @brief This API returns the C int64_t primitive equivalent of the given JavaScript BigInt. 1077 * If needed it will truncate the value, setting lossless to false. 1078 * 1079 * @param env: The environment that the API is invoked under. 1080 * @param value: JSVM_Value representing JavaScript BigInt. 1081 * @param result: C int64_t primitive equivalent of the given JavaScript BigInt. 1082 * @param lossless: Indicates whether the BigInt value was converted losslessly. 1083 * @return Returns JSVM_OK if the API succeeded. If a non-BigInt is passed in it returns JSVM_BIGINT_EXPECTED. 1084 * @since 11 1085 */ 1086 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintInt64(JSVM_Env env, 1087 JSVM_Value value, 1088 int64_t* result, 1089 bool* lossless); 1090 1091 /** 1092 * @brief This API returns the C uint64_t primitive equivalent of the given JavaScript BigInt. 1093 * If needed it will truncate the value, setting lossless to false. 1094 * 1095 * @param env: The environment that the API is invoked under. 1096 * @param value: JSVM_Value representing JavaScript BigInt. 1097 * @param result: C uint64_t primitive equivalent of the given JavaScript BigInt. 1098 * @param lossless: Indicates whether the BigInt value was converted losslessly. 1099 * @return Returns JSVM_OK if the API succeeded. If a non-BigInt is passed in it returns JSVM_BIGINT_EXPECTED. 1100 * @since 11 1101 */ 1102 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintUint64(JSVM_Env env, 1103 JSVM_Value value, 1104 uint64_t* result, 1105 bool* lossless); 1106 1107 /** 1108 * @brief This API converts a single BigInt value into a sign bit, 64-bit little-endian array, and the number 1109 * of elements in the array. signBit and words may be both set to NULL, in order to get only wordCount. 1110 * 1111 * @param env: The environment that the API is invoked under. 1112 * @param value: JSVM_Value representing JavaScript BigInt. 1113 * @param signBit: Integer representing if the JavaScript BigInt is positive or negative. 1114 * @param wordCount: Must be initialized to the length of the words array. Upon return, it will be set to 1115 * the actual number of words that would be needed to store this BigInt. 1116 * @param words: Pointer to a pre-allocated 64-bit word array. 1117 * @return Returns JSVM_OK if the API succeeded. 1118 * @since 11 1119 */ 1120 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueBigintWords(JSVM_Env env, 1121 JSVM_Value value, 1122 int* signBit, 1123 size_t* wordCount, 1124 uint64_t* words); 1125 1126 /** 1127 * @brief This API retrieves the external data pointer that was previously passed to OH_JSVM_CreateExternal(). 1128 * 1129 * @param env: The environment that the API is invoked under. 1130 * @param value: JSVM_Value representing JavaScript external value. 1131 * @param result: Pointer to the data wrapped by the JavaScript external value. 1132 * @return Returns JSVM_OK if the API succeeded. If a non-external JSVM_Value is passed in it returns JSVM_INVALID_ARG. 1133 * @since 11 1134 */ 1135 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueExternal(JSVM_Env env, 1136 JSVM_Value value, 1137 void** result); 1138 1139 /** 1140 * @brief This API returns the C int32 primitive equivalent of the given JavaScript number. 1141 * 1142 * @param env: The environment that the API is invoked under. 1143 * @param value: JSVM_Value representing JavaScript number. 1144 * @param result: C int32 primitive equivalent of the given JavaScript number. 1145 * @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED. 1146 * @since 11 1147 */ 1148 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt32(JSVM_Env env, 1149 JSVM_Value value, 1150 int32_t* result); 1151 1152 /** 1153 * @brief This API returns the C int64 primitive equivalent of the given JavaScript number. 1154 * 1155 * @param env: The environment that the API is invoked under. 1156 * @param value: JSVM_Value representing JavaScript number. 1157 * @param result: C int64 primitive equivalent of the given JavaScript number. 1158 * @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED. 1159 * @since 11 1160 */ 1161 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueInt64(JSVM_Env env, 1162 JSVM_Value value, 1163 int64_t* result); 1164 1165 /** 1166 * @brief This API returns the ISO-8859-1-encoded string corresponding the value passed in. 1167 * 1168 * @param env: The environment that the API is invoked under. 1169 * @param value: JSVM_Value representing JavaScript string. 1170 * @param buf: Buffer to write the ISO-8859-1-encoded string into. If NULL is passed in, the 1171 * length of the string in bytes and excluding the null terminator is returned in result. 1172 * @param bufsize: Size of the destination buffer. When this value is insufficient, the returned string 1173 * is truncated and null-terminated. 1174 * @param result: Number of bytes copied into the buffer, excluding the null terminator. 1175 * @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED. 1176 * @since 11 1177 */ 1178 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringLatin1(JSVM_Env env, 1179 JSVM_Value value, 1180 char* buf, 1181 size_t bufsize, 1182 size_t* result); 1183 1184 /** 1185 * @brief This API returns the UTF8-encoded string corresponding the value passed in. 1186 * 1187 * @param env: The environment that the API is invoked under. 1188 * @param value: JSVM_Value representing JavaScript string. 1189 * @param buf: Buffer to write the UTF8-encoded string into. If NULL is passed in, the length 1190 * of the string in bytes and excluding the null terminator is returned in result. 1191 * @param bufsize: Size of the destination buffer. When this value is insufficient, the returned 1192 * string is truncated and null-terminated. 1193 * @param result: Number of bytes copied into the buffer, excluding the null terminator. 1194 * @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED. 1195 * @since 11 1196 */ 1197 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf8(JSVM_Env env, 1198 JSVM_Value value, 1199 char* buf, 1200 size_t bufsize, 1201 size_t* result); 1202 1203 /** 1204 * @brief This API returns the UTF16-encoded string corresponding the value passed in. 1205 * 1206 * @param env: The environment that the API is invoked under. 1207 * @param value: JSVM_Value representing JavaScript string. 1208 * @param buf: Buffer to write the UTF16-LE-encoded string into. If NULL is passed in, 1209 * the length of the string in 2-byte code units and excluding the null terminator is returned. 1210 * @param bufsize: Size of the destination buffer. When this value is insufficient, 1211 * the returned string is truncated and null-terminated. 1212 * @param result: Number of 2-byte code units copied into the buffer, excluding the null terminator. 1213 * @return Returns JSVM_OK if the API succeeded. If a non-number JSVM_Value is passed in JSVM_NUMBER_EXPECTED. 1214 * @since 11 1215 */ 1216 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueStringUtf16(JSVM_Env env, 1217 JSVM_Value value, 1218 char16_t* buf, 1219 size_t bufsize, 1220 size_t* result); 1221 1222 /** 1223 * @brief This API returns the C primitive equivalent of the given JSVM_Value as a uint32_t. 1224 * 1225 * @param env: The environment that the API is invoked under. 1226 * @param value: JSVM_Value representing JavaScript number. 1227 * @param result: C primitive equivalent of the given JSVM_Value as a uint32_t. 1228 * @return Returns JSVM_OK if the API succeeded. 1229 * If a non-number JSVM_Value is passed in it returns JSVM_NUMBER_EXPECTED. 1230 * @since 11 1231 */ 1232 JSVM_EXTERN JSVM_Status OH_JSVM_GetValueUint32(JSVM_Env env, 1233 JSVM_Value value, 1234 uint32_t* result); 1235 1236 /** 1237 * @brief This API is used to return the JavaScript singleton object that is used to represent the given boolean value. 1238 * 1239 * @param env: The environment that the API is invoked under. 1240 * @param value: The value of the boolean to retrieve. 1241 * @param result: JSVM_Value representing JavaScript Boolean singleton to retrieve. 1242 * @return Returns JSVM_OK if the API succeeded. 1243 * @since 11 1244 */ 1245 JSVM_EXTERN JSVM_Status OH_JSVM_GetBoolean(JSVM_Env env, 1246 bool value, 1247 JSVM_Value* result); 1248 1249 /** 1250 * @brief This API returns the global object. 1251 * 1252 * @param env: The environment that the API is invoked under. 1253 * @param result: JSVM_Value representing JavaScript global object. 1254 * @return Returns JSVM_OK if the API succeeded. 1255 * @since 11 1256 */ 1257 JSVM_EXTERN JSVM_Status OH_JSVM_GetGlobal(JSVM_Env env, 1258 JSVM_Value* result); 1259 1260 /** 1261 * @brief This API returns the null object. 1262 * 1263 * @param env: The environment that the API is invoked under. 1264 * @param result: JSVM_Value representing JavaScript null object. 1265 * @return Returns JSVM_OK if the API succeeded. 1266 * @since 11 1267 */ 1268 JSVM_EXTERN JSVM_Status OH_JSVM_GetNull(JSVM_Env env, 1269 JSVM_Value* result); 1270 1271 /** 1272 * @brief This API returns the Undefined object. 1273 * 1274 * @param env: The environment that the API is invoked under. 1275 * @param result: JSVM_Value representing JavaScript Undefined value. 1276 * @return Returns JSVM_OK if the API succeeded. 1277 * @since 11 1278 */ 1279 JSVM_EXTERN JSVM_Status OH_JSVM_GetUndefined(JSVM_Env env, 1280 JSVM_Value* result); 1281 1282 /** 1283 * @brief This API implements the abstract operation ToBoolean() 1284 * 1285 * @param env: The environment that the API is invoked under. 1286 * @param value: The JavaScript value to coerce. 1287 * @param result: JSVM_Value representing the coerced JavaScript Boolean. 1288 * @return Returns JSVM_OK if the API succeeded. 1289 * @since 11 1290 */ 1291 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToBool(JSVM_Env env, 1292 JSVM_Value value, 1293 JSVM_Value* result); 1294 1295 /** 1296 * @brief This API implements the abstract operation ToNumber() as defined. This 1297 * function potentially runs JS code if the passed-in value is an object. 1298 * 1299 * @param env: The environment that the API is invoked under. 1300 * @param value: The JavaScript value to coerce. 1301 * @param result: JSVM_Value representing the coerced JavaScript number. 1302 * @return Returns JSVM_OK if the API succeeded. 1303 * @since 11 1304 */ 1305 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToNumber(JSVM_Env env, 1306 JSVM_Value value, 1307 JSVM_Value* result); 1308 1309 /** 1310 * @brief This API implements the abstract operation ToObject(). 1311 * 1312 * @param env: The environment that the API is invoked under. 1313 * @param value: The JavaScript value to coerce. 1314 * @param result: JSVM_Value representing the coerced JavaScript Object. 1315 * @return Returns JSVM_OK if the API succeeded. 1316 * @since 11 1317 */ 1318 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToObject(JSVM_Env env, 1319 JSVM_Value value, 1320 JSVM_Value* result); 1321 1322 /** 1323 * @brief This API implements the abstract operation ToString().This 1324 * function potentially runs JS code if the passed-in value is an object. 1325 * 1326 * @param env: The environment that the API is invoked under. 1327 * @param value: The JavaScript value to coerce. 1328 * @param result: JSVM_Value representing the coerced JavaScript string. 1329 * @return Returns JSVM_OK if the API succeeded. 1330 * @since 11 1331 */ 1332 JSVM_EXTERN JSVM_Status OH_JSVM_CoerceToString(JSVM_Env env, 1333 JSVM_Value value, 1334 JSVM_Value* result); 1335 1336 /** 1337 * @brief This API represents behavior similar to invoking the typeof Operator 1338 * on the object as defined. However, there are some differences:It has support 1339 * for detecting an External value.It detects null as a separate type, while 1340 * ECMAScript typeof would detect object.If value has a type that is invalid, 1341 * an error is returned. 1342 * 1343 * @param env: The environment that the API is invoked under. 1344 * @param value: The JavaScript value whose type to query. 1345 * @param result: The type of the JavaScript value. 1346 * @return Returns JSVM_OK if the API succeeded. 1347 * @since 11 1348 */ 1349 JSVM_EXTERN JSVM_Status OH_JSVM_Typeof(JSVM_Env env, 1350 JSVM_Value value, 1351 JSVM_ValueType* result); 1352 1353 /** 1354 * @brief This API represents invoking the instanceof Operator on the object. 1355 * 1356 * @param env: The environment that the API is invoked under. 1357 * @param object: The JavaScript value to check. 1358 * @param constructor: The JavaScript function object of the constructor function 1359 * to check against. 1360 * @param result: Boolean that is set to true if object instanceof constructor is true. 1361 * @return Returns JSVM_OK if the API succeeded. 1362 * @since 11 1363 */ 1364 JSVM_EXTERN JSVM_Status OH_JSVM_Instanceof(JSVM_Env env, 1365 JSVM_Value object, 1366 JSVM_Value constructor, 1367 bool* result); 1368 1369 /** 1370 * @brief This API represents invoking the IsArray operation on the object 1371 * 1372 * @param env: The environment that the API is invoked under. 1373 * @param value: The JavaScript value to check. 1374 * @param result: Whether the given object is an array. 1375 * @return Returns JSVM_OK if the API succeeded. 1376 * @since 11 1377 */ 1378 JSVM_EXTERN JSVM_Status OH_JSVM_IsArray(JSVM_Env env, 1379 JSVM_Value value, 1380 bool* result); 1381 1382 /** 1383 * @brief This API checks if the Object passed in is an array buffer. 1384 * 1385 * @param env: The environment that the API is invoked under. 1386 * @param value: The JavaScript value to check. 1387 * @param result: Whether the given object is an ArrayBuffer. 1388 * @return Returns JSVM_OK if the API succeeded. 1389 * @since 11 1390 */ 1391 JSVM_EXTERN JSVM_Status OH_JSVM_IsArraybuffer(JSVM_Env env, 1392 JSVM_Value value, 1393 bool* result); 1394 1395 /** 1396 * @brief This API checks if the Object passed in is a date. 1397 * 1398 * @param env: The environment that the API is invoked under. 1399 * @param value: The JavaScript value to check. 1400 * @param result: Whether the given JSVM_Value represents a JavaScript Date object. 1401 * @return Returns JSVM_OK if the API succeeded. 1402 * @since 11 1403 */ 1404 JSVM_EXTERN JSVM_Status OH_JSVM_IsDate(JSVM_Env env, 1405 JSVM_Value value, 1406 bool* isDate); 1407 1408 /** 1409 * @brief This API checks if the Object passed in is a typed array. 1410 * 1411 * @param env: The environment that the API is invoked under. 1412 * @param value: The JavaScript value to check. 1413 * @param result: Whether the given JSVM_Value represents a TypedArray. 1414 * @return Returns JSVM_OK if the API succeeded. 1415 * @since 11 1416 */ 1417 JSVM_EXTERN JSVM_Status OH_JSVM_IsTypedarray(JSVM_Env env, 1418 JSVM_Value value, 1419 bool* result); 1420 1421 /** 1422 * @brief This API checks if the Object passed in is a DataView. 1423 * 1424 * @param env: The environment that the API is invoked under. 1425 * @param value: The JavaScript value to check. 1426 * @param result: Whether the given JSVM_Value represents a DataView. 1427 * @return Returns JSVM_OK if the API succeeded. 1428 * @since 11 1429 */ 1430 JSVM_EXTERN JSVM_Status OH_JSVM_IsDataview(JSVM_Env env, 1431 JSVM_Value value, 1432 bool* result); 1433 1434 /** 1435 * @brief This API represents the invocation of the Strict Equality algorithm. 1436 * Returns true only when both the type and value are equal. 1437 * 1438 * @param env: The environment that the API is invoked under. 1439 * @param lhs: The JavaScript value to check. 1440 * @param rhs: The JavaScript value to check against. 1441 * @param result: Whether the two JSVM_Value objects are equal. 1442 * @return Returns JSVM_OK if the API succeeded. 1443 * @since 11 1444 */ 1445 JSVM_EXTERN JSVM_Status OH_JSVM_StrictEquals(JSVM_Env env, 1446 JSVM_Value lhs, 1447 JSVM_Value rhs, 1448 bool* result); 1449 1450 /** 1451 * @brief This API represents the invocation of the Relaxed Equality algorithm. 1452 * Returns true as long as the values are equal, regardless of type. 1453 * 1454 * @param env: The environment that the API is invoked under. 1455 * @param lhs: The JavaScript value to check. 1456 * @param rhs: The JavaScript value to check against. 1457 * @param result: Whether the two JSVM_Value objects are relaxed equal. 1458 * @return Returns JSVM_OK if the API succeeded. 1459 * @since 12 1460 */ 1461 JSVM_EXTERN JSVM_Status OH_JSVM_Equals(JSVM_Env env, 1462 JSVM_Value lhs, 1463 JSVM_Value rhs, 1464 bool* result); 1465 1466 /** 1467 * @brief This API represents the invocation of the ArrayBuffer detach operation. 1468 * 1469 * @param env: The environment that the API is invoked under. 1470 * @param arraybuffer: The JavaScript ArrayBuffer to be detached. 1471 * @return Returns JSVM_OK if the API succeeded.If a non-detachable ArrayBuffer 1472 * is passed in it returns JSVM_DETACHABLE_ARRAYBUFFER_EXPECTED. 1473 * @since 11 1474 */ 1475 JSVM_EXTERN JSVM_Status OH_JSVM_DetachArraybuffer(JSVM_Env env, 1476 JSVM_Value arraybuffer); 1477 1478 /** 1479 * @brief This API represents the invocation of the ArrayBuffer IsDetachedBuffer operation. 1480 * 1481 * @param env: The environment that the API is invoked under. 1482 * @param value: The JavaScript ArrayBuffer to be checked. 1483 * @param result: Whether the arraybuffer is detached. 1484 * @return Returns JSVM_OK if the API succeeded. 1485 * @since 11 1486 */ 1487 JSVM_EXTERN JSVM_Status OH_JSVM_IsDetachedArraybuffer(JSVM_Env env, 1488 JSVM_Value value, 1489 bool* result); 1490 1491 /** 1492 * @brief This API returns the names of the enumerable properties of object as an array of 1493 * strings. The properties of object whose key is a symbol will not be included. 1494 * 1495 * @param env: The environment that the API is invoked under. 1496 * @param object: The object from which to retrieve the properties. 1497 * @param result: A JSVM_Value representing an array of JavaScript values that represent 1498 * the property names of the object. The API can be used to iterate over result using 1499 * OH_JSVM_GetArrayLength and OH_JSVM_GetElement. 1500 * @return Returns JSVM_OK if the API succeeded. 1501 * @since 11 1502 */ 1503 JSVM_EXTERN JSVM_Status OH_JSVM_GetPropertyNames(JSVM_Env env, 1504 JSVM_Value object, 1505 JSVM_Value* result); 1506 1507 /** 1508 * @brief This API returns an array containing the names of the available properties 1509 * of this object. 1510 * 1511 * @param env: The environment that the API is invoked under. 1512 * @param object: The object from which to retrieve the properties. 1513 * @param keyMode: Whether to retrieve prototype properties as well. 1514 * @param keyFilter: Which properties to retrieve (enumerable/readable/writable). 1515 * @param keyConversion: Whether to convert numbered property keys to strings. 1516 * @param result: result: A JSVM_Value representing an array of JavaScript values 1517 * that represent the property names of the object. OH_JSVM_GetArrayLength and 1518 * OH_JSVM_GetElement can be used to iterate over result. 1519 * @return Returns JSVM_OK if the API succeeded. 1520 * @since 11 1521 */ 1522 JSVM_EXTERN JSVM_Status OH_JSVM_GetAllPropertyNames(JSVM_Env env, 1523 JSVM_Value object, 1524 JSVM_KeyCollectionMode keyMode, 1525 JSVM_KeyFilter keyFilter, 1526 JSVM_KeyConversion keyConversion, 1527 JSVM_Value* result); 1528 1529 /** 1530 * @brief This API set a property on the Object passed in. 1531 * 1532 * @param env: The environment that the API is invoked under. 1533 * @param object: The object on which to set the property. 1534 * @param key: The name of the property to set. 1535 * @param value: The property value. 1536 * @return Returns JSVM_OK if the API succeeded. 1537 * @since 11 1538 */ 1539 JSVM_EXTERN JSVM_Status OH_JSVM_SetProperty(JSVM_Env env, 1540 JSVM_Value object, 1541 JSVM_Value key, 1542 JSVM_Value value); 1543 1544 /** 1545 * @brief This API gets the requested property from the Object passed in. 1546 * 1547 * @param env: The environment that the API is invoked under. 1548 * @param object: The object from which to retrieve the property. 1549 * @param key: The name of the property to retrieve. 1550 * @param result: The value of the property. 1551 * @return Returns JSVM_OK if the API succeeded. 1552 * @since 11 1553 */ 1554 JSVM_EXTERN JSVM_Status OH_JSVM_GetProperty(JSVM_Env env, 1555 JSVM_Value object, 1556 JSVM_Value key, 1557 JSVM_Value* result); 1558 1559 /** 1560 * @brief This API checks if the Object passed in has the named property. 1561 * 1562 * @param env: The environment that the API is invoked under. 1563 * @param object: The object to query. 1564 * @param key: The name of the property whose existence to check. 1565 * @param result: Whether the property exists on the object or not. 1566 * @return Returns JSVM_OK if the API succeeded. 1567 * @since 11 1568 */ 1569 JSVM_EXTERN JSVM_Status OH_JSVM_HasProperty(JSVM_Env env, 1570 JSVM_Value object, 1571 JSVM_Value key, 1572 bool* result); 1573 1574 /** 1575 * @brief This API attempts to delete the key own property from object. 1576 * 1577 * @param env: The environment that the API is invoked under. 1578 * @param object: The object to query. 1579 * @param key: The name of the property to delete. 1580 * @param result: Whether the property deletion succeeded or not. result 1581 * can optionally be ignored by passing NULL. 1582 * @return Returns JSVM_OK if the API succeeded. 1583 * @since 11 1584 */ 1585 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteProperty(JSVM_Env env, 1586 JSVM_Value object, 1587 JSVM_Value key, 1588 bool* result); 1589 1590 /** 1591 * @brief This API checks if the Object passed in has the named own property. 1592 * key must be a string or a symbol, or an error will be thrown. JSVM-API will 1593 * not perform any conversion between data types. 1594 * 1595 * @param env: The environment that the API is invoked under. 1596 * @param object: The object to query. 1597 * @param key: The name of the own property whose existence to check. 1598 * @param result: Whether the own property exists on the object or not. 1599 * @return Returns JSVM_OK if the API succeeded. 1600 * @since 11 1601 */ 1602 JSVM_EXTERN JSVM_Status OH_JSVM_HasOwnProperty(JSVM_Env env, 1603 JSVM_Value object, 1604 JSVM_Value key, 1605 bool* result); 1606 1607 /** 1608 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1609 * a JSVM_Value created from the string passed in as utf8Name. 1610 * 1611 * @param env: The environment that the API is invoked under. 1612 * @param object: The object on which to set the property. 1613 * @param utf8Name: The name of the property to set. 1614 * @param value: The property value. 1615 * @return Returns JSVM_OK if the API succeeded. 1616 * @since 11 1617 */ 1618 JSVM_EXTERN JSVM_Status OH_JSVM_SetNamedProperty(JSVM_Env env, 1619 JSVM_Value object, 1620 const char* utf8name, 1621 JSVM_Value value); 1622 1623 /** 1624 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1625 * a JSVM_Value created from the string passed in as utf8Name. 1626 * 1627 * @param env: The environment that the API is invoked under. 1628 * @param object: The object from which to retrieve the property. 1629 * @param utf8Name: The name of the property to get. 1630 * @param result: The value of the property. 1631 * @return Returns JSVM_OK if the API succeeded. 1632 * @since 11 1633 */ 1634 JSVM_EXTERN JSVM_Status OH_JSVM_GetNamedProperty(JSVM_Env env, 1635 JSVM_Value object, 1636 const char* utf8name, 1637 JSVM_Value* result); 1638 1639 /** 1640 * @brief This method is equivalent to calling OH_JSVM_SetProperty with 1641 * a JSVM_Value created from the string passed in as utf8Name. 1642 * 1643 * @param env: The environment that the API is invoked under. 1644 * @param object: The object to query. 1645 * @param utf8Name: The name of the property whose existence to check. 1646 * @param result: Whether the property exists on the object or not. 1647 * @return Returns JSVM_OK if the API succeeded. 1648 * @since 11 1649 */ 1650 JSVM_EXTERN JSVM_Status OH_JSVM_HasNamedProperty(JSVM_Env env, 1651 JSVM_Value object, 1652 const char* utf8name, 1653 bool* result); 1654 1655 /** 1656 * @brief This API sets an element on the Object passed in. 1657 * 1658 * @param env: The environment that the API is invoked under. 1659 * @param object: The object from which to set the properties. 1660 * @param index: The index of the property to set. 1661 * @param value: The property value. 1662 * @return Returns JSVM_OK if the API succeeded. 1663 * @since 11 1664 */ 1665 JSVM_EXTERN JSVM_Status OH_JSVM_SetElement(JSVM_Env env, 1666 JSVM_Value object, 1667 uint32_t index, 1668 JSVM_Value value); 1669 1670 /** 1671 * @brief This API gets the element at the requested index. 1672 * 1673 * @param env: The environment that the API is invoked under. 1674 * @param object: The object from which to retrieve the property. 1675 * @param index: The index of the property to get. 1676 * @param result: The value of the property. 1677 * @return Returns JSVM_OK if the API succeeded. 1678 * @since 11 1679 */ 1680 JSVM_EXTERN JSVM_Status OH_JSVM_GetElement(JSVM_Env env, 1681 JSVM_Value object, 1682 uint32_t index, 1683 JSVM_Value* result); 1684 1685 /** 1686 * @brief This API returns if the Object passed in has an element 1687 * at the requested index. 1688 * 1689 * @param env: The environment that the API is invoked under. 1690 * @param object: The object to query. 1691 * @param index: The index of the property whose existence to check. 1692 * @param result: Whether the property exists on the object or not. 1693 * @return Returns JSVM_OK if the API succeeded. 1694 * @since 11 1695 */ 1696 JSVM_EXTERN JSVM_Status OH_JSVM_HasElement(JSVM_Env env, 1697 JSVM_Value object, 1698 uint32_t index, 1699 bool* result); 1700 1701 /** 1702 * @brief This API attempts to delete the specified index from object. 1703 * 1704 * @param env: The environment that the API is invoked under. 1705 * @param object: The object to query. 1706 * @param index: The index of the property to delete. 1707 * @param result: Whether the element deletion succeeded or not. result 1708 * can optionally be ignored by passing NULL. 1709 * @return Returns JSVM_OK if the API succeeded. 1710 * @since 11 1711 */ 1712 JSVM_EXTERN JSVM_Status OH_JSVM_DeleteElement(JSVM_Env env, 1713 JSVM_Value object, 1714 uint32_t index, 1715 bool* result); 1716 1717 /** 1718 * @brief This method allows the efficient definition of multiple properties 1719 * on a given object. The properties are defined using property descriptors. 1720 * Given an array of such property descriptors, this API will set the properties 1721 * on the object one at a time, as defined by DefineOwnProperty(). 1722 * 1723 * @param env: The environment that the API is invoked under. 1724 * @param object: The object from which to retrieve the properties. 1725 * @param propertyCount: The number of elements in the properties array. 1726 * @param properties: The array of property descriptors. 1727 * @return Returns JSVM_OK if the API succeeded. 1728 * @since 11 1729 */ 1730 JSVM_EXTERN JSVM_Status OH_JSVM_DefineProperties(JSVM_Env env, 1731 JSVM_Value object, 1732 size_t propertyCount, 1733 const JSVM_PropertyDescriptor* properties); 1734 1735 /** 1736 * @brief This method freezes a given object. This prevents new properties 1737 * from being added to it, existing properties from being removed, prevents 1738 * changing the enumerability, configurability, or writability of existing 1739 * properties, and prevents the values of existing properties from being changed. 1740 * It also prevents the object's prototype from being changed. 1741 * 1742 * @param env: The environment that the API is invoked under. 1743 * @param object: The object to freeze. 1744 * @return Returns JSVM_OK if the API succeeded. 1745 * @since 11 1746 */ 1747 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectFreeze(JSVM_Env env, 1748 JSVM_Value object); 1749 1750 /** 1751 * @brief This method seals a given object. This prevents new properties 1752 * from being added to it, as well as marking all existing properties as non-configurable. 1753 * 1754 * @param env: The environment that the API is invoked under. 1755 * @param object: The object to seal. 1756 * @return Returns JSVM_OK if the API succeeded. 1757 * @since 11 1758 */ 1759 JSVM_EXTERN JSVM_Status OH_JSVM_ObjectSeal(JSVM_Env env, 1760 JSVM_Value object); 1761 1762 /** 1763 * @brief This method allows a JavaScript function object to be called from 1764 * a native add-on. This is the primary mechanism of calling back from the 1765 * add-on's native code into JavaScript. 1766 * 1767 * @param env: The environment that the API is invoked under. 1768 * @param recv: The this value passed to the called function. 1769 * @param func: JSVM_Value representing the JavaScript function to be invoked. 1770 * @param argc: The count of elements in the argv array. 1771 * @param argv: Array of JSVM_values representing JavaScript values passed in as arguments to the function. 1772 * @param result: JSVM_Value representing the JavaScript object returned. 1773 * @return Returns JSVM_OK if the API succeeded. 1774 * @since 11 1775 */ 1776 JSVM_EXTERN JSVM_Status OH_JSVM_CallFunction(JSVM_Env env, 1777 JSVM_Value recv, 1778 JSVM_Value func, 1779 size_t argc, 1780 const JSVM_Value* argv, 1781 JSVM_Value* result); 1782 1783 /** 1784 * @brief This API allows an add-on author to create a function object in native 1785 * code. This is the primary mechanism to allow calling into the add-on's native 1786 * code from JavaScript.The newly created function is not automatically visible 1787 * from script after this call. Instead, a property must be explicitly set on any 1788 * object that is visible to JavaScript, in order for the function to be accessible 1789 * from script. 1790 * 1791 * @param env: The environment that the API is invoked under. 1792 * @param utf8Name: Optional name of the function encoded as UTF8. This is visible 1793 * within JavaScript as the new function object's name property. 1794 * @param length: The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 1795 * is null-terminated. 1796 * @param cb: The native function which should be called when this function 1797 * object is invoked and data. JSVM_Callback provides more details. 1798 * @param result: JSVM_Value representing the JavaScript function object for the newly 1799 * created function. 1800 * @return Returns JSVM_OK if the API succeeded. 1801 * @since 11 1802 */ 1803 JSVM_EXTERN JSVM_Status OH_JSVM_CreateFunction(JSVM_Env env, 1804 const char* utf8name, 1805 size_t length, 1806 JSVM_Callback cb, 1807 JSVM_Value* result); 1808 1809 /** 1810 * @brief This method is used within a callback function to retrieve details about 1811 * the call like the arguments and the this pointer from a given callback info. 1812 * 1813 * @param env: The environment that the API is invoked under. 1814 * @param cbinfo: The callback info passed into the callback function. 1815 * @param argc: Specifies the length of the provided argv array and receives the 1816 * actual count of arguments. argc can optionally be ignored by passing NULL. 1817 * @param argv: C array of JSVM_values to which the arguments will be copied. If 1818 * there are more arguments than the provided count, only the requested number of 1819 * arguments are copied. If there are fewer arguments provided than claimed, the 1820 * rest of argv is filled with JSVM_Value values that represent undefined. argv 1821 * can optionally be ignored by passing NULL. 1822 * @param thisArg: Receives the JavaScript this argument for the call. thisArg 1823 * can optionally be ignored by passing NULL. 1824 * @param data: Receives the data pointer for the callback. data can optionally 1825 * be ignored by passing NULL. 1826 * @return Returns JSVM_OK if the API succeeded. 1827 * @since 11 1828 */ 1829 JSVM_EXTERN JSVM_Status OH_JSVM_GetCbInfo(JSVM_Env env, 1830 JSVM_CallbackInfo cbinfo, 1831 size_t* argc, 1832 JSVM_Value* argv, 1833 JSVM_Value* thisArg, 1834 void** data); 1835 1836 /** 1837 * @brief This API returns the new.target of the constructor call. If the 1838 * current callback is not a constructor call, the result is NULL. 1839 * 1840 * @param env: The environment that the API is invoked under. 1841 * @param cbinfo: The callback info passed into the callback function. 1842 * @param result: The new.target of the constructor call. 1843 * @return Returns JSVM_OK if the API succeeded. 1844 * @since 11 1845 */ 1846 JSVM_EXTERN JSVM_Status OH_JSVM_GetNewTarget(JSVM_Env env, 1847 JSVM_CallbackInfo cbinfo, 1848 JSVM_Value* result); 1849 1850 /** 1851 * @brief his method is used to instantiate a new JavaScript value using 1852 * a given JSVM_Value that represents the constructor for the object. 1853 * 1854 * @param env: The environment that the API is invoked under. 1855 * @param constructor: JSVM_Value representing the JavaScript function to be invoked as a constructor. 1856 * @param argc: The count of elements in the argv array. 1857 * @param argv: Array of JavaScript values as JSVM_Value representing the arguments to 1858 * the constructor. If argc is zero this parameter may be omitted by passing in NULL. 1859 * @param result: JSVM_Value representing the JavaScript object returned, which 1860 * in this case is the constructed object. 1861 * @return Returns JSVM_OK if the API succeeded. 1862 * @since 11 1863 */ 1864 JSVM_EXTERN JSVM_Status OH_JSVM_NewInstance(JSVM_Env env, 1865 JSVM_Value constructor, 1866 size_t argc, 1867 const JSVM_Value* argv, 1868 JSVM_Value* result); 1869 1870 /** 1871 * @brief When wrapping a C++ class, the C++ constructor callback passed via constructor 1872 * should be a static method on the class that calls the actual class constructor, then 1873 * wraps the new C++ instance in a JavaScript object, and returns the wrapper object. 1874 * 1875 * @param env: The environment that the API is invoked under. 1876 * @param utf8name: Name of the JavaScript constructor function. For clarity, it is 1877 * recommended to use the C++ class name when wrapping a C++ class. 1878 * @param length: The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 1879 * is null-terminated. 1880 * @param constructor: Struct include callback function that handles constructing instances of the class. 1881 * When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback 1882 * signature. A C++ class constructor cannot be used. 1883 * Include Optional data to be passed to the constructor callback as the data 1884 * property of the callback info. JSVM_Callback provides more details. 1885 * @param propertyCount: Number of items in the properties array argument. 1886 * @param properties: Array of property descriptors describing static and instance data 1887 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 1888 * @param result: A JSVM_Value representing the constructor function for the class. 1889 * @return Returns JSVM_OK if the API succeeded. 1890 * @since 11 1891 */ 1892 JSVM_EXTERN JSVM_Status OH_JSVM_DefineClass(JSVM_Env env, 1893 const char* utf8name, 1894 size_t length, 1895 JSVM_Callback constructor, 1896 size_t propertyCount, 1897 const JSVM_PropertyDescriptor* properties, 1898 JSVM_Value* result); 1899 1900 /** 1901 * @brief Wraps a native instance in a JavaScript object. The native instance can 1902 * be retrieved later using OH_JSVM_Unwrap(). 1903 * 1904 * @param env: The environment that the API is invoked under. 1905 * @param jsObject: The JavaScript object that will be the wrapper for the native object. 1906 * @param nativeObject: The native instance that will be wrapped in the JavaScript object. 1907 * @param finalizeCb: Optional native callback that can be used to free the native instance 1908 * when the JavaScript object has been garbage-collected. 1909 * @param finalizeHint: Optional contextual hint that is passed to the finalize callback. 1910 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 1911 * @param result: Optional reference to the wrapped object. 1912 * @return Returns JSVM_OK if the API succeeded. 1913 * @since 11 1914 */ 1915 JSVM_EXTERN JSVM_Status OH_JSVM_Wrap(JSVM_Env env, 1916 JSVM_Value jsObject, 1917 void* nativeObject, 1918 JSVM_Finalize finalizeCb, 1919 void* finalizeHint, 1920 JSVM_Ref* result); 1921 1922 /** 1923 * @brief When JavaScript code invokes a method or property accessor on the class, the corresponding 1924 * JSVM_Callback is invoked. If the callback is for an instance method or accessor, then the this 1925 * argument to the callback is the wrapper object; the wrapped C++ instance that is the target of 1926 * the call can be obtained then by calling OH_JSVM_Unwrap() on the wrapper object. 1927 * 1928 * @param env: The environment that the API is invoked under. 1929 * @param jsObject: The object associated with the native instance. 1930 * @param result: Pointer to the wrapped native instance. 1931 * @return Returns JSVM_OK if the API succeeded. 1932 * @since 11 1933 */ 1934 JSVM_EXTERN JSVM_Status OH_JSVM_Unwrap(JSVM_Env env, 1935 JSVM_Value jsObject, 1936 void** result); 1937 1938 /** 1939 * @brief Retrieves a native instance that was previously wrapped in the JavaScript object jsObject 1940 * using OH_JSVM_Wrap() and removes the wrapping. If a finalize callback was associated with the wrapping, 1941 * it will no longer be called when the JavaScript object becomes garbage-collected. 1942 * 1943 * @param env: The environment that the API is invoked under. 1944 * @param jsObject: The object associated with the native instance. 1945 * @param result: Pointer to the wrapped native instance. 1946 * @return Returns JSVM_OK if the API succeeded. 1947 * @since 11 1948 */ 1949 JSVM_EXTERN JSVM_Status OH_JSVM_RemoveWrap(JSVM_Env env, 1950 JSVM_Value jsObject, 1951 void** result); 1952 1953 /** 1954 * @brief Associates the value of the typeTag pointer with the JavaScript object or external. 1955 * OH_JSVM_CheckObjectTypeTag() can then be used to compare the tag that was attached to the 1956 * object with one owned by the addon to ensure that the object has the right type. 1957 * If the object already has an associated type tag, this API will return JSVM_INVALID_ARG. 1958 * 1959 * @param env: The environment that the API is invoked under. 1960 * @param value: The JavaScript object or external to be marked. 1961 * @param typeTag: The tag with which the object is to be marked. 1962 * @return Returns JSVM_OK if the API succeeded. 1963 * @since 11 1964 */ 1965 JSVM_EXTERN JSVM_Status OH_JSVM_TypeTagObject(JSVM_Env env, 1966 JSVM_Value value, 1967 const JSVM_TypeTag* typeTag); 1968 1969 /** 1970 * @brief Compares the pointer given as typeTag with any that can be found on js object. 1971 * If no tag is found on js object or, if a tag is found but it does not match typeTag, 1972 * then result is set to false. If a tag is found and it matches typeTag, then result is set to true. 1973 * 1974 * @param env: The environment that the API is invoked under. 1975 * @param value: The JavaScript object or external whose type tag to examine. 1976 * @param typeTag: The tag with which to compare any tag found on the object. 1977 * @param result: Whether the type tag given matched the type tag on the object. false is also returned 1978 * if no type tag was found on the object. 1979 * @return Returns JSVM_OK if the API succeeded. 1980 * @since 11 1981 */ 1982 JSVM_EXTERN JSVM_Status OH_JSVM_CheckObjectTypeTag(JSVM_Env env, 1983 JSVM_Value value, 1984 const JSVM_TypeTag* typeTag, 1985 bool* result); 1986 1987 /** 1988 * @brief This API can be called multiple times on a single JavaScript object. 1989 * 1990 * @param env: The environment that the API is invoked under. 1991 * @param jsObject: The JavaScript object to which the native data will be attached. 1992 * @param finalizeData: Optional data to be passed to finalizeCb. 1993 * @param finalizeCb: Native callback that will be used to free the native data when the 1994 * JavaScript object has been garbage-collected. JSVM_Finalize provides more details. 1995 * @param finalizeHint: Optional contextual hint that is passed to the finalize callback. 1996 * @param result: Optional reference to the JavaScript object. 1997 * @return Returns JSVM_OK if the API succeeded. 1998 * @since 11 1999 */ 2000 JSVM_EXTERN JSVM_Status OH_JSVM_AddFinalizer(JSVM_Env env, 2001 JSVM_Value jsObject, 2002 void* finalizeData, 2003 JSVM_Finalize finalizeCb, 2004 void* finalizeHint, 2005 JSVM_Ref* result); 2006 2007 /** 2008 * @brief This API returns the highest JSVM-API version supported by the JSVM runtime. 2009 * 2010 * JSVM-API is planned to be additive such that newer releases of JSVM may support additional 2011 * API functions. In order to allow an addon to use a newer function when running with versions 2012 * of JSVM that support it, while providing fallback behavior when running with JSVM 2013 * versions that don't support it. 2014 * @param env: The environment that the API is invoked under. 2015 * @param result: The highest version of JSVM-API supported. 2016 * @return Returns JSVM_OK if the API succeeded. 2017 * @since 11 2018 */ 2019 JSVM_EXTERN JSVM_Status OH_JSVM_GetVersion(JSVM_Env env, 2020 uint32_t* result); 2021 2022 /** 2023 * @brief Return information of the VM. 2024 * 2025 * @param result: The information of the VM. 2026 * @return Returns JSVM_OK if the API succeeded. 2027 * @since 11 2028 */ 2029 JSVM_EXTERN JSVM_Status OH_JSVM_GetVMInfo(JSVM_VMInfo* result); 2030 2031 /** 2032 * @brief This function gives V8 an indication of the amount of externally 2033 * allocated memory that is kept alive by JavaScript objects (i.e. a JavaScript 2034 * object that points to its own memory allocated by a native addon). Registering 2035 * externally allocated memory will trigger global garbage collections more often 2036 * than it would otherwise. 2037 * 2038 * @param env: The environment that the API is invoked under. 2039 * @param changeInBytes: The change in externally allocated memory that is kept 2040 * alive by JavaScript objects. 2041 * @param result: The adjusted value 2042 * @return Returns JSVM_OK if the API succeeded. 2043 * @since 11 2044 */ 2045 JSVM_EXTERN JSVM_Status OH_JSVM_AdjustExternalMemory(JSVM_Env env, 2046 int64_t changeInBytes, 2047 int64_t* result); 2048 2049 /** 2050 * @brief This function notifies the VM that the system is running low on memory 2051 * and optionally triggers a garbage collection. 2052 * 2053 * @param env: The environment that the API is invoked under. 2054 * @param level: The memory pressure level set to the current VM. 2055 * @return Returns JSVM_OK if the API succeeded. 2056 * @since 11 2057 */ 2058 JSVM_EXTERN JSVM_Status OH_JSVM_MemoryPressureNotification(JSVM_Env env, 2059 JSVM_MemoryPressureLevel level); 2060 2061 /** 2062 * @brief This API creates a deferred object and a JavaScript promise. 2063 * 2064 * @param env: The environment that the API is invoked under. 2065 * @param deferred: A newly created deferred object which can later be 2066 * passed to OH_JSVM_ResolveDeferred() or OH_JSVM_RejectDeferred() to resolve 2067 * resp. reject the associated promise. 2068 * @param promise: The JavaScript promise associated with the deferred object. 2069 * @return Returns JSVM_OK if the API succeeded. 2070 * @since 11 2071 */ 2072 JSVM_EXTERN JSVM_Status OH_JSVM_CreatePromise(JSVM_Env env, 2073 JSVM_Deferred* deferred, 2074 JSVM_Value* promise); 2075 2076 /** 2077 * @brief This API resolves a JavaScript promise by way of the deferred object with 2078 * which it is associated. Thus, it can only be used to resolve JavaScript promises 2079 * for which the corresponding deferred object is available. This effectively means 2080 * that the promise must have been created using OH_JSVM_CreatePromise() and the deferred 2081 * object returned from that call must have been retained in order to be passed to this API. 2082 * 2083 * @param env: The environment that the API is invoked under. 2084 * @param deferred: The deferred object whose associated promise to resolve. 2085 * @param resolution: The value with which to resolve the promise. 2086 * @return Returns JSVM_OK if the API succeeded. 2087 * @since 11 2088 */ 2089 JSVM_EXTERN JSVM_Status OH_JSVM_ResolveDeferred(JSVM_Env env, 2090 JSVM_Deferred deferred, 2091 JSVM_Value resolution); 2092 2093 /** 2094 * @brief This API rejects a JavaScript promise by way of the deferred object with 2095 * which it is associated. Thus, it can only be used to reject JavaScript promises 2096 * for which the corresponding deferred object is available. This effectively means 2097 * that the promise must have been created using OH_JSVM_CreatePromise() and the deferred 2098 * object returned from that call must have been retained in order to be passed to this API. 2099 * 2100 * @param env: The environment that the API is invoked under. 2101 * @param deferred: The deferred object whose associated promise to resolve. 2102 * @param rejection: The value with which to reject the promise. 2103 * @return Returns JSVM_OK if the API succeeded. 2104 * @since 11 2105 */ 2106 JSVM_EXTERN JSVM_Status OH_JSVM_RejectDeferred(JSVM_Env env, 2107 JSVM_Deferred deferred, 2108 JSVM_Value rejection); 2109 2110 /** 2111 * @brief This API return indicating whether promise is a native promise object. 2112 * @param env: The environment that the API is invoked under. 2113 * @param value: The value to examine 2114 * @param isPromise: Flag indicating whether promise is a native promise object 2115 * @return Returns JSVM_OK if the API succeeded. 2116 * @since 11 2117 */ 2118 JSVM_EXTERN JSVM_Status OH_JSVM_IsPromise(JSVM_Env env, 2119 JSVM_Value value, 2120 bool* isPromise); 2121 2122 /** 2123 * @brief This API parses a JSON string and returns it as value if successful. 2124 * @param env: The environment that the API is invoked under. 2125 * @param jsonString: The string to parse. 2126 * @param result: The parse value if successful. 2127 * @return Returns JSVM_OK if the API succeeded. 2128 * @since 11 2129 */ 2130 JSVM_EXTERN JSVM_Status OH_JSVM_JsonParse(JSVM_Env env, 2131 JSVM_Value jsonString, 2132 JSVM_Value* result); 2133 2134 /** 2135 * @brief This API stringifies the object and returns it as string if successful. 2136 * @param env: The environment that the API is invoked under. 2137 * @param jsonObject: The object to stringify. 2138 * @param result: The string if successfully stringified. 2139 * @return Returns JSVM_OK if the API succeeded. 2140 * @since 11 2141 */ 2142 JSVM_EXTERN JSVM_Status OH_JSVM_JsonStringify(JSVM_Env env, 2143 JSVM_Value jsonObject, 2144 JSVM_Value* result); 2145 2146 /** 2147 * @brief This API create the startup snapshot of the VM. 2148 * @param vm: The environment that the API is invoked under. 2149 * @param contextCount: The object to stringify. 2150 * @param contexts: The array of contexts to add to the snapshot. 2151 * @param blobData: The snapshot data. 2152 * @param blobSize: The size of snapshot data. 2153 * @return Returns JSVM_OK if the API succeeded. 2154 * @since 11 2155 */ 2156 JSVM_EXTERN JSVM_Status OH_JSVM_CreateSnapshot(JSVM_VM vm, 2157 size_t contextCount, 2158 const JSVM_Env* contexts, 2159 const char** blobData, 2160 size_t* blobSize); 2161 2162 /** 2163 * @brief This function returns a set of statistics data of the heap of the VM. 2164 * 2165 * @param vm: The VM whose heap statistics are returned. 2166 * @param result: The heap statistics data. 2167 * @return Returns JSVM_OK if the API succeeded. 2168 * @since 12 2169 */ 2170 JSVM_EXTERN JSVM_Status OH_JSVM_GetHeapStatistics(JSVM_VM vm, 2171 JSVM_HeapStatistics* result); 2172 2173 /** 2174 * @brief This function creates and starts a CPU profiler. 2175 * 2176 * @param vm: The VM to start CPU profiler for. 2177 * @param result: The pointer to the CPU profiler. 2178 * @return Returns JSVM_OK if the API succeeded. 2179 * @since 12 2180 */ 2181 JSVM_EXTERN JSVM_Status OH_JSVM_StartCpuProfiler(JSVM_VM vm, 2182 JSVM_CpuProfiler* result); 2183 2184 /** 2185 * @brief This function stops the CPU profiler and output to the stream. 2186 * 2187 * @param vm: THe VM to start CPU profiler for. 2188 * @param profiler: The CPU profiler to stop. 2189 * @param stream: The output stream callback for receiving the data. 2190 * @param streamData: Optional data to be passed to the stream callback. 2191 * @return Returns JSVM_OK if the API succeeded. 2192 * @since 12 2193 */ 2194 JSVM_EXTERN JSVM_Status OH_JSVM_StopCpuProfiler(JSVM_VM vm, 2195 JSVM_CpuProfiler profiler, 2196 JSVM_OutputStream stream, 2197 void* streamData); 2198 2199 /** 2200 * @brief This funciton takes the current heap snapshot and output to the stream. 2201 * 2202 * @param vm: The VM whose heap snapshot is taken. 2203 * @param stream: The output stream callback for receiving the data. 2204 * @param streamData: Optional data to be passed to the stream callback. 2205 * @return Returns JSVM_OK if the API succeeded. 2206 * @since 12 2207 */ 2208 JSVM_EXTERN JSVM_Status OH_JSVM_TakeHeapSnapshot(JSVM_VM vm, 2209 JSVM_OutputStream stream, 2210 void* streamData); 2211 2212 /** 2213 * @brief This functiong activates insepctor on host and port. 2214 * 2215 * @param env: The environment that the API is invoked under. 2216 * @param host: The host to listen to for inspector connections. 2217 * @param port: The port to listen to for inspector connections. 2218 * @return Returns JSVM_OK if the API succeeded. 2219 * @since 12 2220 */ 2221 JSVM_EXTERN JSVM_Status OH_JSVM_OpenInspector(JSVM_Env env, 2222 const char* host, 2223 uint16_t port); 2224 2225 /** 2226 * @brief This function attempts to close all remaining inspector connections. 2227 * 2228 * @param env: The environment that the API is invoked under. 2229 * @return Returns JSVM_OK if the API succeeded. 2230 * @since 12 2231 */ 2232 JSVM_EXTERN JSVM_Status OH_JSVM_CloseInspector(JSVM_Env env); 2233 2234 /** 2235 * @brief This function will block until a client (existing or connected later) 2236 * has sent Runtime.runIfWaitingForDebugger command. 2237 * 2238 * @param env: The environment that the API is invoked under. 2239 * @param breakNextLine: Whether break on the next line of JavaScript code. 2240 * @return Returns JSVM_OK if the API succeeded. 2241 * @since 12 2242 */ 2243 JSVM_EXTERN JSVM_Status OH_JSVM_WaitForDebugger(JSVM_Env env, 2244 bool breakNextLine); 2245 2246 /** 2247 * @brief When packaging C++classes, the C++constructor callback passed through the constructor 2248 * triggers the corresponding callback function when getter, setter, call, and other 2249 * behaviors occur on the instance object, handles the user's custom behavior, and then wraps 2250 * the new C++instance in a JavaScript object and returns the wrapper object. 2251 * 2252 * @param env: The environment that the API is invoked under. 2253 * @param utf8name: Name of the JavaScript constructor function. For clarity, it is 2254 * recommended to use the C++ class name when wrapping a C++ class. 2255 * @param length: The length of the utf8name in bytes, or JSVM_AUTO_LENGTH if it 2256 * is null-terminated. 2257 * @param constructor: Struct include callback function that handles constructing instances of the class. 2258 * When wrapping a C++ class, this method must be a static member with the JSVM_Callback.callback 2259 * signature. A C++ class constructor cannot be used. 2260 * Include Optional data to be passed to the constructor callback as the data 2261 * property of the callback info. JSVM_Callback provides more details. 2262 * @param propertyCount: Number of items in the properties array argument. 2263 * @param properties: Array of property descriptors describing static and instance data 2264 * properties, accessors, and methods on the class See JSVM_PropertyDescriptor. 2265 * @param propertyHandlerCfg: The instance object triggers the corresponding callback function. 2266 * @param callAsFunctionCallback: Calling an instance object as a function will trigger this callback. 2267 * @param result: A JSVM_Value representing the constructor function for the class. 2268 * @return Returns JSVM_OK if the API succeeded. 2269 * @since 12 2270 */ 2271 JSVM_EXTERN JSVM_Status OH_JSVM_DefineClassWithPropertyHandler(JSVM_Env env, 2272 const char* utf8name, 2273 size_t length, 2274 JSVM_Callback constructor, 2275 size_t propertyCount, 2276 const JSVM_PropertyDescriptor* properties, 2277 JSVM_PropertyHandlerCfg propertyHandlerCfg, 2278 JSVM_Callback callAsFunctionCallback, 2279 JSVM_Value* result); 2280 2281 /** 2282 * @brief Determines whether the current thread holds the lock for the specified environment. 2283 * Only threads that hold locks can use the environment. 2284 * 2285 * @param env: The environment that the API is invoked under. 2286 * @param isLocked: Flag indicating whether the current thread holds the lock for the specified environment. 2287 * @return Returns JSVM_OK if the API succeeded. 2288 * @since 12 2289 */ 2290 JSVM_EXTERN JSVM_Status OH_JSVM_IsLocked(JSVM_Env env, 2291 bool* isLocked); 2292 2293 /** 2294 * @brief Acquire the lock for the specified environment. Only threads that hold locks can use the environment. 2295 * 2296 * @param env: The environment that the API is invoked under. 2297 * @return Returns JSVM_OK if the API succeeded. 2298 * @since 12 2299 */ 2300 JSVM_EXTERN JSVM_Status OH_JSVM_AcquireLock(JSVM_Env env); 2301 2302 /** 2303 * @brief Release the lock for the specified environment. Only threads that hold locks can use the environment. 2304 * 2305 * @param env: The environment that the API is invoked under. 2306 * @return Returns JSVM_OK if the API succeeded. 2307 * @since 12 2308 */ 2309 JSVM_EXTERN JSVM_Status OH_JSVM_ReleaseLock(JSVM_Env env); 2310 2311 /** 2312 * @brief Starts the running of the task queue inside the VM. 2313 * This task queue can be executed by an external event loop. 2314 * 2315 * @param env: The VM instance on which to start the task queue. 2316 * @param result: Whether the task queue was successfully started. 2317 * @return Returns JSVM_OK if the API succeeded. 2318 * @since 12 2319 */ 2320 JSVM_EXTERN JSVM_Status OH_JSVM_PumpMessageLoop(JSVM_VM vm, 2321 bool* result); 2322 2323 /** 2324 * @brief Check to see if there are any microtasks waiting in the queue, and if there are, execute them. 2325 * 2326 * @param env: The VM instance on which to check microtasks. 2327 * @return Returns JSVM_OK if the API succeeded. 2328 * @since 12 2329 */ 2330 JSVM_EXTERN JSVM_Status OH_JSVM_PerformMicrotaskCheckpoint(JSVM_VM vm); 2331 2332 /** 2333 * @brief This API checks if the value passed in is callable. 2334 * 2335 * @param env: The VM instance on which to check microtasks. 2336 * @param value: The JavaScript value to check. 2337 * @param isCallable: Whether the given value is callable. 2338 * @return Returns JSVM_OK if the API succeeded. 2339 * @since 12 2340 */ 2341 JSVM_EXTERN JSVM_Status OH_JSVM_IsCallable(JSVM_Env env, 2342 JSVM_Value value, 2343 bool* isCallable); 2344 2345 /** 2346 * @brief This API checks if the value passed in is undefined. 2347 * This equals to `value === undefined` in JS. 2348 * 2349 * @param env: The VM instance on which to check microtasks. 2350 * @param value: The JavaScript value to check. 2351 * @param isUndefined: Whether the given value is Undefined. 2352 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2353 * @since 12 2354 */ 2355 JSVM_EXTERN JSVM_Status OH_JSVM_IsUndefined(JSVM_Env env, 2356 JSVM_Value value, 2357 bool* isUndefined); 2358 2359 /** 2360 * @brief This API checks if the value passed in is a null object. 2361 * This equals to `value === null` in JS. 2362 * 2363 * @param env: The VM instance on which to check microtasks. 2364 * @param value: The JavaScript value to check. 2365 * @param isNull: Whether the given value is Null. 2366 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2367 * @since 12 2368 */ 2369 JSVM_EXTERN JSVM_Status OH_JSVM_IsNull(JSVM_Env env, 2370 JSVM_Value value, 2371 bool* isNull); 2372 2373 /** 2374 * @brief This API checks if the value passed in is either a null or an undefined object. 2375 * This is equivalent to `value == null` in JS. 2376 * 2377 * @param env: The VM instance on which to check microtasks. 2378 * @param value: The JavaScript value to check. 2379 * @param isNullOrUndefined: Whether the given value is Null or Undefined. 2380 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2381 * @since 12 2382 */ 2383 JSVM_EXTERN JSVM_Status OH_JSVM_IsNullOrUndefined(JSVM_Env env, 2384 JSVM_Value value, 2385 bool* isNullOrUndefined); 2386 2387 /** 2388 * @brief This API checks if the value passed in is a boolean. 2389 * This equals to `typeof value === 'boolean'` in JS. 2390 * 2391 * @param env: The VM instance on which to check microtasks. 2392 * @param value: The JavaScript value to check. 2393 * @param isBoolean: Whether the given value is Boolean. 2394 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2395 * @since 12 2396 */ 2397 JSVM_EXTERN JSVM_Status OH_JSVM_IsBoolean(JSVM_Env env, 2398 JSVM_Value value, 2399 bool* isBoolean); 2400 2401 /** 2402 * @brief This API checks if the value passed in is a number. 2403 * This equals to `typeof value === 'number'` in JS. 2404 * 2405 * @param env: The VM instance on which to check microtasks. 2406 * @param value: The JavaScript value to check. 2407 * @param isNumber: Whether the given value is Number. 2408 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2409 * @since 12 2410 */ 2411 JSVM_EXTERN JSVM_Status OH_JSVM_IsNumber(JSVM_Env env, 2412 JSVM_Value value, 2413 bool* isNumber); 2414 2415 /** 2416 * @brief This API checks if the value passed in is a string. 2417 * This equals to `typeof value === 'string'` in JS. 2418 * 2419 * @param env: The VM instance on which to check microtasks. 2420 * @param value: The JavaScript value to check. 2421 * @param isString: Whether the given value is String. 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_IsString(JSVM_Env env, 2426 JSVM_Value value, 2427 bool* isString); 2428 2429 /** 2430 * @brief This API checks if the value passed in is a symbol. 2431 * This equals to `typeof value === 'symbol'` in JS. 2432 * 2433 * @param env: The VM instance on which to check microtasks. 2434 * @param value: The JavaScript value to check. 2435 * @param isSymbol: Whether the given value is Symbol. 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_IsSymbol(JSVM_Env env, 2440 JSVM_Value value, 2441 bool* isSymbol); 2442 2443 /** 2444 * @brief This API checks if the value passed in is a function. 2445 * This equals to `typeof value === 'function'` in JS. 2446 * 2447 * @param env: The VM instance on which to check microtasks. 2448 * @param value: The JavaScript value to check. 2449 * @param isFunction: Whether the given value is Function. 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_IsFunction(JSVM_Env env, 2454 JSVM_Value value, 2455 bool* isFunction); 2456 2457 /** 2458 * @brief This API checks if the value passed in is an object. 2459 * 2460 * @param env: The VM instance on which to check microtasks. 2461 * @param value: The JavaScript value to check. 2462 * @param isObject: Whether the given value is Object. 2463 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2464 * @since 12 2465 */ 2466 JSVM_EXTERN JSVM_Status OH_JSVM_IsObject(JSVM_Env env, 2467 JSVM_Value value, 2468 bool* isObject); 2469 2470 /** 2471 * @brief This API checks if the value passed in is a bigInt. 2472 * This equals to `typeof value === 'bigint'` in JS. 2473 * 2474 * @param env: The VM instance on which to check microtasks. 2475 * @param value: The JavaScript value to check. 2476 * @param isBigInt: Whether the given value is BigInt. 2477 * @return Only returns JSVM_OK, because this API will not trigger any exception. 2478 * @since 12 2479 */ 2480 JSVM_EXTERN JSVM_Status OH_JSVM_IsBigInt(JSVM_Env env, 2481 JSVM_Value value, 2482 bool* isBigInt); 2483 EXTERN_C_END 2484 2485 /** @} */ 2486 #endif /* ARK_RUNTIME_JSVM_JSVM_H */ 2487 2488