1 #ifndef SRC_JS_NATIVE_API_H_ 2 #define SRC_JS_NATIVE_API_H_ 3 4 // This file needs to be compatible with C compilers. 5 #include <stddef.h> // NOLINT(modernize-deprecated-headers) 6 #include <stdbool.h> // NOLINT(modernize-deprecated-headers) 7 8 // Use INT_MAX, this should only be consumed by the pre-processor anyway. 9 #define NAPI_VERSION_EXPERIMENTAL 2147483647 10 #ifndef NAPI_VERSION 11 #ifdef NAPI_EXPERIMENTAL 12 #define NAPI_VERSION NAPI_VERSION_EXPERIMENTAL 13 #else 14 // The baseline version for N-API. 15 // The NAPI_VERSION controls which version will be used by default when 16 // compilling a native addon. If the addon developer specifically wants to use 17 // functions available in a new version of N-API that is not yet ported in all 18 // LTS versions, they can set NAPI_VERSION knowing that they have specifically 19 // depended on that version. 20 #define NAPI_VERSION 8 21 #endif 22 #endif 23 24 #include "js_native_api_types.h" 25 26 // If you need __declspec(dllimport), either include <node_api.h> instead, or 27 // define NAPI_EXTERN as __declspec(dllimport) on the compiler's command line. 28 #ifndef NAPI_EXTERN 29 #ifdef _WIN32 30 #define NAPI_EXTERN __declspec(dllexport) 31 #elif defined(__wasm32__) 32 #define NAPI_EXTERN __attribute__((visibility("default"))) \ 33 __attribute__((__import_module__("napi"))) 34 #else 35 #define NAPI_EXTERN __attribute__((visibility("default"))) 36 #endif 37 #endif 38 39 #define NAPI_AUTO_LENGTH SIZE_MAX 40 41 #ifdef __cplusplus 42 #define EXTERN_C_START extern "C" { 43 #define EXTERN_C_END } 44 #else 45 #define EXTERN_C_START 46 #define EXTERN_C_END 47 #endif 48 49 EXTERN_C_START 50 51 NAPI_EXTERN napi_status 52 napi_get_last_error_info(napi_env env, 53 const napi_extended_error_info** result); 54 55 // Getters for defined singletons 56 NAPI_EXTERN napi_status napi_get_undefined(napi_env env, napi_value* result); 57 NAPI_EXTERN napi_status napi_get_null(napi_env env, napi_value* result); 58 NAPI_EXTERN napi_status napi_get_global(napi_env env, napi_value* result); 59 NAPI_EXTERN napi_status napi_get_boolean(napi_env env, 60 bool value, 61 napi_value* result); 62 63 // Methods to create Primitive types/Objects 64 NAPI_EXTERN napi_status napi_create_object(napi_env env, napi_value* result); 65 NAPI_EXTERN napi_status napi_create_array(napi_env env, napi_value* result); 66 NAPI_EXTERN napi_status napi_create_array_with_length(napi_env env, 67 size_t length, 68 napi_value* result); 69 NAPI_EXTERN napi_status napi_create_double(napi_env env, 70 double value, 71 napi_value* result); 72 NAPI_EXTERN napi_status napi_create_int32(napi_env env, 73 int32_t value, 74 napi_value* result); 75 NAPI_EXTERN napi_status napi_create_uint32(napi_env env, 76 uint32_t value, 77 napi_value* result); 78 NAPI_EXTERN napi_status napi_create_int64(napi_env env, 79 int64_t value, 80 napi_value* result); 81 NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env, 82 const char* str, 83 size_t length, 84 napi_value* result); 85 NAPI_EXTERN napi_status napi_create_string_utf8(napi_env env, 86 const char* str, 87 size_t length, 88 napi_value* result); 89 NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, 90 const char16_t* str, 91 size_t length, 92 napi_value* result); 93 NAPI_EXTERN napi_status napi_create_symbol(napi_env env, 94 napi_value description, 95 napi_value* result); 96 NAPI_EXTERN napi_status napi_create_function(napi_env env, 97 const char* utf8name, 98 size_t length, 99 napi_callback cb, 100 void* data, 101 napi_value* result); 102 NAPI_EXTERN napi_status napi_create_error(napi_env env, 103 napi_value code, 104 napi_value msg, 105 napi_value* result); 106 NAPI_EXTERN napi_status napi_create_type_error(napi_env env, 107 napi_value code, 108 napi_value msg, 109 napi_value* result); 110 NAPI_EXTERN napi_status napi_create_range_error(napi_env env, 111 napi_value code, 112 napi_value msg, 113 napi_value* result); 114 115 // Methods to get the native napi_value from Primitive type 116 NAPI_EXTERN napi_status napi_typeof(napi_env env, 117 napi_value value, 118 napi_valuetype* result); 119 NAPI_EXTERN napi_status napi_get_value_double(napi_env env, 120 napi_value value, 121 double* result); 122 NAPI_EXTERN napi_status napi_get_value_int32(napi_env env, 123 napi_value value, 124 int32_t* result); 125 NAPI_EXTERN napi_status napi_get_value_uint32(napi_env env, 126 napi_value value, 127 uint32_t* result); 128 NAPI_EXTERN napi_status napi_get_value_int64(napi_env env, 129 napi_value value, 130 int64_t* result); 131 NAPI_EXTERN napi_status napi_get_value_bool(napi_env env, 132 napi_value value, 133 bool* result); 134 135 // Copies LATIN-1 encoded bytes from a string into a buffer. 136 NAPI_EXTERN napi_status napi_get_value_string_latin1(napi_env env, 137 napi_value value, 138 char* buf, 139 size_t bufsize, 140 size_t* result); 141 142 // Copies UTF-8 encoded bytes from a string into a buffer. 143 NAPI_EXTERN napi_status napi_get_value_string_utf8(napi_env env, 144 napi_value value, 145 char* buf, 146 size_t bufsize, 147 size_t* result); 148 149 // Copies UTF-16 encoded bytes from a string into a buffer. 150 NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env, 151 napi_value value, 152 char16_t* buf, 153 size_t bufsize, 154 size_t* result); 155 156 // Methods to coerce values 157 // These APIs may execute user scripts 158 NAPI_EXTERN napi_status napi_coerce_to_bool(napi_env env, 159 napi_value value, 160 napi_value* result); 161 NAPI_EXTERN napi_status napi_coerce_to_number(napi_env env, 162 napi_value value, 163 napi_value* result); 164 NAPI_EXTERN napi_status napi_coerce_to_object(napi_env env, 165 napi_value value, 166 napi_value* result); 167 NAPI_EXTERN napi_status napi_coerce_to_string(napi_env env, 168 napi_value value, 169 napi_value* result); 170 171 // Methods to work with Objects 172 NAPI_EXTERN napi_status napi_get_prototype(napi_env env, 173 napi_value object, 174 napi_value* result); 175 NAPI_EXTERN napi_status napi_get_property_names(napi_env env, 176 napi_value object, 177 napi_value* result); 178 NAPI_EXTERN napi_status napi_set_property(napi_env env, 179 napi_value object, 180 napi_value key, 181 napi_value value); 182 NAPI_EXTERN napi_status napi_has_property(napi_env env, 183 napi_value object, 184 napi_value key, 185 bool* result); 186 NAPI_EXTERN napi_status napi_get_property(napi_env env, 187 napi_value object, 188 napi_value key, 189 napi_value* result); 190 NAPI_EXTERN napi_status napi_delete_property(napi_env env, 191 napi_value object, 192 napi_value key, 193 bool* result); 194 NAPI_EXTERN napi_status napi_has_own_property(napi_env env, 195 napi_value object, 196 napi_value key, 197 bool* result); 198 NAPI_EXTERN napi_status napi_set_named_property(napi_env env, 199 napi_value object, 200 const char* utf8name, 201 napi_value value); 202 NAPI_EXTERN napi_status napi_has_named_property(napi_env env, 203 napi_value object, 204 const char* utf8name, 205 bool* result); 206 NAPI_EXTERN napi_status napi_get_named_property(napi_env env, 207 napi_value object, 208 const char* utf8name, 209 napi_value* result); 210 NAPI_EXTERN napi_status napi_set_element(napi_env env, 211 napi_value object, 212 uint32_t index, 213 napi_value value); 214 NAPI_EXTERN napi_status napi_has_element(napi_env env, 215 napi_value object, 216 uint32_t index, 217 bool* result); 218 NAPI_EXTERN napi_status napi_get_element(napi_env env, 219 napi_value object, 220 uint32_t index, 221 napi_value* result); 222 NAPI_EXTERN napi_status napi_delete_element(napi_env env, 223 napi_value object, 224 uint32_t index, 225 bool* result); 226 NAPI_EXTERN napi_status 227 napi_define_properties(napi_env env, 228 napi_value object, 229 size_t property_count, 230 const napi_property_descriptor* properties); 231 232 // Methods to work with Arrays 233 NAPI_EXTERN napi_status napi_is_array(napi_env env, 234 napi_value value, 235 bool* result); 236 NAPI_EXTERN napi_status napi_get_array_length(napi_env env, 237 napi_value value, 238 uint32_t* result); 239 240 // Methods to compare values 241 NAPI_EXTERN napi_status napi_strict_equals(napi_env env, 242 napi_value lhs, 243 napi_value rhs, 244 bool* result); 245 246 // Methods to work with Functions 247 NAPI_EXTERN napi_status napi_call_function(napi_env env, 248 napi_value recv, 249 napi_value func, 250 size_t argc, 251 const napi_value* argv, 252 napi_value* result); 253 NAPI_EXTERN napi_status napi_new_instance(napi_env env, 254 napi_value constructor, 255 size_t argc, 256 const napi_value* argv, 257 napi_value* result); 258 NAPI_EXTERN napi_status napi_instanceof(napi_env env, 259 napi_value object, 260 napi_value constructor, 261 bool* result); 262 263 // Methods to work with napi_callbacks 264 265 // Gets all callback info in a single call. (Ugly, but faster.) 266 NAPI_EXTERN napi_status napi_get_cb_info( 267 napi_env env, // [in] NAPI environment handle 268 napi_callback_info cbinfo, // [in] Opaque callback-info handle 269 size_t* argc, // [in-out] Specifies the size of the provided argv array 270 // and receives the actual count of args. 271 napi_value* argv, // [out] Array of values 272 napi_value* this_arg, // [out] Receives the JS 'this' arg for the call 273 void** data); // [out] Receives the data pointer for the callback. 274 275 NAPI_EXTERN napi_status napi_get_new_target(napi_env env, 276 napi_callback_info cbinfo, 277 napi_value* result); 278 NAPI_EXTERN napi_status 279 napi_define_class(napi_env env, 280 const char* utf8name, 281 size_t length, 282 napi_callback constructor, 283 void* data, 284 size_t property_count, 285 const napi_property_descriptor* properties, 286 napi_value* result); 287 288 // Methods to work with external data objects 289 NAPI_EXTERN napi_status napi_wrap(napi_env env, 290 napi_value js_object, 291 void* native_object, 292 napi_finalize finalize_cb, 293 void* finalize_hint, 294 napi_ref* result); 295 NAPI_EXTERN napi_status napi_unwrap(napi_env env, 296 napi_value js_object, 297 void** result); 298 NAPI_EXTERN napi_status napi_remove_wrap(napi_env env, 299 napi_value js_object, 300 void** result); 301 NAPI_EXTERN napi_status napi_create_external(napi_env env, 302 void* data, 303 napi_finalize finalize_cb, 304 void* finalize_hint, 305 napi_value* result); 306 NAPI_EXTERN napi_status napi_get_value_external(napi_env env, 307 napi_value value, 308 void** result); 309 310 // Methods to control object lifespan 311 312 // Set initial_refcount to 0 for a weak reference, >0 for a strong reference. 313 NAPI_EXTERN napi_status napi_create_reference(napi_env env, 314 napi_value value, 315 uint32_t initial_refcount, 316 napi_ref* result); 317 318 // Deletes a reference. The referenced value is released, and may 319 // be GC'd unless there are other references to it. 320 NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); 321 322 // Increments the reference count, optionally returning the resulting count. 323 // After this call the reference will be a strong reference because its 324 // refcount is >0, and the referenced object is effectively "pinned". 325 // Calling this when the refcount is 0 and the object is unavailable 326 // results in an error. 327 NAPI_EXTERN napi_status napi_reference_ref(napi_env env, 328 napi_ref ref, 329 uint32_t* result); 330 331 // Decrements the reference count, optionally returning the resulting count. 332 // If the result is 0 the reference is now weak and the object may be GC'd 333 // at any time if there are no other references. Calling this when the 334 // refcount is already 0 results in an error. 335 NAPI_EXTERN napi_status napi_reference_unref(napi_env env, 336 napi_ref ref, 337 uint32_t* result); 338 339 // Attempts to get a referenced value. If the reference is weak, 340 // the value might no longer be available, in that case the call 341 // is still successful but the result is NULL. 342 NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, 343 napi_ref ref, 344 napi_value* result); 345 346 NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, 347 napi_handle_scope* result); 348 NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, 349 napi_handle_scope scope); 350 NAPI_EXTERN napi_status 351 napi_open_escapable_handle_scope(napi_env env, 352 napi_escapable_handle_scope* result); 353 NAPI_EXTERN napi_status 354 napi_close_escapable_handle_scope(napi_env env, 355 napi_escapable_handle_scope scope); 356 357 NAPI_EXTERN napi_status napi_escape_handle(napi_env env, 358 napi_escapable_handle_scope scope, 359 napi_value escapee, 360 napi_value* result); 361 362 // Methods to support error handling 363 NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); 364 NAPI_EXTERN napi_status napi_throw_error(napi_env env, 365 const char* code, 366 const char* msg); 367 NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, 368 const char* code, 369 const char* msg); 370 NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, 371 const char* code, 372 const char* msg); 373 NAPI_EXTERN napi_status napi_is_error(napi_env env, 374 napi_value value, 375 bool* result); 376 377 // Methods to support catching exceptions 378 NAPI_EXTERN napi_status napi_is_exception_pending(napi_env env, bool* result); 379 NAPI_EXTERN napi_status napi_get_and_clear_last_exception(napi_env env, 380 napi_value* result); 381 382 // Methods to work with array buffers and typed arrays 383 NAPI_EXTERN napi_status napi_is_arraybuffer(napi_env env, 384 napi_value value, 385 bool* result); 386 NAPI_EXTERN napi_status napi_create_arraybuffer(napi_env env, 387 size_t byte_length, 388 void** data, 389 napi_value* result); 390 NAPI_EXTERN napi_status 391 napi_create_external_arraybuffer(napi_env env, 392 void* external_data, 393 size_t byte_length, 394 napi_finalize finalize_cb, 395 void* finalize_hint, 396 napi_value* result); 397 NAPI_EXTERN napi_status napi_get_arraybuffer_info(napi_env env, 398 napi_value arraybuffer, 399 void** data, 400 size_t* byte_length); 401 NAPI_EXTERN napi_status napi_is_typedarray(napi_env env, 402 napi_value value, 403 bool* result); 404 NAPI_EXTERN napi_status napi_create_typedarray(napi_env env, 405 napi_typedarray_type type, 406 size_t length, 407 napi_value arraybuffer, 408 size_t byte_offset, 409 napi_value* result); 410 NAPI_EXTERN napi_status napi_get_typedarray_info(napi_env env, 411 napi_value typedarray, 412 napi_typedarray_type* type, 413 size_t* length, 414 void** data, 415 napi_value* arraybuffer, 416 size_t* byte_offset); 417 418 NAPI_EXTERN napi_status napi_create_dataview(napi_env env, 419 size_t length, 420 napi_value arraybuffer, 421 size_t byte_offset, 422 napi_value* result); 423 NAPI_EXTERN napi_status napi_is_dataview(napi_env env, 424 napi_value value, 425 bool* result); 426 NAPI_EXTERN napi_status napi_get_dataview_info(napi_env env, 427 napi_value dataview, 428 size_t* bytelength, 429 void** data, 430 napi_value* arraybuffer, 431 size_t* byte_offset); 432 433 // version management 434 NAPI_EXTERN napi_status napi_get_version(napi_env env, uint32_t* result); 435 436 // Promises 437 NAPI_EXTERN napi_status napi_create_promise(napi_env env, 438 napi_deferred* deferred, 439 napi_value* promise); 440 NAPI_EXTERN napi_status napi_resolve_deferred(napi_env env, 441 napi_deferred deferred, 442 napi_value resolution); 443 NAPI_EXTERN napi_status napi_reject_deferred(napi_env env, 444 napi_deferred deferred, 445 napi_value rejection); 446 NAPI_EXTERN napi_status napi_is_promise(napi_env env, 447 napi_value value, 448 bool* is_promise); 449 450 // Running a script 451 NAPI_EXTERN napi_status napi_run_script(napi_env env, 452 napi_value script, 453 napi_value* result); 454 455 // Memory management 456 NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, 457 int64_t change_in_bytes, 458 int64_t* adjusted_value); 459 460 #if NAPI_VERSION >= 5 461 462 // Dates 463 NAPI_EXTERN napi_status napi_create_date(napi_env env, 464 double time, 465 napi_value* result); 466 467 NAPI_EXTERN napi_status napi_is_date(napi_env env, 468 napi_value value, 469 bool* is_date); 470 471 NAPI_EXTERN napi_status napi_get_date_value(napi_env env, 472 napi_value value, 473 double* result); 474 475 // Add finalizer for pointer 476 NAPI_EXTERN napi_status napi_add_finalizer(napi_env env, 477 napi_value js_object, 478 void* native_object, 479 napi_finalize finalize_cb, 480 void* finalize_hint, 481 napi_ref* result); 482 483 #endif // NAPI_VERSION >= 5 484 485 #if NAPI_VERSION >= 6 486 487 // BigInt 488 NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env, 489 int64_t value, 490 napi_value* result); 491 NAPI_EXTERN napi_status napi_create_bigint_uint64(napi_env env, 492 uint64_t value, 493 napi_value* result); 494 NAPI_EXTERN napi_status napi_create_bigint_words(napi_env env, 495 int sign_bit, 496 size_t word_count, 497 const uint64_t* words, 498 napi_value* result); 499 NAPI_EXTERN napi_status napi_get_value_bigint_int64(napi_env env, 500 napi_value value, 501 int64_t* result, 502 bool* lossless); 503 NAPI_EXTERN napi_status napi_get_value_bigint_uint64(napi_env env, 504 napi_value value, 505 uint64_t* result, 506 bool* lossless); 507 NAPI_EXTERN napi_status napi_get_value_bigint_words(napi_env env, 508 napi_value value, 509 int* sign_bit, 510 size_t* word_count, 511 uint64_t* words); 512 513 // Object 514 NAPI_EXTERN napi_status 515 napi_get_all_property_names(napi_env env, 516 napi_value object, 517 napi_key_collection_mode key_mode, 518 napi_key_filter key_filter, 519 napi_key_conversion key_conversion, 520 napi_value* result); 521 522 // Instance data 523 NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, 524 void* data, 525 napi_finalize finalize_cb, 526 void* finalize_hint); 527 528 NAPI_EXTERN napi_status napi_get_instance_data(napi_env env, 529 void** data); 530 #endif // NAPI_VERSION >= 6 531 532 #if NAPI_VERSION >= 7 533 // ArrayBuffer detaching 534 NAPI_EXTERN napi_status napi_detach_arraybuffer(napi_env env, 535 napi_value arraybuffer); 536 537 NAPI_EXTERN napi_status napi_is_detached_arraybuffer(napi_env env, 538 napi_value value, 539 bool* result); 540 #endif // NAPI_VERSION >= 7 541 542 #if NAPI_VERSION >= 8 543 // Type tagging 544 NAPI_EXTERN napi_status napi_type_tag_object(napi_env env, 545 napi_value value, 546 const napi_type_tag* type_tag); 547 548 NAPI_EXTERN napi_status 549 napi_check_object_type_tag(napi_env env, 550 napi_value value, 551 const napi_type_tag* type_tag, 552 bool* result); 553 NAPI_EXTERN napi_status napi_object_freeze(napi_env env, 554 napi_value object); 555 NAPI_EXTERN napi_status napi_object_seal(napi_env env, 556 napi_value object); 557 #endif // NAPI_VERSION >= 8 558 559 EXTERN_C_END 560 561 #endif // SRC_JS_NATIVE_API_H_ 562