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