1 /* 2 * Copyright (c) 2024 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 /** 17 * @addtogroup ArkUI_NativeModule 18 * @{ 19 * 20 * @brief Provides UI capabilities of ArkUI on the native side, such as UI component creation and destruction, 21 * tree node operations, attribute setting, and event listening. 22 * 23 * @since 12 24 */ 25 26 /** 27 * @file native_node_napi.h 28 * 29 * @brief 提供ArkTS侧的FrameNode转换NodeHandle的方式。 30 * 31 * @library libace_ndk.z.so 32 * @syscap SystemCapability.ArkUI.ArkUI.Full 33 * @since 12 34 */ 35 36 #ifndef ARKUI_NATIVE_NODE_NAPI_H 37 #define ARKUI_NATIVE_NODE_NAPI_H 38 39 #include "napi/native_api.h" 40 #include "native_type.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 int32_t OH_ArkUI_GetNodeHandleFromNapiValue(napi_env env, napi_value value, ArkUI_NodeHandle* handle); 47 48 /** 49 * @brief 获取ArkTS侧创建的UIContext对象映射到native侧的ArkUI_ContextHandle。 50 * 51 * @param env napi的环境指针。 52 * @param value ArkTS侧创建的context对象。 53 * @param context ArkUI_ContextHandle指针。 54 * @return 0 - 成功。 55 * 401 - 函数参数异常。 56 * @since 12 57 */ 58 int32_t OH_ArkUI_GetContextFromNapiValue(napi_env env, napi_value value, ArkUI_ContextHandle* context); 59 60 /** 61 * @brief 获取ArkTS侧创建的NodeContent对象映射到native侧的ArkUI_NodeContentHandle。 62 * 63 * @param env napi的环境指针。 64 * @param value ArkTS侧创建的NodeContent对象。 65 * @param context ArkUI_NodeContentHandle指针。 66 * @return 0 - 成功。 67 * 401 - 函数参数异常。 68 * @since 12 69 */ 70 int32_t OH_ArkUI_GetNodeContentFromNapiValue(napi_env env, napi_value value, ArkUI_NodeContentHandle* content); 71 72 /** 73 * @brief Initialize the ArkTS method for the specified env environment. Cannot be called on 74 * the non-UI thread. Checking for non-UI thread calls will abort. 75 * 76 * @param env napi environment pointer. 77 * @return The error code. 78 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 79 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if env is null or failed to set the whitelist. 80 * {@link ARKUI_ERROR_CODE_CAPI_INIT_ERROR} if the CAPI init error. 81 * @since 20 82 */ 83 ArkUI_ErrorCode OH_ArkUI_InitModuleForArkTSEnv(napi_env env); 84 85 /** 86 * @brief Notify the specified env environment is invalid. Cannot be called on 87 * the non-UI thread. Checking for non-UI thread calls will abort. 88 * 89 * @param env napi environment pointer. 90 * @since 20 91 */ 92 void OH_ArkUI_NotifyArkTSEnvDestroy(napi_env env); 93 94 /** 95 * @brief Obtain the ID of the Navigation component where the node is located. 96 * 97 * @param node The node. 98 * @param buffer The buffer to which NavigationID writes to the memory, 99 * memory space needs to be allocated by the developer. 100 * @param bufferSize The buffer size 101 * @param writeLength Indicates the string length actually written to the buffer 102 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 103 * Indicates the minimum buffer size that can accommodate the target 104 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 105 * @return The error code. 106 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 107 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 108 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 109 * this may be because the node is not in Navigation. 110 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 111 * @since 12 112 */ 113 ArkUI_ErrorCode OH_ArkUI_GetNavigationId( 114 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 115 116 /** 117 * @brief Obtain the name of the NavDestination component where the node is located. 118 * 119 * @param node The node. 120 * @param buffer The buffer to which NavDestination name writes to the memory, 121 * memory space needs to be allocated by the developer. 122 * @param bufferSize The buffer size 123 * @param writeLength Indicates the string length actually written to the buffer 124 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 125 * Indicates the minimum buffer size that can accommodate the target 126 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 127 * @return The error code. 128 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 129 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 130 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 131 * this may be because the node is not in Navigation. 132 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 133 * @since 12 134 */ 135 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationName( 136 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 137 138 /** 139 * @brief Based on the given index value, obtain the length of the Navigation stack where the node is located. 140 * 141 * @param node The node. 142 * @param length The length of the stack. After the operation succeeds, the result is written back to this parameter. 143 * @return The error code. 144 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 145 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or length is null. 146 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 147 * this may be because the node is not in Navigation. 148 * @since 12 149 */ 150 ArkUI_ErrorCode OH_ArkUI_GetNavStackLength(ArkUI_NodeHandle node, int32_t* length); 151 152 /** 153 * @brief Based on the given index value, obtain the page name of the corresponding position 154 * in the navigation stack where the node is located. 155 * Index values are counted from 0, with 0 being the bottom of the stack. 156 * 157 * @param node The node. 158 * @param index The index of the NavDestination in the stack is queried. 159 * @param buffer The buffer to which NavDestination index writes to the memory, 160 * memory space needs to be allocated by the developer. 161 * @param bufferSize The buffer size 162 * @param writeLength Indicates the string length actually written to the buffer 163 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 164 * Indicates the minimum buffer size that can accommodate the target 165 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 166 * @return The error code. 167 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 168 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 169 * {@link ARKUI_ERROR_CODE_NODE_INDEX_INVALID} if index is an invalid value. 170 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 171 * this may be because the node is not in Navigation. 172 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 173 * @since 12 174 */ 175 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationNameByIndex( 176 ArkUI_NodeHandle node, int32_t index, char* buffer, int32_t bufferSize, int32_t* writeLength); 177 178 /** 179 * @brief Obtain the ID of the NavDestination component where the node is located. 180 * 181 * @param node The node. 182 * @param buffer The buffer to which NavDestination ID writes to the memory, 183 * memory space needs to be allocated by the developer. 184 * @param bufferSize The buffer size 185 * @param writeLength Indicates the string length actually written to the buffer 186 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 187 * Indicates the minimum buffer size that can accommodate the target 188 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 189 * @return The error code. 190 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 191 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 192 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 193 * this may be because the node is not in Navigation. 194 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 195 * @since 12 196 */ 197 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationId( 198 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 199 200 /** 201 * @brief Obtain the state of the NavDestination component where the node is located. 202 * 203 * @param node The node. 204 * @param state The state value of NavDestination is written back into this parameter. 205 * @return The error code. 206 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 207 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 208 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 209 * this may be because the node is not in Navigation. 210 * @since 12 211 */ 212 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationState(ArkUI_NodeHandle node, ArkUI_NavDestinationState* state); 213 214 /** 215 * @brief Obtain the index of the NavDestination component on the Navigation stack where the node is located. 216 * 217 * @param node The node. 218 * @param index Index value, counted from 0. 219 * @return The error code. 220 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 221 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 222 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 223 * this may be because the node is not in Navigation. 224 * @since 12 225 */ 226 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationIndex(ArkUI_NodeHandle node, int32_t* index); 227 228 /** 229 * @brief Obtain the parameters of the NavDestination component where the node is located. 230 * 231 * @param node The node. 232 * @return The parameters. 233 * If a null pointer is returned, it may be because the node is empty or the parameters does not exist. 234 * @since 12 235 */ 236 napi_value OH_ArkUI_GetNavDestinationParam(ArkUI_NodeHandle node); 237 238 /** 239 * @brief Obtain the index of the page where the node resides in the Router page stack. 240 * 241 * @param node The node. 242 * @param index Index value, counted from 1. 243 * @return The error code. 244 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 245 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 246 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 247 * this may be because the node is not in RouterPage. 248 * @since 12 249 */ 250 ArkUI_ErrorCode OH_ArkUI_GetRouterPageIndex(ArkUI_NodeHandle node, int32_t* index); 251 252 /** 253 * @brief Obtain the name of the page where the node is located. 254 * 255 * @param node The node. 256 * @param buffer The buffer to which page name writes to the memory, 257 * memory space needs to be allocated by the developer. 258 * @param bufferSize The buffer size 259 * @param writeLength Indicates the string length actually written to the buffer 260 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 261 * Indicates the minimum buffer size that can accommodate the target 262 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 263 * @return The error code. 264 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 265 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 266 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 267 * this may be because the node is not in RouterPage. 268 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 269 * @since 12 270 */ 271 ArkUI_ErrorCode OH_ArkUI_GetRouterPageName( 272 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 273 274 /** 275 * @brief Obtain the path of the page where the node is located. 276 * 277 * @param node The node. 278 * @param buffer The buffer to which page path writes to the memory, 279 * memory space needs to be allocated by the developer. 280 * @param bufferSize The buffer size 281 * @param writeLength Indicates the string length actually written to the buffer 282 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 283 * Indicates the minimum buffer size that can accommodate the target 284 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 285 * @return The error code. 286 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 287 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 288 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 289 * this may be because the node is not in RouterPage. 290 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 291 * @since 12 292 */ 293 ArkUI_ErrorCode OH_ArkUI_GetRouterPagePath( 294 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 295 /** 296 * @brief Obtain the state of the page where the node is located. 297 * 298 * @param node The node. 299 * @param state The state value of the page is written back to this parameter. 300 * @return The error code. 301 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 302 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 303 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 304 * this may be because the node is not in RouterPage. 305 * @since 12 306 */ 307 ArkUI_ErrorCode OH_ArkUI_GetRouterPageState(ArkUI_NodeHandle node, ArkUI_RouterPageState* state); 308 309 /** 310 * @brief Obtain the ID of the page where the node is located. 311 * 312 * @param node The node. 313 * @param buffer The buffer to which page ID writes to the memory, memory space needs to be allocated by the developer. 314 * @param bufferSize The buffer size 315 * @param writeLength Indicates the string length actually written to the buffer 316 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 317 * Indicates the minimum buffer size that can accommodate the target 318 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 319 * @return The error code. 320 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 321 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 322 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 323 * this may be because the node is not in RouterPage. 324 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 325 * @since 12 326 */ 327 ArkUI_ErrorCode OH_ArkUI_GetRouterPageId( 328 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 329 330 /** 331 * @brief Register a callback to be executed when rendering in the next frame. 332 * 333 * @param uiContext ArkUI_ContextHandle. 334 * @param userData Indicates the custom data to be saved. 335 * @param callback Custom callback function. 336 * @param nanoTimestamp Timestamp of frame signal. 337 * @param frameCount Frame count. 338 * @return Returns the result code. 339 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 340 * Returns {@link ARKUI_ERROR_CODE_CAPI_INIT_ERROR} if the CAPI init error. 341 * Returns {@link ARKUI_ERROR_CODE_UI_CONTEXT_INVALID} if the uiContext is invalid. 342 * Returns {@link ARKUI_ERROR_CODE_CALLBACK_INVALID} if the callback function is invalid. 343 * @since 16 344 */ 345 int32_t OH_ArkUI_PostFrameCallback(ArkUI_ContextHandle uiContext, void* userData, 346 void (*callback)(uint64_t nanoTimestamp, uint32_t frameCount, void* userData)); 347 348 /** 349 * @brief Register a callback to be executed at the end of the next idle frame. 350 If there is no next frame, will request one automatically. 351 * 352 * @param uiContext ArkUI_ContextHandle. 353 * @param userData Indicates the custom data to be saved. 354 * @param callback Custom callback function. 355 * @param nanoTimeLeft The remaining time from the deadline for this frame. 356 * @param frameCount Frame count. 357 * @return Returns the result code. 358 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 359 * Returns {@link ARKUI_ERROR_CODE_CAPI_INIT_ERROR} if the CAPI init error. 360 * Returns {@link ARKUI_ERROR_CODE_UI_CONTEXT_INVALID} if the uiContext is invalid. 361 * Returns {@link ARKUI_ERROR_CODE_CALLBACK_INVALID} if the callback function is invalid. 362 * @since 20 363 */ 364 int32_t OH_ArkUI_PostIdleCallback(ArkUI_ContextHandle uiContext, void* userData, 365 void (*callback)(uint64_t nanoTimeLeft, uint32_t frameCount, void* userData)); 366 367 #ifdef __cplusplus 368 }; 369 #endif 370 371 #endif // ARKUI_NATIVE_NODE_NAPI_H 372 /** @} */ 373