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 49EXTERN_C_START 50 51NAPI_EXTERN napi_status 52napi_get_last_error_info(napi_env env, 53 const napi_extended_error_info** result); 54 55// Getters for defined singletons 56NAPI_EXTERN napi_status napi_get_undefined(napi_env env, napi_value* result); 57NAPI_EXTERN napi_status napi_get_null(napi_env env, napi_value* result); 58NAPI_EXTERN napi_status napi_get_global(napi_env env, napi_value* result); 59NAPI_EXTERN napi_status napi_get_boolean(napi_env env, 60 bool value, 61 napi_value* result); 62 63// Methods to create Primitive types/Objects 64NAPI_EXTERN napi_status napi_create_object(napi_env env, napi_value* result); 65NAPI_EXTERN napi_status napi_create_array(napi_env env, napi_value* result); 66NAPI_EXTERN napi_status napi_create_array_with_length(napi_env env, 67 size_t length, 68 napi_value* result); 69NAPI_EXTERN napi_status napi_create_double(napi_env env, 70 double value, 71 napi_value* result); 72NAPI_EXTERN napi_status napi_create_int32(napi_env env, 73 int32_t value, 74 napi_value* result); 75NAPI_EXTERN napi_status napi_create_uint32(napi_env env, 76 uint32_t value, 77 napi_value* result); 78NAPI_EXTERN napi_status napi_create_int64(napi_env env, 79 int64_t value, 80 napi_value* result); 81NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env, 82 const char* str, 83 size_t length, 84 napi_value* result); 85NAPI_EXTERN napi_status napi_create_string_utf8(napi_env env, 86 const char* str, 87 size_t length, 88 napi_value* result); 89NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, 90 const char16_t* str, 91 size_t length, 92 napi_value* result); 93NAPI_EXTERN napi_status napi_create_symbol(napi_env env, 94 napi_value description, 95 napi_value* result); 96NAPI_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); 102NAPI_EXTERN napi_status napi_create_error(napi_env env, 103 napi_value code, 104 napi_value msg, 105 napi_value* result); 106NAPI_EXTERN napi_status napi_create_type_error(napi_env env, 107 napi_value code, 108 napi_value msg, 109 napi_value* result); 110NAPI_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 116NAPI_EXTERN napi_status napi_typeof(napi_env env, 117 napi_value value, 118 napi_valuetype* result); 119NAPI_EXTERN napi_status napi_get_value_double(napi_env env, 120 napi_value value, 121 double* result); 122NAPI_EXTERN napi_status napi_get_value_int32(napi_env env, 123 napi_value value, 124 int32_t* result); 125NAPI_EXTERN napi_status napi_get_value_uint32(napi_env env, 126 napi_value value, 127 uint32_t* result); 128NAPI_EXTERN napi_status napi_get_value_int64(napi_env env, 129 napi_value value, 130 int64_t* result); 131NAPI_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. 136NAPI_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. 143NAPI_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. 150NAPI_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 158NAPI_EXTERN napi_status napi_coerce_to_bool(napi_env env, 159 napi_value value, 160 napi_value* result); 161NAPI_EXTERN napi_status napi_coerce_to_number(napi_env env, 162 napi_value value, 163 napi_value* result); 164NAPI_EXTERN napi_status napi_coerce_to_object(napi_env env, 165 napi_value value, 166 napi_value* result); 167NAPI_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 172NAPI_EXTERN napi_status napi_get_prototype(napi_env env, 173 napi_value object, 174 napi_value* result); 175NAPI_EXTERN napi_status napi_get_property_names(napi_env env, 176 napi_value object, 177 napi_value* result); 178NAPI_EXTERN napi_status napi_set_property(napi_env env, 179 napi_value object, 180 napi_value key, 181 napi_value value); 182NAPI_EXTERN napi_status napi_has_property(napi_env env, 183 napi_value object, 184 napi_value key, 185 bool* result); 186NAPI_EXTERN napi_status napi_get_property(napi_env env, 187 napi_value object, 188 napi_value key, 189 napi_value* result); 190NAPI_EXTERN napi_status napi_delete_property(napi_env env, 191 napi_value object, 192 napi_value key, 193 bool* result); 194NAPI_EXTERN napi_status napi_has_own_property(napi_env env, 195 napi_value object, 196 napi_value key, 197 bool* result); 198NAPI_EXTERN napi_status napi_set_named_property(napi_env env, 199 napi_value object, 200 const char* utf8name, 201 napi_value value); 202NAPI_EXTERN napi_status napi_has_named_property(napi_env env, 203 napi_value object, 204 const char* utf8name, 205 bool* result); 206NAPI_EXTERN napi_status napi_get_named_property(napi_env env, 207 napi_value object, 208 const char* utf8name, 209 napi_value* result); 210NAPI_EXTERN napi_status napi_set_element(napi_env env, 211 napi_value object, 212 uint32_t index, 213 napi_value value); 214NAPI_EXTERN napi_status napi_has_element(napi_env env, 215 napi_value object, 216 uint32_t index, 217 bool* result); 218NAPI_EXTERN napi_status napi_get_element(napi_env env, 219 napi_value object, 220 uint32_t index, 221 napi_value* result); 222NAPI_EXTERN napi_status napi_delete_element(napi_env env, 223 napi_value object, 224 uint32_t index, 225 bool* result); 226NAPI_EXTERN napi_status 227napi_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 233NAPI_EXTERN napi_status napi_is_array(napi_env env, 234 napi_value value, 235 bool* result); 236NAPI_EXTERN napi_status napi_get_array_length(napi_env env, 237 napi_value value, 238 uint32_t* result); 239 240// Methods to compare values 241NAPI_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 247NAPI_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); 253NAPI_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); 258NAPI_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.) 266NAPI_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 275NAPI_EXTERN napi_status napi_get_new_target(napi_env env, 276 napi_callback_info cbinfo, 277 napi_value* result); 278NAPI_EXTERN napi_status 279napi_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 289NAPI_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); 295NAPI_EXTERN napi_status napi_unwrap(napi_env env, 296 napi_value js_object, 297 void** result); 298NAPI_EXTERN napi_status napi_remove_wrap(napi_env env, 299 napi_value js_object, 300 void** result); 301NAPI_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); 306NAPI_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. 313NAPI_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. 320NAPI_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. 327NAPI_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. 335NAPI_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. 342NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, 343 napi_ref ref, 344 napi_value* result); 345 346NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, 347 napi_handle_scope* result); 348NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, 349 napi_handle_scope scope); 350NAPI_EXTERN napi_status 351napi_open_escapable_handle_scope(napi_env env, 352 napi_escapable_handle_scope* result); 353NAPI_EXTERN napi_status 354napi_close_escapable_handle_scope(napi_env env, 355 napi_escapable_handle_scope scope); 356 357NAPI_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 363NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); 364NAPI_EXTERN napi_status napi_throw_error(napi_env env, 365 const char* code, 366 const char* msg); 367NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, 368 const char* code, 369 const char* msg); 370NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, 371 const char* code, 372 const char* msg); 373NAPI_EXTERN napi_status napi_is_error(napi_env env, 374 napi_value value, 375 bool* result); 376 377// Methods to support catching exceptions 378NAPI_EXTERN napi_status napi_is_exception_pending(napi_env env, bool* result); 379NAPI_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 383NAPI_EXTERN napi_status napi_is_arraybuffer(napi_env env, 384 napi_value value, 385 bool* result); 386NAPI_EXTERN napi_status napi_create_arraybuffer(napi_env env, 387 size_t byte_length, 388 void** data, 389 napi_value* result); 390NAPI_EXTERN napi_status 391napi_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); 397NAPI_EXTERN napi_status napi_get_arraybuffer_info(napi_env env, 398 napi_value arraybuffer, 399 void** data, 400 size_t* byte_length); 401NAPI_EXTERN napi_status napi_is_typedarray(napi_env env, 402 napi_value value, 403 bool* result); 404NAPI_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); 410NAPI_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 418NAPI_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); 423NAPI_EXTERN napi_status napi_is_dataview(napi_env env, 424 napi_value value, 425 bool* result); 426NAPI_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 434NAPI_EXTERN napi_status napi_get_version(napi_env env, uint32_t* result); 435 436// Promises 437NAPI_EXTERN napi_status napi_create_promise(napi_env env, 438 napi_deferred* deferred, 439 napi_value* promise); 440NAPI_EXTERN napi_status napi_resolve_deferred(napi_env env, 441 napi_deferred deferred, 442 napi_value resolution); 443NAPI_EXTERN napi_status napi_reject_deferred(napi_env env, 444 napi_deferred deferred, 445 napi_value rejection); 446NAPI_EXTERN napi_status napi_is_promise(napi_env env, 447 napi_value value, 448 bool* is_promise); 449 450// Running a script 451NAPI_EXTERN napi_status napi_run_script(napi_env env, 452 napi_value script, 453 napi_value* result); 454 455// Memory management 456NAPI_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 463NAPI_EXTERN napi_status napi_create_date(napi_env env, 464 double time, 465 napi_value* result); 466 467NAPI_EXTERN napi_status napi_is_date(napi_env env, 468 napi_value value, 469 bool* is_date); 470 471NAPI_EXTERN napi_status napi_get_date_value(napi_env env, 472 napi_value value, 473 double* result); 474 475// Add finalizer for pointer 476NAPI_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 488NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env, 489 int64_t value, 490 napi_value* result); 491NAPI_EXTERN napi_status napi_create_bigint_uint64(napi_env env, 492 uint64_t value, 493 napi_value* result); 494NAPI_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); 499NAPI_EXTERN napi_status napi_get_value_bigint_int64(napi_env env, 500 napi_value value, 501 int64_t* result, 502 bool* lossless); 503NAPI_EXTERN napi_status napi_get_value_bigint_uint64(napi_env env, 504 napi_value value, 505 uint64_t* result, 506 bool* lossless); 507NAPI_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 514NAPI_EXTERN napi_status 515napi_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 523NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, 524 void* data, 525 napi_finalize finalize_cb, 526 void* finalize_hint); 527 528NAPI_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 534NAPI_EXTERN napi_status napi_detach_arraybuffer(napi_env env, 535 napi_value arraybuffer); 536 537NAPI_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 544NAPI_EXTERN napi_status napi_type_tag_object(napi_env env, 545 napi_value value, 546 const napi_type_tag* type_tag); 547 548NAPI_EXTERN napi_status 549napi_check_object_type_tag(napi_env env, 550 napi_value value, 551 const napi_type_tag* type_tag, 552 bool* result); 553NAPI_EXTERN napi_status napi_object_freeze(napi_env env, 554 napi_value object); 555NAPI_EXTERN napi_status napi_object_seal(napi_env env, 556 napi_value object); 557#endif // NAPI_VERSION >= 8 558 559EXTERN_C_END 560 561#endif // SRC_JS_NATIVE_API_H_ 562