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