include/node/node_api.h

0001 #ifndef SRC_NODE_API_H_
0002 #define SRC_NODE_API_H_
0003
0004 #if defined(BUILDING_NODE_EXTENSION) && !defined(NAPI_EXTERN)
0005 #ifdef _WIN32
0006 // Building native addon against node
0007 #define NAPI_EXTERN __declspec(dllimport)
0008 #elif defined(__wasm__)
0009 #define NAPI_EXTERN __attribute__((__import_module__("napi")))
0010 #endif
0011 #endif
0012 #include "js_native_api.h"
0013 #include "node_api_types.h"
0014
0015 struct uv_loop_s;  // Forward declaration.
0016
0017 #ifdef _WIN32
0018 #define NAPI_MODULE_EXPORT __declspec(dllexport)
0019 #else
0020 #ifdef __EMSCRIPTEN__
0021 #define NAPI_MODULE_EXPORT                                                     \
0022   __attribute__((visibility("default"))) __attribute__((used))
0023 #else
0024 #define NAPI_MODULE_EXPORT __attribute__((visibility("default")))
0025 #endif
0026 #endif
0027
0028 #if defined(__GNUC__)
0029 #define NAPI_NO_RETURN __attribute__((noreturn))
0030 #elif defined(_WIN32)
0031 #define NAPI_NO_RETURN __declspec(noreturn)
0032 #else
0033 #define NAPI_NO_RETURN
0034 #endif
0035
0036 typedef napi_value(NAPI_CDECL* napi_addon_register_func)(napi_env env,
0037                                                          napi_value exports);
0038 typedef int32_t(NAPI_CDECL* node_api_addon_get_api_version_func)(void);
0039
0040 // Used by deprecated registration method napi_module_register.
0041 typedef struct napi_module {
0042   int nm_version;
0043   unsigned int nm_flags;
0044   const char* nm_filename;
0045   napi_addon_register_func nm_register_func;
0046   const char* nm_modname;
0047   void* nm_priv;
0048   void* reserved[4];
0049 } napi_module;
0050
0051 #define NAPI_MODULE_VERSION 1
0052
0053 #define NAPI_MODULE_INITIALIZER_X(base, version)                               \
0054   NAPI_MODULE_INITIALIZER_X_HELPER(base, version)
0055 #define NAPI_MODULE_INITIALIZER_X_HELPER(base, version) base##version
0056
0057 #ifdef __wasm__
0058 #define NAPI_MODULE_INITIALIZER_BASE napi_register_wasm_v
0059 #else
0060 #define NAPI_MODULE_INITIALIZER_BASE napi_register_module_v
0061 #endif
0062
0063 #define NODE_API_MODULE_GET_API_VERSION_BASE node_api_module_get_api_version_v
0064
0065 #define NAPI_MODULE_INITIALIZER                                                \
0066   NAPI_MODULE_INITIALIZER_X(NAPI_MODULE_INITIALIZER_BASE, NAPI_MODULE_VERSION)
0067
0068 #define NODE_API_MODULE_GET_API_VERSION                                        \
0069   NAPI_MODULE_INITIALIZER_X(NODE_API_MODULE_GET_API_VERSION_BASE,              \
0070                             NAPI_MODULE_VERSION)
0071
0072 #define NAPI_MODULE_INIT()                                                     \
0073   EXTERN_C_START                                                               \
0074   NAPI_MODULE_EXPORT int32_t NODE_API_MODULE_GET_API_VERSION(void) {           \
0075     return NAPI_VERSION;                                                       \
0076   }                                                                            \
0077   NAPI_MODULE_EXPORT napi_value NAPI_MODULE_INITIALIZER(napi_env env,          \
0078                                                         napi_value exports);   \
0079   EXTERN_C_END                                                                 \
0080   napi_value NAPI_MODULE_INITIALIZER(napi_env env, napi_value exports)
0081
0082 #define NAPI_MODULE(modname, regfunc)                                          \
0083   NAPI_MODULE_INIT() { return regfunc(env, exports); }
0084
0085 // Deprecated. Use NAPI_MODULE.
0086 #define NAPI_MODULE_X(modname, regfunc, priv, flags)                           \
0087   NAPI_MODULE(modname, regfunc)
0088
0089 EXTERN_C_START
0090
0091 // Deprecated. Replaced by symbol-based registration defined by NAPI_MODULE
0092 // and NAPI_MODULE_INIT macros.
0093 #if defined(__cplusplus) && __cplusplus >= 201402L
0094 [[deprecated]]
0095 #endif
0096 NAPI_EXTERN void NAPI_CDECL
0097 napi_module_register(napi_module* mod);
0098
0099 NAPI_EXTERN NAPI_NO_RETURN void NAPI_CDECL
0100 napi_fatal_error(const char* location,
0101                  size_t location_len,
0102                  const char* message,
0103                  size_t message_len);
0104
0105 // Methods for custom handling of async operations
0106 NAPI_EXTERN napi_status NAPI_CDECL
0107 napi_async_init(napi_env env,
0108                 napi_value async_resource,
0109                 napi_value async_resource_name,
0110                 napi_async_context* result);
0111
0112 NAPI_EXTERN napi_status NAPI_CDECL
0113 napi_async_destroy(napi_env env, napi_async_context async_context);
0114
0115 NAPI_EXTERN napi_status NAPI_CDECL
0116 napi_make_callback(napi_env env,
0117                    napi_async_context async_context,
0118                    napi_value recv,
0119                    napi_value func,
0120                    size_t argc,
0121                    const napi_value* argv,
0122                    napi_value* result);
0123
0124 // Methods to provide node::Buffer functionality with napi types
0125 NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer(napi_env env,
0126                                                       size_t length,
0127                                                       void** data,
0128                                                       napi_value* result);
0129 #ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
0130 NAPI_EXTERN napi_status NAPI_CDECL
0131 napi_create_external_buffer(napi_env env,
0132                             size_t length,
0133                             void* data,
0134                             node_api_nogc_finalize finalize_cb,
0135                             void* finalize_hint,
0136                             napi_value* result);
0137 #endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
0138 NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
0139                                                            size_t length,
0140                                                            const void* data,
0141                                                            void** result_data,
0142                                                            napi_value* result);
0143 NAPI_EXTERN napi_status NAPI_CDECL napi_is_buffer(napi_env env,
0144                                                   napi_value value,
0145                                                   bool* result);
0146 NAPI_EXTERN napi_status NAPI_CDECL napi_get_buffer_info(napi_env env,
0147                                                         napi_value value,
0148                                                         void** data,
0149                                                         size_t* length);
0150
0151 // Methods to manage simple async operations
0152 NAPI_EXTERN napi_status NAPI_CDECL
0153 napi_create_async_work(napi_env env,
0154                        napi_value async_resource,
0155                        napi_value async_resource_name,
0156                        napi_async_execute_callback execute,
0157                        napi_async_complete_callback complete,
0158                        void* data,
0159                        napi_async_work* result);
0160 NAPI_EXTERN napi_status NAPI_CDECL napi_delete_async_work(napi_env env,
0161                                                           napi_async_work work);
0162 NAPI_EXTERN napi_status NAPI_CDECL napi_queue_async_work(node_api_nogc_env env,
0163                                                          napi_async_work work);
0164 NAPI_EXTERN napi_status NAPI_CDECL napi_cancel_async_work(node_api_nogc_env env,
0165                                                           napi_async_work work);
0166
0167 // version management
0168 NAPI_EXTERN napi_status NAPI_CDECL
0169 napi_get_node_version(node_api_nogc_env env, const napi_node_version** version);
0170
0171 #if NAPI_VERSION >= 2
0172
0173 // Return the current libuv event loop for a given environment
0174 NAPI_EXTERN napi_status NAPI_CDECL
0175 napi_get_uv_event_loop(node_api_nogc_env env, struct uv_loop_s** loop);
0176
0177 #endif  // NAPI_VERSION >= 2
0178
0179 #if NAPI_VERSION >= 3
0180
0181 NAPI_EXTERN napi_status NAPI_CDECL napi_fatal_exception(napi_env env,
0182                                                         napi_value err);
0183
0184 NAPI_EXTERN napi_status NAPI_CDECL napi_add_env_cleanup_hook(
0185     node_api_nogc_env env, napi_cleanup_hook fun, void* arg);
0186
0187 NAPI_EXTERN napi_status NAPI_CDECL napi_remove_env_cleanup_hook(
0188     node_api_nogc_env env, napi_cleanup_hook fun, void* arg);
0189
0190 NAPI_EXTERN napi_status NAPI_CDECL
0191 napi_open_callback_scope(napi_env env,
0192                          napi_value resource_object,
0193                          napi_async_context context,
0194                          napi_callback_scope* result);
0195
0196 NAPI_EXTERN napi_status NAPI_CDECL
0197 napi_close_callback_scope(napi_env env, napi_callback_scope scope);
0198
0199 #endif  // NAPI_VERSION >= 3
0200
0201 #if NAPI_VERSION >= 4
0202
0203 // Calling into JS from other threads
0204 NAPI_EXTERN napi_status NAPI_CDECL
0205 napi_create_threadsafe_function(napi_env env,
0206                                 napi_value func,
0207                                 napi_value async_resource,
0208                                 napi_value async_resource_name,
0209                                 size_t max_queue_size,
0210                                 size_t initial_thread_count,
0211                                 void* thread_finalize_data,
0212                                 napi_finalize thread_finalize_cb,
0213                                 void* context,
0214                                 napi_threadsafe_function_call_js call_js_cb,
0215                                 napi_threadsafe_function* result);
0216
0217 NAPI_EXTERN napi_status NAPI_CDECL napi_get_threadsafe_function_context(
0218     napi_threadsafe_function func, void** result);
0219
0220 NAPI_EXTERN napi_status NAPI_CDECL
0221 napi_call_threadsafe_function(napi_threadsafe_function func,
0222                               void* data,
0223                               napi_threadsafe_function_call_mode is_blocking);
0224
0225 NAPI_EXTERN napi_status NAPI_CDECL
0226 napi_acquire_threadsafe_function(napi_threadsafe_function func);
0227
0228 NAPI_EXTERN napi_status NAPI_CDECL napi_release_threadsafe_function(
0229     napi_threadsafe_function func, napi_threadsafe_function_release_mode mode);
0230
0231 NAPI_EXTERN napi_status NAPI_CDECL napi_unref_threadsafe_function(
0232     node_api_nogc_env env, napi_threadsafe_function func);
0233
0234 NAPI_EXTERN napi_status NAPI_CDECL napi_ref_threadsafe_function(
0235     node_api_nogc_env env, napi_threadsafe_function func);
0236
0237 #endif  // NAPI_VERSION >= 4
0238
0239 #if NAPI_VERSION >= 8
0240
0241 NAPI_EXTERN napi_status NAPI_CDECL
0242 napi_add_async_cleanup_hook(node_api_nogc_env env,
0243                             napi_async_cleanup_hook hook,
0244                             void* arg,
0245                             napi_async_cleanup_hook_handle* remove_handle);
0246
0247 NAPI_EXTERN napi_status NAPI_CDECL
0248 napi_remove_async_cleanup_hook(napi_async_cleanup_hook_handle remove_handle);
0249
0250 #endif  // NAPI_VERSION >= 8
0251
0252 #if NAPI_VERSION >= 9
0253
0254 NAPI_EXTERN napi_status NAPI_CDECL
0255 node_api_get_module_file_name(node_api_nogc_env env, const char** result);
0256
0257 #endif  // NAPI_VERSION >= 9
0258
0259 EXTERN_C_END
0260
0261 #endif  // SRC_NODE_API_H_