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_TYPE_H 17 #define ARK_RUNTIME_JSVM_JSVM_TYPE_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_types.h 34 * 35 * @brief Provides the JSVM API type 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 #include <stddef.h> // NOLINT(modernize-deprecated-headers) 46 #include <stdint.h> // NOLINT(modernize-deprecated-headers) 47 48 #if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900) 49 typedef uint16_t char16_t; 50 #endif 51 52 #ifndef JSVM_CDECL 53 #ifdef _WIN32 54 #define JSVM_CDECL __cdecl 55 #else 56 #define JSVM_CDECL 57 #endif 58 #endif 59 60 /** 61 * @brief To represent a JavaScript VM instance. 62 * 63 * @since 11 64 */ 65 typedef struct JSVM_VM__* JSVM_VM; 66 67 /** 68 * @brief To represent a JavaScript VM scope. 69 * 70 * @since 11 71 */ 72 typedef struct JSVM_VMScope__* JSVM_VMScope; 73 74 /** 75 * @brief To represent a JavaScript VM environment scope. 76 * 77 * @since 11 78 */ 79 typedef struct JSVM_EnvScope__* JSVM_EnvScope; 80 81 /** 82 * @brief To represent a JavaScript code. 83 * 84 * @since 11 85 */ 86 typedef struct JSVM_Script__* JSVM_Script; 87 88 /** 89 * @brief To represent a JavaScript VM instance. 90 * 91 * @since 11 92 */ 93 typedef struct JSVM_Env__* JSVM_Env; 94 95 /** 96 * @brief To represent a JavaScript profiler. 97 * 98 * @since 12 99 */ 100 typedef struct JSVM_CpuProfiler__* JSVM_CpuProfiler; 101 102 /** 103 * @brief To represent a JavaScript VM environment. 104 * 105 * @since 11 106 */ 107 typedef struct JSVM_Value__* JSVM_Value; 108 109 /** 110 * @brief To represent a JavaScript value references. 111 * 112 * @since 11 113 */ 114 typedef struct JSVM_Ref__* JSVM_Ref; 115 116 /** 117 * @brief To represent a JavaScript VM handle scope. 118 * 119 * @since 11 120 */ 121 typedef struct JSVM_HandleScope__* JSVM_HandleScope; 122 123 /** 124 * @brief To represent a JavaScript VM escapable handle scope. 125 * 126 * @since 11 127 */ 128 typedef struct JSVM_EscapableHandleScope__* JSVM_EscapableHandleScope; 129 130 /** 131 * @brief To represent a JavaScript VM callback additional information. 132 * 133 * @since 11 134 */ 135 typedef struct JSVM_CallbackInfo__* JSVM_CallbackInfo; 136 137 /** 138 * @brief To represent a JavaScript VM value deferred. 139 * 140 * @since 11 141 */ 142 typedef struct JSVM_Deferred__* JSVM_Deferred; 143 144 145 /** 146 * @brief Callback function pointer and data for user-provided native function which are to exposed to js via JSVM-API. 147 * 148 * @since 11 149 */ 150 typedef struct { 151 JSVM_Value(JSVM_CDECL* callback)(JSVM_Env env, 152 JSVM_CallbackInfo info); 153 void* data; 154 } JSVM_CallbackStruct; 155 156 /** 157 * @brief Function pointer type for user-provided native function which are to exposed to js via JSVM-API. 158 * 159 * @since 11 160 */ 161 typedef JSVM_CallbackStruct* JSVM_Callback; 162 163 /** 164 * @brief Function pointer type for add-on provided function that allow the user to be notified. 165 * 166 * @since 11 167 */ 168 typedef void(JSVM_CDECL* JSVM_Finalize)(JSVM_Env env, 169 void* finalizeData, 170 void* finalizeHint); 171 172 /** 173 * @brief Function pointer type for callback of ASCII output stream. 174 * 175 * @since 12 176 */ 177 typedef bool(JSVM_CDECL* JSVM_OutputStream)(const char* data, 178 int size, 179 void* streamData); 180 181 /** 182 * @brief JSVM_PropertyAttributes are flag used to control the behavior of properties set on a js object. 183 * 184 * @since 11 185 */ 186 typedef enum { 187 /** No explicit attributes are set on the property. */ 188 JSVM_DEFAULT = 0, 189 /** The property is writable. */ 190 JSVM_WRITABLE = 1 << 0, 191 /** The property is enumeable. */ 192 JSVM_ENUMERABLE = 1 << 1, 193 /** The property is configurable. */ 194 JSVM_CONFIGURABLE = 1 << 2, 195 /** Used with OH_JSVM_DefineClass to distinguish static properties from instance properties. */ 196 JSVM_STATIC = 1 << 10, 197 /** Default for class methods. */ 198 JSVM_DEFAULT_METHOD = JSVM_WRITABLE | JSVM_CONFIGURABLE, 199 /** Default for object properties, like in JS obj[prop]. */ 200 JSVM_DEFAULT_JSPROPERTY = JSVM_WRITABLE | JSVM_ENUMERABLE | JSVM_CONFIGURABLE, 201 } JSVM_PropertyAttributes; 202 203 /** 204 * @brief Describes the type of a JSVM_Value. 205 * 206 * @since 11 207 */ 208 typedef enum { 209 /** undefined type. */ 210 JSVM_UNDEFINED, 211 /** null type. */ 212 JSVM_NULL, 213 /** boolean type. */ 214 JSVM_BOOLEAN, 215 /** number type. */ 216 JSVM_NUMBER, 217 /** string type. */ 218 JSVM_STRING, 219 /** symbol type. */ 220 JSVM_SYMBOL, 221 /** object type. */ 222 JSVM_OBJECT, 223 /** function type. */ 224 JSVM_FUNCTION, 225 /** external type. */ 226 JSVM_EXTERNAL, 227 /** bigint type. */ 228 JSVM_BIGINT, 229 } JSVM_ValueType; 230 231 /** 232 * @brief Describes the type of a typedarray. 233 * 234 * @since 11 235 */ 236 typedef enum { 237 /** int8 type. */ 238 JSVM_INT8_ARRAY, 239 /** uint8 type. */ 240 JSVM_UINT8_ARRAY, 241 /** uint8 clamped type. */ 242 JSVM_UINT8_CLAMPED_ARRAY, 243 /** int16 type. */ 244 JSVM_INT16_ARRAY, 245 /** uint16 type. */ 246 JSVM_UINT16_ARRAY, 247 /** int32 type. */ 248 JSVM_INT32_ARRAY, 249 /** uint32 type. */ 250 JSVM_UINT32_ARRAY, 251 /** float32 type. */ 252 JSVM_FLOAT32_ARRAY, 253 /** float64 type. */ 254 JSVM_FLOAT64_ARRAY, 255 /** bigint64 type. */ 256 JSVM_BIGINT64_ARRAY, 257 /** biguint64 type. */ 258 JSVM_BIGUINT64_ARRAY, 259 } JSVM_TypedarrayType; 260 261 /** 262 * @brief Integral status code indicating the success or failure of a JSVM-API call. 263 * 264 * @since 11 265 */ 266 typedef enum { 267 /** success status. */ 268 JSVM_OK, 269 /** invalidarg status. */ 270 JSVM_INVALID_ARG, 271 /** object expected status. */ 272 JSVM_OBJECT_EXPECTED, 273 /** string expected status. */ 274 JSVM_STRING_EXPECTED, 275 /** name expected status. */ 276 JSVM_NAME_EXPECTED, 277 /** function expected status. */ 278 JSVM_FUNCTION_EXPECTED, 279 /** number expected status. */ 280 JSVM_NUMBER_EXPECTED, 281 /** boolean expected status. */ 282 JSVM_BOOLEAN_EXPECTED, 283 /** array expected status. */ 284 JSVM_ARRAY_EXPECTED, 285 /** generic failure status. */ 286 JSVM_GENERIC_FAILURE, 287 /** pending exception status. */ 288 JSVM_PENDING_EXCEPTION, 289 /** cancelled status. */ 290 JSVM_CANCELLED, 291 /** escape called twice status. */ 292 JSVM_ESCAPE_CALLED_TWICE, 293 /** handle scope mismatch status. */ 294 JSVM_HANDLE_SCOPE_MISMATCH, 295 /** callback scope mismatch status. */ 296 JSVM_CALLBACK_SCOPE_MISMATCH, 297 /** queue full status. */ 298 JSVM_QUEUE_FULL, 299 /** closing status. */ 300 JSVM_CLOSING, 301 /** bigint expected status. */ 302 JSVM_BIGINT_EXPECTED, 303 /** date expected status. */ 304 JSVM_DATE_EXPECTED, 305 /** arraybuffer expected status. */ 306 JSVM_ARRAYBUFFER_EXPECTED, 307 /** detachable arraybuffer expected status. */ 308 JSVM_DETACHABLE_ARRAYBUFFER_EXPECTED, 309 /** would deadlock status. */ 310 JSVM_WOULD_DEADLOCK, 311 /** no external buffers allowed status. */ 312 JSVM_NO_EXTERNAL_BUFFERS_ALLOWED, 313 /** cannot run +js status. */ 314 JSVM_CANNOT_RUN_JS, 315 } JSVM_Status; 316 317 /** 318 * @brief limits the range of collected properties.. 319 * 320 * @since 11 321 */ 322 typedef enum { 323 /** will include all keys of the objects's prototype chain as well. */ 324 JSVM_KEY_INCLUDE_PROTOTYPES, 325 /** limits the collected properties to the given object only. */ 326 JSVM_KEY_OWN_ONLY 327 } JSVM_KeyCollectionMode; 328 329 /** 330 * @brief Property filter bits. They can be or'ed to build a composite filter.. 331 * 332 * @since 11 333 */ 334 typedef enum { 335 /** key all properties. */ 336 JSVM_KEY_ALL_PROPERTIES = 0, 337 /** key writable. */ 338 JSVM_KEY_WRITABLE = 1, 339 /** key enumerable. */ 340 JSVM_KEY_ENUMERABLE = 1 << 1, 341 /** key configurable. */ 342 JSVM_KEY_CONFIGURABLE = 1 << 2, 343 /** key skip strings. */ 344 JSVM_KEY_SKIP_STRINGS = 1 << 3, 345 /** key skip symbols. */ 346 JSVM_KEY_SKIP_SYMBOLS = 1 << 4 347 } JSVM_KeyFilter; 348 349 /** 350 * @brief key conversion select. 351 * 352 * @since 11 353 */ 354 typedef enum { 355 /** will return numbers for integer indices. */ 356 JSVM_KEY_KEEP_NUMBERS, 357 /** will convert integer indices to strings. */ 358 JSVM_KEY_NUMBERS_TO_STRINGS 359 } JSVM_KeyConversion; 360 361 /** 362 * @brief Memory pressure level. 363 * 364 * @since 11 365 */ 366 typedef enum { 367 /** none pressure. */ 368 JSVM_MEMORY_PRESSURE_LEVEL_NONE, 369 /** moderate pressure. */ 370 JSVM_MEMORY_PRESSURE_LEVEL_MODERATE, 371 /** critical pressure. */ 372 JSVM_MEMORY_PRESSURE_LEVEL_CRITICAL, 373 } JSVM_MemoryPressureLevel; 374 375 /** 376 * @brief Heap statisics. 377 * 378 * @since 12 379 */ 380 typedef struct { 381 /** the size of the total heap. */ 382 size_t totalHeapSize; 383 /** the executable size of the total heap. */ 384 size_t totalHeapSizeExecutable; 385 /** the physical size of the total heap. */ 386 size_t totalPhysicalSize; 387 /** the available size of the total heap. */ 388 size_t totalAvailableSize; 389 /** used size of the heap. */ 390 size_t usedHeapSize; 391 /** heap size limit. */ 392 size_t heapSizeLimit; 393 /** memory requested by the heap. */ 394 size_t mallocedMemory; 395 /** heap-requested external memory. */ 396 size_t externalMemory; 397 /** peak memory requested by the heap. */ 398 size_t peakMallocedMemory; 399 /** the number of native contexts. */ 400 size_t numberOfNativeContexts; 401 /** the number of detached contexts. */ 402 size_t numberOfDetachedContexts; 403 /** the size of the total global handles. */ 404 size_t totalGlobalHandlesSize; 405 /** the size of the used global handles. */ 406 size_t usedGlobalHandlesSize; 407 } JSVM_HeapStatistics; 408 409 /** 410 * @brief Init the JavaScript VM with init option. 411 * 412 * @since 11 413 */ 414 typedef struct { 415 /** 416 * Optional nullptr-terminated array of raw adddresses in the embedder that the 417 * VM can match against during serialization and use for deserialization. This 418 * array and its content must stay valid for the entire lifetime of the VM 419 * instance. 420 */ 421 const intptr_t* externalReferences; 422 423 /** 424 * Flags for the VM. IF removeFlags is true, recognized flags will be removed 425 * from (argc, argv). Note that these flags are specific to VM. 426 * They are mainly used for development. Do not include them in production as 427 * they might not take effect if the VM is different from the development 428 * environment. 429 */ 430 int* argc; 431 /** argv . */ 432 char** argv; 433 /** remove flags. */ 434 bool removeFlags; 435 } JSVM_InitOptions; 436 437 /** 438 * @brief Create the JavaScript VM with init option. 439 * 440 * @since 11 441 */ 442 typedef struct { 443 /** optional limits of memory use of the vm. */ 444 size_t maxOldGenerationSize; 445 /** optional limits of memory use of the vm. */ 446 size_t maxYoungGenerationSize; 447 /** optional limits of memory use of the vm. */ 448 size_t initialOldGenerationSize; 449 /** optional limits of memory use of the vm. */ 450 size_t initialYoungGenerationSize; 451 /** Optional startup snapshot data. */ 452 const char* snapshotBlobData; 453 /** Optional size of the startup snapshot data. */ 454 size_t snapshotBlobSize; 455 /** Whether the VM is used for creating snapshot. */ 456 bool isForSnapshotting; 457 } JSVM_CreateVMOptions; 458 459 /** 460 * @brief JavaScript VM info. 461 * 462 * @since 11 463 */ 464 typedef struct { 465 /** The highest API version this VM supports. */ 466 uint32_t apiVersion; 467 /** The engine name implementing the VM. */ 468 const char* engine; 469 /** The version of the VM. */ 470 const char* version; 471 /** The cached data version tag. */ 472 uint32_t cachedDataVersionTag; 473 } JSVM_VMInfo; 474 475 /** 476 * @brief Property descriptor. 477 * 478 * @since 11 479 */ 480 typedef struct { 481 /** Optional string describing the key for the property, encoded as UTF8. 482 * One of utf8name or name must be provided for the property. 483 */ 484 const char* utf8name; 485 /** Optional value that points to a JavaScript string or symbol to be used as the key for the property. */ 486 JSVM_Value name; 487 /** Set this to make the property descriptor object's value property to be 488 * a JavaScript function represented by method. 489 */ 490 JSVM_Callback method; 491 /** A function to call when a get access of the property is performed. */ 492 JSVM_Callback getter; 493 /** A function to call when a set access of the property is performed. */ 494 JSVM_Callback setter; 495 /** The value that's retrieved by a get access of the property if the property is a data property. */ 496 JSVM_Value value; 497 /** The attributes associated with the particular property. */ 498 JSVM_PropertyAttributes attributes; 499 } JSVM_PropertyDescriptor; 500 501 /** 502 * @brief JSVM-API uses both return values and JavaScript exceptions for error handling 503 * @since 11 504 */ 505 typedef struct { 506 /** UTF8-encoded string containing a VM-neutral description of the error. */ 507 const char* errorMessage; 508 /** Reserved for VM-specific error details. This is currently not implemented for any VM. */ 509 void* engineReserved; 510 /** VM-specific error code. This is currently not implemented for any VM. */ 511 uint32_t engineErrorCode; 512 /** The JSVM-API status code that originated with the last error. */ 513 JSVM_Status errorCode; 514 } JSVM_ExtendedErrorInfo; 515 516 /** 517 * @brief A 128-bit value stored as two unsigned 64-bit integers. 518 * It serves as a UUID with which JavaScript objects or externals can be "tagged" 519 * in order to ensure that they are of a certain type. 520 * 521 * @since 11 522 */ 523 typedef struct { 524 /** lower type. */ 525 uint64_t lower; 526 /** upper type. */ 527 uint64_t upper; 528 } JSVM_TypeTag; 529 530 /** 531 * @brief When the getter, setter, call, etc. behavior occurs on the object, the corresponding 532 * the corresponding callback will be triggered. 533 * 534 * @since 12 535 */ 536 typedef struct { 537 /** A callback function triggered by getting a named property of an instance object. */ 538 JSVM_Value(JSVM_CDECL* genericNamedPropertyGetterCallback)(JSVM_Env env, 539 JSVM_Value name, 540 JSVM_Value thisArg, 541 JSVM_Value namedPropertyData); 542 543 /** A callback function triggered by setting a named property of an instance object. */ 544 JSVM_Value(JSVM_CDECL* genericNamedPropertySetterCallback)(JSVM_Env env, 545 JSVM_Value name, 546 JSVM_Value property, 547 JSVM_Value thisArg, 548 JSVM_Value namedPropertyData); 549 550 /** A callback function triggered by deleting a named property of an instance object. */ 551 JSVM_Value(JSVM_CDECL* genericNamedPropertyDeleterCallback)(JSVM_Env env, 552 JSVM_Value name, 553 JSVM_Value thisArg, 554 JSVM_Value namedPropertyData); 555 556 /** A callback function triggered by getting all named properties requests on an object. */ 557 JSVM_Value(JSVM_CDECL* genericNamedPropertyEnumeratorCallback)(JSVM_Env env, 558 JSVM_Value thisArg, 559 JSVM_Value namedPropertyData); 560 561 /** A callback function triggered by getting an indexed property of an instance object. */ 562 JSVM_Value(JSVM_CDECL* genericIndexedPropertyGetterCallback)(JSVM_Env env, 563 JSVM_Value index, 564 JSVM_Value thisArg, 565 JSVM_Value indexedPropertyData); 566 567 /** A callback function triggered by setting an indexed property of an instance object. */ 568 JSVM_Value(JSVM_CDECL* genericIndexedPropertySetterCallback)(JSVM_Env env, 569 JSVM_Value index, 570 JSVM_Value property, 571 JSVM_Value thisArg, 572 JSVM_Value indexedPropertyData); 573 574 /** A callback function triggered by deleting an indexed property of an instance object. */ 575 JSVM_Value(JSVM_CDECL* genericIndexedPropertyDeleterCallback)(JSVM_Env env, 576 JSVM_Value index, 577 JSVM_Value thisArg, 578 JSVM_Value indexedPropertyData); 579 580 /** A callback function triggered by getting all indexed properties requests on an object. */ 581 JSVM_Value(JSVM_CDECL* genericIndexedPropertyEnumeratorCallback)(JSVM_Env env, 582 JSVM_Value thisArg, 583 JSVM_Value indexedPropertyData); 584 585 /** data will be utilized by the named property callbacks in this struct. */ 586 JSVM_Value namedPropertyData; 587 588 /** data will be utilized by the indexed property callbacks in this struct. */ 589 JSVM_Value indexedPropertyData; 590 } JSVM_PropertyHandlerConfigurationStruct; 591 592 /** 593 * @brief The function pointer type of the callback provided by the instance object, which triggers the 594 * corresponding callback when getter, setter, call, and other behaviors occur on the object. 595 * 596 * @since 12 597 */ 598 typedef JSVM_PropertyHandlerConfigurationStruct* JSVM_PropertyHandlerCfg; 599 600 /** 601 * 602 * @brief Source code information. 603 * 604 * @since 12 605 */ 606 typedef struct { 607 /** Sourcemap url. */ 608 const char* sourceMapUrl; 609 /** Resource name. */ 610 const char* resourceName; 611 /** Resource line offset. */ 612 size_t resourceLineOffset; 613 /** Resource column offset. */ 614 size_t resourceColumnOffset; 615 } JSVM_ScriptOrigin; 616 /** @} */ 617 #endif /* ARK_RUNTIME_JSVM_JSVM_TYPE_H */ 618