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 FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H 17 #define FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H 18 19 #ifndef NAPI_VERSION 20 #define NAPI_VERSION 8 21 #endif 22 23 #ifndef NAPI_EXPERIMENTAL 24 #define NAPI_EXPERIMENTAL 25 #endif 26 27 #include "common.h" 28 #include "node_api.h" 29 30 #ifdef NAPI_TEST 31 #ifdef _WIN32 32 #define NAPI_INNER_EXTERN __declspec(dllexport) 33 #else 34 #define NAPI_INNER_EXTERN __attribute__((visibility("default"))) 35 #endif 36 #else 37 #ifdef _WIN32 38 #define NAPI_INNER_EXTERN __declspec(deprecated) 39 #else 40 #define NAPI_INNER_EXTERN __attribute__((__deprecated__)) 41 #endif 42 #endif 43 44 NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, napi_value err); 45 46 NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env, 47 const char16_t* str, 48 size_t length, 49 napi_value* result); 50 51 NAPI_EXTERN napi_status napi_get_value_string_utf16(napi_env env, 52 napi_value value, 53 char16_t* buf, 54 size_t bufsize, 55 size_t* result); 56 57 NAPI_EXTERN napi_status napi_type_tag_object(napi_env env, 58 napi_value value, 59 const napi_type_tag* type_tag); 60 61 NAPI_EXTERN napi_status napi_check_object_type_tag(napi_env env, 62 napi_value value, 63 const napi_type_tag* type_tag, 64 bool* result); 65 66 NAPI_INNER_EXTERN napi_status napi_adjust_external_memory(napi_env env, 67 int64_t change_in_bytes, 68 int64_t* adjusted_value); 69 70 71 #ifdef __cplusplus 72 extern "C" { 73 #endif 74 75 /** 76 * @brief Native detach callback of napi_coerce_to_native_binding_object that can be used to 77 * detach the js object and the native object. 78 * 79 * @since 11 80 */ 81 typedef void* (*napi_native_binding_detach_callback)(napi_env env, void* native_object, void* hint); 82 /** 83 * @brief Native attach callback of napi_coerce_to_native_binding_object that can be used to 84 * bind the js object and the native object. 85 * 86 * @since 11 87 */ 88 typedef napi_value (*napi_native_binding_attach_callback)(napi_env env, void* native_object, void* hint); 89 90 NAPI_EXTERN napi_status napi_run_script_path(napi_env env, const char* path, napi_value* result); 91 NAPI_EXTERN napi_status napi_queue_async_work_with_qos(napi_env env, napi_async_work work, napi_qos_t qos); 92 NAPI_EXTERN napi_status napi_load_module(napi_env env, const char* path, napi_value* result); 93 94 /** 95 * @brief The module is loaded through the NAPI. By default, the default object is exported from the module. 96 * 97 * @param env Current running virtual machine context. 98 * @param path Path name of the module to be loaded, like @ohos.hilog. 99 * @param module_info Path names of bundle and module, like com.example.application/entry. 100 * @param result Result of loading a module, which is an exported object of the module. 101 * @return Returns the function execution status. 102 * @since 12 103 */ 104 NAPI_EXTERN napi_status napi_load_module_with_info(napi_env env, 105 const char* path, 106 const char* module_info, 107 napi_value* result); 108 NAPI_EXTERN napi_status napi_get_instance_data(napi_env env, void** data); 109 NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, 110 void* data, 111 napi_finalize finalize_cb, 112 void* finalize_hint); 113 NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); 114 NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); 115 NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(napi_async_cleanup_hook_handle remove_handle); 116 NAPI_EXTERN napi_status napi_add_async_cleanup_hook(napi_env env, 117 napi_async_cleanup_hook hook, 118 void* arg, 119 napi_async_cleanup_hook_handle* remove_handle); 120 NAPI_EXTERN napi_status napi_async_destroy(napi_env env, 121 napi_async_context async_context); 122 NAPI_EXTERN napi_status napi_async_init(napi_env env, 123 napi_value async_resource, 124 napi_value async_resource_name, 125 napi_async_context* result); 126 NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, napi_callback_scope scope); 127 NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, 128 napi_value resource_object, 129 napi_async_context context, 130 napi_callback_scope* result); 131 NAPI_EXTERN napi_status node_api_get_module_file_name(napi_env env, const char** result); 132 // Create JSObject with initial properties given by descriptors, note that property key must be String, 133 // and must can not convert to element_index, also all keys must not duplicate. 134 NAPI_EXTERN napi_status napi_create_object_with_properties(napi_env env, 135 napi_value* result, 136 size_t property_count, 137 const napi_property_descriptor* properties); 138 // Create JSObject with initial properties given by keys and values, note that property key must be String, 139 // and must can not convert to element_index, also all keys must not duplicate. 140 NAPI_EXTERN napi_status napi_create_object_with_named_properties(napi_env env, 141 napi_value* result, 142 size_t property_count, 143 const char** keys, 144 const napi_value* values); 145 /** 146 * @brief This API sets native properties to a object and converts this js object to native binding object. 147 * 148 * @param[in] env Current running virtual machine context. 149 * @param[in] js_object The JavaScript value to coerce. 150 * @param[in] detach_cb Native callback that can be used to detach the js object and the native object. 151 * @param[in] attach_cb Native callback that can be used to bind the js object and the native object. 152 * @param[in] native_object User-provided native instance to pass to thr detach callback and attach callback. 153 * @param[in] hint Optional hint to pass to the detach callback and attach callback. 154 * @return Return the function execution status. 155 * @since 11 156 */ 157 NAPI_EXTERN napi_status napi_coerce_to_native_binding_object(napi_env env, 158 napi_value js_object, 159 napi_native_binding_detach_callback detach_cb, 160 napi_native_binding_attach_callback attach_cb, 161 void* native_object, 162 void* hint); 163 NAPI_EXTERN napi_status napi_add_finalizer(napi_env env, 164 napi_value js_object, 165 void* native_object, 166 napi_finalize finalize_cb, 167 void* finalize_hint, 168 napi_ref* result); 169 /** 170 * @brief Create the ark runtime. 171 * 172 * @param env Indicates the ark runtime environment. 173 * @since 12 174 */ 175 NAPI_EXTERN napi_status napi_create_ark_runtime(napi_env* env); 176 177 /** 178 * @brief Destroy the ark runtime. 179 * 180 * @param env Indicates the ark runtime environment. 181 * @since 12 182 */ 183 NAPI_EXTERN napi_status napi_destroy_ark_runtime(napi_env* env); 184 185 /* 186 * @brief Defines a sendable class. 187 * 188 * @param env: The environment that the API is invoked under. 189 * @param utf8name: Name of the ArkTS constructor function. 190 * @param length: The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated. 191 * @param constructor: Callback function that handles constructing instances of the class. 192 * @param data: Optional data to be passed to the constructor callback as the data property of the callback info. 193 * @param property_count: Number of items in the properties array argument. 194 * @param properties: Array of property descriptors describing static and instance data properties, accessors, and 195 * methods on the class. See napi_property_descriptor. 196 * @param parent: A napi_value representing the Superclass. 197 * @param result: A napi_value representing the constructor function for the class. 198 * @return Return the function execution status. 199 * @since 12 200 */ 201 NAPI_EXTERN napi_status napi_define_sendable_class(napi_env env, 202 const char* utf8name, 203 size_t length, 204 napi_callback constructor, 205 void* data, 206 size_t property_count, 207 const napi_property_descriptor* properties, 208 napi_value parent, 209 napi_value* result); 210 211 /** 212 * @brief Queries a napi_value to check if it is sendable. 213 * 214 * @param env The environment that the API is invoked under. 215 * @param value The napi_value to be checked. 216 * @param result Boolean value that is set to true if napi_value is sendable, false otherwise. 217 * @return Return the function execution status. 218 * @since 12 219 */ 220 NAPI_EXTERN napi_status napi_is_sendable(napi_env env, napi_value value, bool* result); 221 /** 222 * @brief Defines a sendable object. 223 * 224 * @param env The environment that the API is invoked under. 225 * @param property_count The count of object properties. 226 * @param properties Object properties. 227 * @return Return the function execution status. 228 * @since 12 229 */ 230 NAPI_EXTERN napi_status napi_create_sendable_object_with_properties(napi_env env, size_t property_count, 231 const napi_property_descriptor* properties, 232 napi_value* result); 233 /** 234 * @brief Wraps a native instance in a ArkTS object. 235 * 236 * @param env The environment that the API is invoked under. 237 * @param js_object The ArkTS object that will be the wrapper for the native object. 238 * @param native_object The native instance that will be wrapped in the ArkTS object. 239 * @param finalize_lib Optional native callback that can be used to free the native instance when the ArkTS object 240 * has been garbage-collected. 241 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 242 * @return Return the function execution status. 243 * @since 12 244 */ 245 NAPI_EXTERN napi_status napi_wrap_sendable(napi_env env, napi_value js_object, void* native_object, 246 napi_finalize finalize_cb, void* finalize_hint); 247 /** 248 * @brief Wraps a native instance in a ArkTS object. 249 * 250 * @param env The environment that the API is invoked under. 251 * @param js_object The ArkTS object that will be the wrapper for the native object. 252 * @param native_object The native instance that will be wrapped in the ArkTS object. 253 * @param finalize_lib Optional native callback that can be used to free the native instance when the ArkTS object 254 * has been garbage-collected. 255 * @param finalize_hint Optional contextual hint that is passed to the finalize callback. 256 * @param native_binding_size The size of native binding. 257 * @return Return the function execution status. 258 * @since 12 259 */ 260 NAPI_EXTERN napi_status napi_wrap_sendable_with_size(napi_env env, napi_value js_object, void* native_object, 261 napi_finalize finalize_cb, void* finalize_hint, 262 size_t native_binding_size); 263 /** 264 * @brief Retrieves a native instance that was previously wrapped in a ArkTS object. 265 * 266 * @param env The environment that the API is invoked under. 267 * @param js_object The object associated with the native instance. 268 * @param result Pointer to the wrapped native instance. 269 * @return Return the function execution status. 270 * @since 12 271 */ 272 NAPI_EXTERN napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result); 273 /** 274 * @brief Retrieves a native instance that was previously wrapped in a ArkTS object and removes the wrapping. 275 * 276 * @param env The environment that the API is invoked under. 277 * @param js_object The object associated with the native instance. 278 * @param result Pointer to the wrapped native instance. 279 * @return Return the function execution status. 280 * @since 12 281 */ 282 NAPI_EXTERN napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result); 283 /* 284 * @brief Create a sendable array. 285 * 286 * @param env: The environment that the API is invoked under. 287 * @param result: A napi_value representing a sendable array. 288 * @return Return the function execution status. 289 * @since 12 290 */ 291 NAPI_EXTERN napi_status napi_create_sendable_array(napi_env env, napi_value* result); 292 293 /* 294 * @brief Create a sendable array with length. 295 * 296 * @param env: The environment that the API is invoked under. 297 * @param length: The initial length of the sendable array. 298 * @param result: A napi_value representing a sendable array. 299 * @return Return the function execution status. 300 * @since 12 301 */ 302 NAPI_EXTERN napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result); 303 304 /* 305 * @brief Create a sendable arraybuffer. 306 * 307 * @param env: The environment that the API is invoked under. 308 * @param byte_length: The length in bytes of the sendable arraybuffer to create. 309 * @param data: Pointer to the underlying byte buffer of the sendable arraybuffer. 310 * @param result: A napi_value representing a sendable arraybuffer. 311 * @return Return the function execution status. 312 * @since 12 313 */ 314 NAPI_EXTERN napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, 315 void** data, napi_value* result); 316 317 /* 318 * @brief Create a sendable typedarray. 319 * 320 * @param env: The environment that the API is invoked under. 321 * @param type: Scalar datatype of the elements within the sendable typedarray. 322 * @param length: Number of elements in the typedarray. 323 * @param arraybuffer: Sendable arraybuffer underlying the sendable typedarray. 324 * @param byte_offset: The byte offset within the sendable arraybuffer from 325 * which to start projecting the sendable typedarray. 326 * @param result: A napi_value representing a sendable typedarray. 327 * @return Return the function execution status. 328 * @since 12 329 */ 330 NAPI_EXTERN napi_status napi_create_sendable_typedarray(napi_env env, 331 napi_typedarray_type type, 332 size_t length, 333 napi_value arraybuffer, 334 size_t byte_offset, 335 napi_value* result); 336 337 /** 338 * @brief Run the event loop by the given env and running mode in current thread. 339 * 340 * Support to run the native event loop in an asynchronous native thread with the specified running mode. 341 * 342 * @param env Current running virtual machine context. 343 * @param mode Indicates the running mode of the native event loop. 344 * @return Return the function execution status. 345 * @since 12 346 */ 347 NAPI_EXTERN napi_status napi_run_event_loop(napi_env env, napi_event_mode mode); 348 349 /** 350 * @brief Stop the event loop in current thread. 351 * 352 * Support to stop the running event loop in current native thread. 353 * 354 * @param env Current running virtual machine context. 355 * @return Return the function execution status. 356 * @since 12 357 */ 358 NAPI_EXTERN napi_status napi_stop_event_loop(napi_env env); 359 360 /** 361 * @brief Serialize a JS object. 362 * 363 * @param env Current running virtual machine context. 364 * @param object The JavaScript value to serialize. 365 * @param transfer_list List of data to transfer in transfer mode. 366 * @param clone_list List of Sendable data to transfer in clone mode. 367 * @param result Serialization result of the JS object. 368 * @return Returns the function execution status. 369 * @since 12 370 */ 371 NAPI_EXTERN napi_status napi_serialize(napi_env env, 372 napi_value object, 373 napi_value transfer_list, 374 napi_value clone_list, 375 void** result); 376 377 /** 378 * @brief Restore serialization data to a ArkTS object. 379 * 380 * @param env Current running virtual machine context. 381 * @param buffer Data to deserialize. 382 * @param object ArkTS object obtained by deserialization. 383 * @return Returns the function execution status. 384 * @since 12 385 */ 386 NAPI_EXTERN napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object); 387 388 /** 389 * @brief Delete serialization data. 390 * 391 * @param env Current running virtual machine context. 392 * @param buffer Data to delete. 393 * @return Returns the function execution status. 394 * @since 12 395 */ 396 NAPI_EXTERN napi_status napi_delete_serialization_data(napi_env env, void* buffer); 397 398 /** 399 * @brief Dispatch a task with specified priority from a native thread to an ArkTS thread, the task will execute 400 * the given thread safe function. 401 * 402 * @param func Indicates the thread safe function. 403 * @param data Indicates the data anticipated to be transferred to the ArkTS thread. 404 * @param priority Indicates the priority of the task dispatched. 405 * @param isTail Indicates the way of the task dispatched into the native event queue. When "isTail" is true, 406 * the task will be dispatched to the tail of the native event queue. Conversely, when "isTail" is false, the 407 * tasks will be dispatched to the head of the native event queue. 408 * @return Return the function execution status. 409 * @since 12 410 */ 411 NAPI_EXTERN napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 412 void *data, 413 napi_task_priority priority, 414 bool isTail); 415 #ifdef __cplusplus 416 } 417 #endif 418 #endif /* FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H */ 419