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 Declares APIs for converting <b>FrameNode</b> objects on the ArkTS side to <b>ArkUI_NodeHandle</b> objects on 30 * the native side. 31 * 32 * @library libace_ndk.z.so 33 * @syscap SystemCapability.ArkUI.ArkUI.Full 34 * @kit ArkUI 35 * @since 12 36 */ 37 38 #ifndef ARKUI_NATIVE_NODE_NAPI_H 39 #define ARKUI_NATIVE_NODE_NAPI_H 40 41 #include "drawable_descriptor.h" 42 #include "napi/native_api.h" 43 #include "native_type.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 /** 49 * @brief Obtains a <b>FrameNode</b> object on the ArkTS side and maps it to an <b>ArkUI_NodeHandle</b> object on the 50 * native side. 51 * 52 * @param env Indicates the NAPI environment pointer. 53 * @param frameNode Indicates the <b>FrameNode</b> object created on the ArkTS side. 54 * @param handle Indicates the pointer to the <b>ArkUI_NodeHandle</b> object. 55 * @return Returns the error code. 56 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 57 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 58 * @since 12 59 */ 60 int32_t OH_ArkUI_GetNodeHandleFromNapiValue(napi_env env, napi_value frameNode, ArkUI_NodeHandle* handle); 61 62 /** 63 * @brief Obtains a <b>UIContext</b> object on the ArkTS side and maps it to an <b>ArkUI_ContextHandle</b> object on the 64 * native side. 65 * 66 * @param env ndicates the NAPI environment pointer. 67 * @param value Indicates the <b>UIContext</b> object created on the ArkTS side. 68 * @param context Indicates the pointer to the <b>ArkUI_ContextHandle</b> object. 69 * @return Returns the error code. 70 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 71 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 72 * @since 12 73 */ 74 int32_t OH_ArkUI_GetContextFromNapiValue(napi_env env, napi_value value, ArkUI_ContextHandle* context); 75 76 77 /** 78 * @brief Obtains a <b>NodeContent</b> object on the ArkTS side and maps it to an <b>ArkUI_NodeContentHandle</b> 79 * object on the native side. 80 * 81 * @param env ndicates the NAPI environment pointer. 82 * @param value Indicates the <b>NodeContent</b> object created on the ArkTS side. 83 * @param content Indicates the pointer to the <b>ArkUI_NodeContentHandle</b> object. 84 * @return Returns the error code. 85 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 86 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 87 * @since 12 88 */ 89 int32_t OH_ArkUI_GetNodeContentFromNapiValue(napi_env env, napi_value value, ArkUI_NodeContentHandle* content); 90 91 /** 92 * @brief Obtains a <b>DrawableDescriptor</b> object on the ArkTS side and maps it to an 93 * <b>ArkUI_DrawableDescriptro</b> object on the native side. 94 * 95 * @param env Indicates the NAPI environment pointer. 96 * @param value Indicates the <b>DrawableDescriptor</b> object created on the ArkTS side. 97 * @param drawableDescriptor Indicates the pointer to the <b>ArkUI_DrawableDescriptro</b> object. 98 * @return Returns the error code. 99 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 100 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 101 * @since 12 102 */ 103 int32_t OH_ArkUI_GetDrawableDescriptorFromNapiValue( 104 napi_env env, napi_value value, ArkUI_DrawableDescriptor** drawableDescriptor); 105 106 /** 107 * @brief Obtains a <b>Resource</b> object on the ArkTS side and maps it to an 108 * <b>ArkUI_DrawableDescriptro</b> object on the native side. 109 * 110 * @param env Indicates the NAPI environment pointer. 111 * @param value Indicates the <b>Resource</b> object created on the ArkTS side. 112 * @param drawableDescriptor Indicates the pointer to the <b>ArkUI_DrawableDescriptro</b> object. 113 * @return Returns the error code. 114 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 115 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 116 * @since 12 117 */ 118 int32_t OH_ArkUI_GetDrawableDescriptorFromResourceNapiValue( 119 napi_env env, napi_value value, ArkUI_DrawableDescriptor** drawableDescriptor); 120 121 /** 122 * @brief Obtain the ID of the Navigation component where the node is located. 123 * 124 * @param node The node. 125 * @param buffer The buffer to which NavigationID writes to the memory, 126 * memory space needs to be allocated by the developer. 127 * @param bufferSize The buffer size 128 * @param writeLength Indicates the string length actually written to the buffer 129 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 130 * Indicates the minimum buffer size that can accommodate the target 131 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 132 * @return The error code. 133 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 134 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 135 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 136 * this may be because the node is not in Navigation. 137 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 138 * @since 12 139 */ 140 ArkUI_ErrorCode OH_ArkUI_GetNavigationId( 141 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 142 143 /** 144 * @brief Obtain the name of the NavDestination component where the node is located. 145 * 146 * @param node The node. 147 * @param buffer The buffer to which NavDestination name writes to the memory, 148 * memory space needs to be allocated by the developer. 149 * @param bufferSize The buffer size 150 * @param writeLength Indicates the string length actually written to the buffer 151 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 152 * Indicates the minimum buffer size that can accommodate the target 153 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 154 * @return The error code. 155 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 156 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 157 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 158 * this may be because the node is not in Navigation. 159 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 160 * @since 12 161 */ 162 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationName( 163 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 164 165 /** 166 * @brief Based on the given index value, obtain the length of the Navigation stack where the node is located. 167 * 168 * @param node The node. 169 * @param length The length of the stack. After the operation succeeds, the result is written back to this parameter. 170 * @return The error code. 171 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 172 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or length is null. 173 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 174 * this may be because the node is not in Navigation. 175 * @since 12 176 */ 177 ArkUI_ErrorCode OH_ArkUI_GetNavStackLength(ArkUI_NodeHandle node, int32_t* length); 178 179 /** 180 * @brief Based on the given index value, obtain the page name of the corresponding position 181 * in the navigation stack where the node is located. 182 * Index values are counted from 0, with 0 being the bottom of the stack. 183 * 184 * @param node The node. 185 * @param index The index of the NavDestination in the stack is queried. 186 * @param buffer The buffer to which NavDestination index writes to the memory, 187 * memory space needs to be allocated by the developer. 188 * @param bufferSize The buffer size 189 * @param writeLength Indicates the string length actually written to the buffer 190 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 191 * Indicates the minimum buffer size that can accommodate the target 192 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 193 * @return The error code. 194 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 195 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 196 * {@link ARKUI_ERROR_CODE_NODE_INDEX_INVALID} if index is an invalid value. 197 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 198 * this may be because the node is not in Navigation. 199 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 200 * @since 12 201 */ 202 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationNameByIndex( 203 ArkUI_NodeHandle node, int32_t index, char* buffer, int32_t bufferSize, int32_t* writeLength); 204 205 /** 206 * @brief Obtain the ID of the NavDestination component where the node is located. 207 * 208 * @param node The node. 209 * @param buffer The buffer to which NavDestination ID writes to the memory, 210 * memory space needs to be allocated by the developer. 211 * @param bufferSize The buffer size 212 * @param writeLength Indicates the string length actually written to the buffer 213 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 214 * Indicates the minimum buffer size that can accommodate the target 215 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 216 * @return The error code. 217 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 218 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 219 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 220 * this may be because the node is not in Navigation. 221 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 222 * @since 12 223 */ 224 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationId( 225 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 226 227 /** 228 * @brief Obtain the state of the NavDestination component where the node is located. 229 * 230 * @param node The node. 231 * @param state The state value of NavDestination is written back into this parameter. 232 * @return The error code. 233 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 234 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 235 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 236 * this may be because the node is not in Navigation. 237 * @since 12 238 */ 239 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationState(ArkUI_NodeHandle node, ArkUI_NavDestinationState* state); 240 241 /** 242 * @brief Obtain the index of the NavDestination component on the Navigation stack where the node is located. 243 * 244 * @param node The node. 245 * @param index Index value, counted from 0. 246 * @return The error code. 247 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 248 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 249 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 250 * this may be because the node is not in Navigation. 251 * @since 12 252 */ 253 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationIndex(ArkUI_NodeHandle node, int32_t* index); 254 255 /** 256 * @brief Obtain the parameters of the NavDestination component where the node is located. 257 * 258 * @param node The node. 259 * @return The parameters. 260 * If a null pointer is returned, it may be because the node is empty or the parameters does not exist. 261 * @since 12 262 */ 263 napi_value OH_ArkUI_GetNavDestinationParam(ArkUI_NodeHandle node); 264 265 /** 266 * @brief Obtain the index of the page where the node resides in the Router page stack. 267 * 268 * @param node The node. 269 * @param index Index value, counted from 1. 270 * @return The error code. 271 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 272 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 273 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 274 * this may be because the node is not in RouterPage. 275 * @since 12 276 */ 277 ArkUI_ErrorCode OH_ArkUI_GetRouterPageIndex(ArkUI_NodeHandle node, int32_t* index); 278 279 /** 280 * @brief Obtain the name of the page where the node is located. 281 * 282 * @param node The node. 283 * @param buffer The buffer to which page name writes to the memory, 284 * memory space needs to be allocated by the developer. 285 * @param bufferSize The buffer size 286 * @param writeLength Indicates the string length actually written to the buffer 287 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 288 * Indicates the minimum buffer size that can accommodate the target 289 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 290 * @return The error code. 291 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 292 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 293 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 294 * this may be because the node is not in RouterPage. 295 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 296 * @since 12 297 */ 298 ArkUI_ErrorCode OH_ArkUI_GetRouterPageName( 299 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 300 301 /** 302 * @brief Obtain the path of the page where the node is located. 303 * 304 * @param node The node. 305 * @param buffer The buffer to which page path writes to the memory, 306 * memory space needs to be allocated by the developer. 307 * @param bufferSize The buffer size 308 * @param writeLength Indicates the string length actually written to the buffer 309 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 310 * Indicates the minimum buffer size that can accommodate the target 311 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 312 * @return The error code. 313 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 314 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 315 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 316 * this may be because the node is not in RouterPage. 317 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 318 * @since 12 319 */ 320 ArkUI_ErrorCode OH_ArkUI_GetRouterPagePath( 321 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 322 /** 323 * @brief Obtain the state of the page where the node is located. 324 * 325 * @param node The node. 326 * @param state The state value of the page is written back to this parameter. 327 * @return The error code. 328 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 329 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 330 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 331 * this may be because the node is not in RouterPage. 332 * @since 12 333 */ 334 ArkUI_ErrorCode OH_ArkUI_GetRouterPageState(ArkUI_NodeHandle node, ArkUI_RouterPageState* state); 335 336 /** 337 * @brief Obtain the ID of the page where the node is located. 338 * 339 * @param node The node. 340 * @param buffer The buffer to which page ID writes to the memory, 341 * memory space needs to be allocated by the developer. 342 * @param bufferSize The buffer size 343 * @param writeLength Indicates the string length actually written to the buffer 344 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 345 * Indicates the minimum buffer size that can accommodate the target 346 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 347 * @return The error code. 348 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 349 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 350 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 351 * this may be because the node is not in RouterPage. 352 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 353 * @since 12 354 */ 355 ArkUI_ErrorCode OH_ArkUI_GetRouterPageId( 356 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 357 358 #ifdef __cplusplus 359 }; 360 #endif 361 362 #endif // ARKUI_NATIVE_NODE_NAPI_H 363 /** @} */ 364