#ifndef SRC_NODE_API_H_ #define SRC_NODE_API_H_ #include #include #ifndef NAPI_VERSION #ifdef NAPI_EXPERIMENTAL // Use INT_MAX, this should only be consumed by the pre-processor anyway. #define NAPI_VERSION 2147483647 #else // The baseline version for N-API. // The NAPI_VERSION controls which version will be used by default when // compilling a native addon. If the addon developer specifically wants to use // functions available in a new version of N-API that is not yet ported in all // LTS versions, they can set NAPI_VERSION knowing that they have specifically // depended on that version. #define NAPI_VERSION 7 #endif #endif #include "node_api_types.h" struct uv_loop_s; // Forward declaration. #ifdef _WIN32 #ifdef BUILDING_NODE_EXTENSION #ifdef EXTERNAL_NAPI // Building external N-API, or native module against external N-API #define NAPI_EXTERN /* nothing */ #else // Building native module against node with built-in N-API #define NAPI_EXTERN __declspec(dllimport) #endif #else // Building node with built-in N-API #define NAPI_EXTERN __declspec(dllexport) #endif #else #define NAPI_EXTERN /* nothing */ #endif #ifdef _WIN32 # define NAPI_MODULE_EXPORT __declspec(dllexport) #else # define NAPI_MODULE_EXPORT __attribute__((visibility("default"))) #endif #ifdef __GNUC__ #define NAPI_NO_RETURN __attribute__((noreturn)) #else #define NAPI_NO_RETURN #endif typedef napi_value (*napi_addon_register_func)(napi_env env, napi_value exports); typedef struct { int nm_version; unsigned int nm_flags; const char* nm_filename; napi_addon_register_func nm_register_func; const char* nm_modname; void* nm_priv; void* reserved[4]; } napi_module; #define NAPI_MODULE_VERSION 1 #if defined(_MSC_VER) #pragma section(".CRT$XCU", read) #define NAPI_C_CTOR(fn) \ static void __cdecl fn(void); \ __declspec(dllexport, allocate(".CRT$XCU")) void(__cdecl * fn##_)(void) = \ fn; \ static void __cdecl fn(void) #else #define NAPI_C_CTOR(fn) \ static void fn(void) __attribute__((constructor)); \ static void fn(void) #endif #ifdef __cplusplus #define EXTERN_C_START extern "C" { #define EXTERN_C_END } #else #define EXTERN_C_START #define EXTERN_C_END #endif #define NAPI_MODULE_X(modname, regfunc, priv, flags) \ EXTERN_C_START \ static napi_module _module = \ { \ NAPI_MODULE_VERSION, \ flags, \ __FILE__, \ regfunc, \ #modname, \ priv, \ {0}, \ }; \ NAPI_C_CTOR(_register_ ## modname) { \ napi_module_register(&_module); \ } \ EXTERN_C_END #define NAPI_MODULE(modname, regfunc) \ NAPI_MODULE_X(modname, regfunc, NULL, 0) // NOLINT (readability/null_usage) #define NAPI_MODULE_INITIALIZER_BASE napi_register_module_v #define NAPI_MODULE_INITIALIZER_X(base, version) \ NAPI_MODULE_INITIALIZER_X_HELPER(base, version) #define NAPI_MODULE_INITIALIZER_X_HELPER(base, version) base##version #define NAPI_MODULE_INITIALIZER \ NAPI_MODULE_INITIALIZER_X(NAPI_MODULE_INITIALIZER_BASE, \ NAPI_MODULE_VERSION) #define NAPI_MODULE_INIT() \ EXTERN_C_START \ NAPI_MODULE_EXPORT napi_value \ NAPI_MODULE_INITIALIZER(napi_env env, napi_value exports); \ EXTERN_C_END \ NAPI_MODULE(NODE_GYP_MODULE_NAME, NAPI_MODULE_INITIALIZER) \ napi_value NAPI_MODULE_INITIALIZER(napi_env env, \ napi_value exports) #define NAPI_AUTO_LENGTH SIZE_MAX EXTERN_C_START NAPI_EXTERN void napi_module_register(napi_module* mod); NAPI_EXTERN napi_status napi_get_last_error_info(napi_env env, const napi_extended_error_info** result); NAPI_EXTERN NAPI_NO_RETURN void napi_fatal_error(const char* location, size_t location_len, const char* message, size_t message_len); // Getters for defined singletons NAPI_EXTERN napi_status napi_get_undefined(napi_env env, napi_value* result); NAPI_EXTERN napi_status napi_get_null(napi_env env, napi_value* result); NAPI_EXTERN napi_status napi_get_global(napi_env env, napi_value* result); NAPI_EXTERN napi_status napi_get_boolean(napi_env env, bool value, napi_value* result); // Methods to create Primitive types/Objects NAPI_EXTERN napi_status napi_create_object(napi_env env, napi_value* result); NAPI_EXTERN napi_status napi_create_array(napi_env env, napi_value* result); NAPI_EXTERN napi_status napi_create_array_with_length(napi_env env, size_t length, napi_value* result); NAPI_EXTERN napi_status napi_create_double(napi_env env, double value, napi_value* result); NAPI_EXTERN napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result); NAPI_EXTERN napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result); NAPI_EXTERN napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result); NAPI_EXTERN napi_status napi_create_string_latin1(napi_env env, const char* str, size_t length, napi_value* result); NAPI_EXTERN napi_status napi_create_string_utf8(napi_env env, const char* str, size_t length, napi_value* result); NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, const char16_t* str, size_t length, napi_value* result); NAPI_EXTERN napi_status napi_create_symbol(napi_env env, napi_value description, napi_value* result); NAPI_EXTERN napi_status napi_create_function(napi_env env, const char* utf8name, size_t length, napi_callback cb, void* data, napi_value* result); NAPI_EXTERN napi_status napi_create_error(napi_env env, napi_value code, napi_value msg, napi_value* result); NAPI_EXTERN napi_status napi_create_type_error(napi_env env, napi_value code, napi_value msg, napi_value* result); NAPI_EXTERN napi_status napi_create_range_error(napi_env env, napi_value code, napi_value msg, napi_value* result); // Methods to get the native napi_value from Primitive type NAPI_EXTERN napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result); NAPI_EXTERN napi_status napi_get_value_double(napi_env env, napi_value value, double* result); NAPI_EXTERN napi_status napi_get_value_int32(napi_env env, napi_value value, int32_t* result); NAPI_EXTERN napi_status napi_get_value_uint32(napi_env env, napi_value value, uint32_t* result); NAPI_EXTERN napi_status napi_get_value_int64(napi_env env, napi_value value, int64_t* result); NAPI_EXTERN napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result); // Copies LATIN-1 encoded bytes from a string into a buffer. NAPI_EXTERN napi_status napi_get_value_string_latin1(napi_env env, napi_value value, char* buf, size_t bufsize, size_t* result); // Copies UTF-8 encoded bytes from a string into a buffer. NAPI_EXTERN napi_status napi_get_value_string_utf8(napi_env env, napi_value value, char* buf, size_t bufsize, size_t* result); // Copies UTF-16 encoded bytes from a string into a buffer. NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env, napi_value value, char16_t* buf, size_t bufsize, size_t* result); // Methods to coerce values // These APIs may execute user scripts NAPI_EXTERN napi_status napi_coerce_to_bool(napi_env env, napi_value value, napi_value* result); NAPI_EXTERN napi_status napi_coerce_to_number(napi_env env, napi_value value, napi_value* result); NAPI_EXTERN napi_status napi_coerce_to_object(napi_env env, napi_value value, napi_value* result); NAPI_EXTERN napi_status napi_coerce_to_string(napi_env env, napi_value value, napi_value* result); // Methods to work with Objects NAPI_EXTERN napi_status napi_get_prototype(napi_env env, napi_value object, napi_value* result); NAPI_EXTERN napi_status napi_get_property_names(napi_env env, napi_value object, napi_value* result); NAPI_EXTERN napi_status napi_set_property(napi_env env, napi_value object, napi_value key, napi_value value); NAPI_EXTERN napi_status napi_has_property(napi_env env, napi_value object, napi_value key, bool* result); NAPI_EXTERN napi_status napi_get_property(napi_env env, napi_value object, napi_value key, napi_value* result); NAPI_EXTERN napi_status napi_delete_property(napi_env env, napi_value object, napi_value key, bool* result); NAPI_EXTERN napi_status napi_has_own_property(napi_env env, napi_value object, napi_value key, bool* result); NAPI_EXTERN napi_status napi_set_named_property(napi_env env, napi_value object, const char* utf8name, napi_value value); NAPI_EXTERN napi_status napi_has_named_property(napi_env env, napi_value object, const char* utf8name, bool* result); NAPI_EXTERN napi_status napi_get_named_property(napi_env env, napi_value object, const char* utf8name, napi_value* result); NAPI_EXTERN napi_status napi_set_element(napi_env env, napi_value object, uint32_t index, napi_value value); NAPI_EXTERN napi_status napi_has_element(napi_env env, napi_value object, uint32_t index, bool* result); NAPI_EXTERN napi_status napi_get_element(napi_env env, napi_value object, uint32_t index, napi_value* result); NAPI_EXTERN napi_status napi_delete_element(napi_env env, napi_value object, uint32_t index, bool* result); NAPI_EXTERN napi_status napi_define_properties(napi_env env, napi_value object, size_t property_count, const napi_property_descriptor* properties); // Methods to work with Arrays NAPI_EXTERN napi_status napi_is_array(napi_env env, napi_value value, bool* result); NAPI_EXTERN napi_status napi_get_array_length(napi_env env, napi_value value, uint32_t* result); // Methods to compare values NAPI_EXTERN napi_status napi_strict_equals(napi_env env, napi_value lhs, napi_value rhs, bool* result); // Methods to work with Functions NAPI_EXTERN napi_status napi_call_function(napi_env env, napi_value recv, napi_value func, size_t argc, const napi_value* argv, napi_value* result); NAPI_EXTERN napi_status napi_new_instance(napi_env env, napi_value constructor, size_t argc, const napi_value* argv, napi_value* result); NAPI_EXTERN napi_status napi_instanceof(napi_env env, napi_value object, napi_value constructor, bool* result); // Methods to work with napi_callbacks // Gets all callback info in a single call. (Ugly, but faster.) NAPI_EXTERN napi_status napi_get_cb_info( napi_env env, // [in] NAPI environment handle napi_callback_info cbinfo, // [in] Opaque callback-info handle size_t* argc, // [in-out] Specifies the size of the provided argv array // and receives the actual count of args. napi_value* argv, // [out] Array of values napi_value* this_arg, // [out] Receives the JS 'this' arg for the call void** data); // [out] Receives the data pointer for the callback. NAPI_EXTERN napi_status napi_get_new_target(napi_env env, napi_callback_info cbinfo, napi_value* result); NAPI_EXTERN napi_status napi_define_class(napi_env env, const char* utf8name, size_t length, napi_callback constructor, void* data, size_t property_count, const napi_property_descriptor* properties, napi_value* result); // Methods to work with external data objects NAPI_EXTERN napi_status napi_wrap(napi_env env, napi_value js_object, void* native_object, napi_finalize finalize_cb, void* finalize_hint, napi_ref* result); NAPI_EXTERN napi_status napi_unwrap(napi_env env, napi_value js_object, void** result); NAPI_EXTERN napi_status napi_remove_wrap(napi_env env, napi_value js_object, void** result); NAPI_EXTERN napi_status napi_create_external(napi_env env, void* data, napi_finalize finalize_cb, void* finalize_hint, napi_value* result); NAPI_EXTERN napi_status napi_get_value_external(napi_env env, napi_value value, void** result); // Methods to control object lifespan // Set initial_refcount to 0 for a weak reference, >0 for a strong reference. NAPI_EXTERN napi_status napi_create_reference(napi_env env, napi_value value, uint32_t initial_refcount, napi_ref* result); // Deletes a reference. The referenced value is released, and may // be GC'd unless there are other references to it. NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); // Increments the reference count, optionally returning the resulting count. // After this call the reference will be a strong reference because its // refcount is >0, and the referenced object is effectively "pinned". // Calling this when the refcount is 0 and the object is unavailable // results in an error. NAPI_EXTERN napi_status napi_reference_ref(napi_env env, napi_ref ref, uint32_t* result); // Decrements the reference count, optionally returning the resulting count. // If the result is 0 the reference is now weak and the object may be GC'd // at any time if there are no other references. Calling this when the // refcount is already 0 results in an error. NAPI_EXTERN napi_status napi_reference_unref(napi_env env, napi_ref ref, uint32_t* result); // Attempts to get a referenced value. If the reference is weak, // the value might no longer be available, in that case the call // is still successful but the result is NULL. NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, napi_ref ref, napi_value* result); NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, napi_handle_scope* result); NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, napi_handle_scope scope); NAPI_EXTERN napi_status napi_open_escapable_handle_scope(napi_env env, napi_escapable_handle_scope* result); NAPI_EXTERN napi_status napi_close_escapable_handle_scope(napi_env env, napi_escapable_handle_scope scope); NAPI_EXTERN napi_status napi_escape_handle(napi_env env, napi_escapable_handle_scope scope, napi_value escapee, napi_value* result); // Methods to support error handling NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); NAPI_EXTERN napi_status napi_throw_error(napi_env env, const char* code, const char* msg); NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, const char* code, const char* msg); NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, const char* code, const char* msg); NAPI_EXTERN napi_status napi_is_error(napi_env env, napi_value value, bool* result); // Methods to support catching exceptions NAPI_EXTERN napi_status napi_is_exception_pending(napi_env env, bool* result); NAPI_EXTERN napi_status napi_get_and_clear_last_exception(napi_env env, napi_value* result); // Methods to provide node::Buffer functionality with napi types NAPI_EXTERN napi_status napi_create_buffer(napi_env env, size_t length, void** data, napi_value* result); NAPI_EXTERN napi_status napi_create_external_buffer(napi_env env, size_t length, void* data, napi_finalize finalize_cb, void* finalize_hint, napi_value* result); NAPI_EXTERN napi_status napi_create_buffer_copy(napi_env env, size_t length, const void* data, void** result_data, napi_value* result); NAPI_EXTERN napi_status napi_is_buffer(napi_env env, napi_value value, bool* result); NAPI_EXTERN napi_status napi_get_buffer_info(napi_env env, napi_value value, void** data, size_t* length); // Methods to work with array buffers and typed arrays NAPI_EXTERN napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result); NAPI_EXTERN napi_status napi_create_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result); NAPI_EXTERN napi_status napi_create_external_arraybuffer(napi_env env, void* external_data, size_t byte_length, napi_finalize finalize_cb, void* finalize_hint, napi_value* result); NAPI_EXTERN napi_status napi_get_arraybuffer_info(napi_env env, napi_value arraybuffer, void** data, size_t* byte_length); NAPI_EXTERN napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result); NAPI_EXTERN napi_status napi_create_typedarray(napi_env env, napi_typedarray_type type, size_t length, napi_value arraybuffer, size_t byte_offset, napi_value* result); NAPI_EXTERN napi_status napi_get_typedarray_info(napi_env env, napi_value typedarray, napi_typedarray_type* type, size_t* length, void** data, napi_value* arraybuffer, size_t* byte_offset); NAPI_EXTERN napi_status napi_create_dataview(napi_env env, size_t length, napi_value arraybuffer, size_t byte_offset, napi_value* result); NAPI_EXTERN napi_status napi_is_dataview(napi_env env, napi_value value, bool* result); NAPI_EXTERN napi_status napi_get_dataview_info(napi_env env, napi_value dataview, size_t* bytelength, void** data, napi_value* arraybuffer, size_t* byte_offset); // Methods to manage simple async operations NAPI_EXTERN napi_status napi_create_async_work(napi_env env, napi_value async_resource, napi_value async_resource_name, napi_async_execute_callback execute, napi_async_complete_callback complete, void* data, napi_async_work* result); NAPI_EXTERN napi_status napi_delete_async_work(napi_env env, napi_async_work work); NAPI_EXTERN napi_status napi_queue_async_work(napi_env env, napi_async_work work); NAPI_EXTERN napi_status napi_cancel_async_work(napi_env env, napi_async_work work); // Methods for custom handling of async operations NAPI_EXTERN napi_status napi_async_init(napi_env env, napi_value async_resource, napi_value async_resource_name, napi_async_context* result); NAPI_EXTERN napi_status napi_async_destroy(napi_env env, napi_async_context async_context); NAPI_EXTERN napi_status napi_make_callback(napi_env env, napi_async_context async_context, napi_value recv, napi_value func, size_t argc, const napi_value* argv, napi_value* result); // version management NAPI_EXTERN napi_status napi_get_version(napi_env env, uint32_t* result); NAPI_EXTERN napi_status napi_get_node_version(napi_env env, const napi_node_version** version); // Promises NAPI_EXTERN napi_status napi_create_promise(napi_env env, napi_deferred* deferred, napi_value* promise); NAPI_EXTERN napi_status napi_resolve_deferred(napi_env env, napi_deferred deferred, napi_value resolution); NAPI_EXTERN napi_status napi_reject_deferred(napi_env env, napi_deferred deferred, napi_value rejection); NAPI_EXTERN napi_status napi_is_promise(napi_env env, napi_value promise, bool* is_promise); // Memory management NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, int64_t change_in_bytes, int64_t* adjusted_value); // Running a script NAPI_EXTERN napi_status napi_run_script(napi_env env, napi_value script, napi_value* result); #if NAPI_VERSION >= 2 // Return the current libuv event loop for a given environment NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, struct uv_loop_s** loop); #endif // NAPI_VERSION >= 2 #if NAPI_VERSION >= 3 NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, napi_value resource_object, napi_async_context context, napi_callback_scope* result); NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, napi_callback_scope scope); NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, napi_value err); NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); #endif // NAPI_VERSION >= 3 #if NAPI_VERSION >= 4 // Calling into JS from other threads NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env, napi_value func, napi_value async_resource, napi_value async_resource_name, size_t max_queue_size, size_t initial_thread_count, void* thread_finalize_data, napi_finalize thread_finalize_cb, void* context, napi_threadsafe_function_call_js call_js_cb, napi_threadsafe_function* result); NAPI_EXTERN napi_status napi_get_threadsafe_function_context(napi_threadsafe_function func, void** result); NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, void* data, napi_threadsafe_function_call_mode is_blocking); NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); NAPI_EXTERN napi_status napi_release_threadsafe_function(napi_threadsafe_function func, napi_threadsafe_function_release_mode mode); NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func); NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func); #endif // NAPI_VERSION >= 4 #if NAPI_VERSION >= 5 // Dates NAPI_EXTERN napi_status napi_create_date(napi_env env, double time, napi_value* result); NAPI_EXTERN napi_status napi_is_date(napi_env env, napi_value value, bool* is_date); NAPI_EXTERN napi_status napi_get_date_value(napi_env env, napi_value value, double* result); // Add finalizer for pointer NAPI_EXTERN napi_status napi_add_finalizer(napi_env env, napi_value js_object, void* native_object, napi_finalize finalize_cb, void* finalize_hint, napi_ref* result); #endif // NAPI_VERSION >= 5 #if NAPI_VERSION >= 6 // BigInt NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env, int64_t value, napi_value* result); NAPI_EXTERN napi_status napi_create_bigint_uint64(napi_env env, uint64_t value, napi_value* result); NAPI_EXTERN napi_status napi_create_bigint_words(napi_env env, int sign_bit, size_t word_count, const uint64_t* words, napi_value* result); NAPI_EXTERN napi_status napi_get_value_bigint_int64(napi_env env, napi_value value, int64_t* result, bool* lossless); NAPI_EXTERN napi_status napi_get_value_bigint_uint64(napi_env env, napi_value value, uint64_t* result, bool* lossless); NAPI_EXTERN napi_status napi_get_value_bigint_words(napi_env env, napi_value value, int* sign_bit, size_t* word_count, uint64_t* words); // Instance data NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, void* data, napi_finalize finalize_cb, void* finalize_hint); NAPI_EXTERN napi_status napi_get_instance_data(napi_env env, void** data); // Object NAPI_EXTERN napi_status napi_get_all_property_names(napi_env env, napi_value object, napi_key_collection_mode key_mode, napi_key_filter key_filter, napi_key_conversion key_conversion, napi_value* result); #endif // NAPI_VERSION >= 6 #if NAPI_VERSION >= 7 // ArrayBuffer detaching NAPI_EXTERN napi_status napi_detach_arraybuffer(napi_env env, napi_value arraybuffer); NAPI_EXTERN napi_status napi_is_detached_arraybuffer(napi_env env, napi_value value, bool* result); #endif // NAPI_VERSION >= 7 EXTERN_C_END #endif // SRC_NODE_API_H_