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