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