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_INNER_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 typedef void* (*napi_native_binding_detach_callback)(napi_env env, void* native_object, void* hint); 76 typedef napi_value (*napi_native_binding_attach_callback)(napi_env env, void* native_object, void* hint); 77 78 NAPI_EXTERN napi_status napi_run_script_path(napi_env env, const char* path, napi_value* result); 79 NAPI_EXTERN napi_status napi_queue_async_work_with_qos(napi_env env, napi_async_work work, napi_qos_t qos); 80 NAPI_EXTERN napi_status napi_load_module(napi_env env, const char* path, napi_value* result); 81 82 /** 83 * @brief The module is loaded through the NAPI. By default, the default object is exported from the module. 84 * 85 * @param env Current running virtual machine context. 86 * @param path Path name of the module to be loaded, like @ohos.hilog. 87 * @param module_info Path names of bundle and module, like com.example.application/entry. 88 * @param result Result of loading a module, which is an exported object of the module. 89 * @return Returns the function execution status. 90 * @since 12 91 */ 92 NAPI_EXTERN napi_status napi_load_module_with_info(napi_env env, 93 const char* path, 94 const char* module_info, 95 napi_value* result); 96 NAPI_EXTERN napi_status napi_get_instance_data(napi_env env, void** data); 97 NAPI_EXTERN napi_status napi_set_instance_data(napi_env env, 98 void* data, 99 napi_finalize finalize_cb, 100 void* finalize_hint); 101 NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); 102 NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, void (*fun)(void* arg), void* arg); 103 NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(napi_async_cleanup_hook_handle remove_handle); 104 NAPI_EXTERN napi_status napi_add_async_cleanup_hook(napi_env env, 105 napi_async_cleanup_hook hook, 106 void* arg, 107 napi_async_cleanup_hook_handle* remove_handle); 108 NAPI_EXTERN napi_status napi_async_destroy(napi_env env, 109 napi_async_context async_context); 110 NAPI_EXTERN napi_status napi_async_init(napi_env env, 111 napi_value async_resource, 112 napi_value async_resource_name, 113 napi_async_context* result); 114 NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, napi_callback_scope scope); 115 NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, 116 napi_value resource_object, 117 napi_async_context context, 118 napi_callback_scope* result); 119 NAPI_EXTERN napi_status node_api_get_module_file_name(napi_env env, const char** result); 120 // Create JSObject with initial properties given by descriptors, note that property key must be String, 121 // and must can not convert to element_index, also all keys must not duplicate. 122 NAPI_EXTERN napi_status napi_create_object_with_properties(napi_env env, 123 napi_value* result, 124 size_t property_count, 125 const napi_property_descriptor* properties); 126 // Create JSObject with initial properties given by keys and values, note that property key must be String, 127 // and must can not convert to element_index, also all keys must not duplicate. 128 NAPI_EXTERN napi_status napi_create_object_with_named_properties(napi_env env, 129 napi_value* result, 130 size_t property_count, 131 const char** keys, 132 const napi_value* values); 133 NAPI_EXTERN napi_status napi_coerce_to_native_binding_object(napi_env env, 134 napi_value js_object, 135 napi_native_binding_detach_callback detach_cb, 136 napi_native_binding_attach_callback attach_cb, 137 void* native_object, 138 void* hint); 139 NAPI_EXTERN napi_status napi_add_finalizer(napi_env env, 140 napi_value js_object, 141 void* native_object, 142 napi_finalize finalize_cb, 143 void* finalize_hint, 144 napi_ref* result); 145 /** 146 * @brief Create the ark runtime. 147 * 148 * @param env Indicates the ark runtime environment. 149 * @since 12 150 */ 151 NAPI_EXTERN napi_status napi_create_ark_runtime(napi_env* env); 152 153 /** 154 * @brief Destroy the ark runtime. 155 * 156 * @param env Indicates the ark runtime environment. 157 * @since 12 158 */ 159 NAPI_EXTERN napi_status napi_destroy_ark_runtime(napi_env* env); 160 161 /* 162 * @brief Defines a sendable class. 163 * 164 * @param env: The environment that the API is invoked under. 165 * @param utf8name: Name of the ArkTS constructor function. 166 * @param length: The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated. 167 * @param constructor: Callback function that handles constructing instances of the class. 168 * @param data: Optional data to be passed to the constructor callback as the data property of the callback info. 169 * @param property_count: Number of items in the properties array argument. 170 * @param properties: Array of property descriptors describing static and instance data properties, accessors, and 171 * methods on the class. See napi_property_descriptor. 172 * @param parent: A napi_value representing the Superclass. 173 * @param result: A napi_value representing the constructor function for the class. 174 * @return Return the function execution status. 175 * @since 12 176 */ 177 NAPI_EXTERN napi_status napi_define_sendable_class(napi_env env, 178 const char* utf8name, 179 size_t length, 180 napi_callback constructor, 181 void* data, 182 size_t property_count, 183 const napi_property_descriptor* properties, 184 napi_value parent, 185 napi_value* result); 186 187 /** 188 * @brief Queries a napi_value to check if it is sendable. 189 * 190 * @param env The environment that the API is invoked under. 191 * @param value The napi_value to be checked. 192 * @param result Boolean value that is set to true if napi_value is sendable, false otherwise. 193 * @return Return the function execution status. 194 * @since 12 195 */ 196 NAPI_EXTERN napi_status napi_is_sendable(napi_env env, napi_value value, bool* result); 197 198 /** 199 * @brief Run the event loop by the given env and running mode in current thread. 200 * 201 * Support to run the native event loop in an asynchronous native thread with the specified running mode. 202 * 203 * @param env Current running virtual machine context. 204 * @param mode Indicates the running mode of the native event loop. 205 * @return Return the function execution status. 206 * @since 12 207 */ 208 NAPI_EXTERN napi_status napi_run_event_loop(napi_env env, napi_event_mode mode); 209 210 /** 211 * @brief Stop the event loop in current thread. 212 * 213 * Support to stop the running event loop in current native thread. 214 * 215 * @param env Current running virtual machine context. 216 * @return Return the function execution status. 217 * @since 12 218 */ 219 NAPI_EXTERN napi_status napi_stop_event_loop(napi_env env); 220 221 /** 222 * @brief Serialize a JS object. 223 * 224 * @param env Current running virtual machine context. 225 * @param object The JavaScript value to serialize. 226 * @param transfer_list List of data to transfer in transfer mode. 227 * @param clone_list List of Sendable data to transfer in clone mode. 228 * @param result Serialization result of the JS object. 229 * @return Returns the function execution status. 230 * @since 12 231 */ 232 NAPI_EXTERN napi_status napi_serialize(napi_env env, 233 napi_value object, 234 napi_value transfer_list, 235 napi_value clone_list, 236 void** result); 237 238 /** 239 * @brief Restore serialization data to a ArkTS object. 240 * 241 * @param env Current running virtual machine context. 242 * @param buffer Data to deserialize. 243 * @param object ArkTS object obtained by deserialization. 244 * @return Returns the function execution status. 245 * @since 12 246 */ 247 NAPI_EXTERN napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object); 248 249 /** 250 * @brief Delete serialization data. 251 * 252 * @param env Current running virtual machine context. 253 * @param buffer Data to delete. 254 * @return Returns the function execution status. 255 * @since 12 256 */ 257 NAPI_EXTERN napi_status napi_delete_serialization_data(napi_env env, void* buffer); 258 259 /** 260 * @brief Dispatch a task with specified priority from a native thread to an ArkTS thread, the task will execute 261 * the given thread safe function. 262 * 263 * @param func Indicates the thread safe function. 264 * @param data Indicates the data anticipated to be transferred to the ArkTS thread. 265 * @param priority Indicates the priority of the task dispatched. 266 * @param isTail Indicates the way of the task dispatched into the native event queue. When "isTail" is true, 267 * the task will be dispatched to the tail of the native event queue. Conversely, when "isTail" is false, the 268 * tasks will be dispatched to the head of the native event queue. 269 * @return Return the function execution status. 270 * @since 12 271 */ 272 NAPI_EXTERN napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 273 void *data, 274 napi_task_priority priority, 275 bool isTail); 276 #ifdef __cplusplus 277 } 278 #endif 279 #endif /* FOUNDATION_ACE_NAPI_INTERFACES_KITS_NAPI_NATIVE_API_H */ 280