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 Obtain the ID of the Navigation component where the node is located. 74 * 75 * @param node The node. 76 * @param buffer The buffer to which NavigationID writes to the memory, 77 * memory space needs to be allocated by the developer. 78 * @param bufferSize The buffer size 79 * @param writeLength Indicates the string length actually written to the buffer 80 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 81 * Indicates the minimum buffer size that can accommodate the target 82 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 83 * @return The error code. 84 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 85 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 86 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 87 * this may be because the node is not in Navigation. 88 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 89 * @since 12 90 */ 91 ArkUI_ErrorCode OH_ArkUI_GetNavigationId( 92 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 93 94 /** 95 * @brief Obtain the name of the NavDestination component where the node is located. 96 * 97 * @param node The node. 98 * @param buffer The buffer to which NavDestination name 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_GetNavDestinationName( 114 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 115 116 /** 117 * @brief Based on the given index value, obtain the length of the Navigation stack where the node is located. 118 * 119 * @param node The node. 120 * @param length The length of the stack. After the operation succeeds, the result is written back to this parameter. 121 * @return The error code. 122 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 123 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or length is null. 124 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 125 * this may be because the node is not in Navigation. 126 * @since 12 127 */ 128 ArkUI_ErrorCode OH_ArkUI_GetNavStackLength(ArkUI_NodeHandle node, int32_t* length); 129 130 /** 131 * @brief Based on the given index value, obtain the page name of the corresponding position 132 * in the navigation stack where the node is located. 133 * Index values are counted from 0, with 0 being the bottom of the stack. 134 * 135 * @param node The node. 136 * @param index The index of the NavDestination in the stack is queried. 137 * @param buffer The buffer to which NavDestination index writes to the memory, 138 * memory space needs to be allocated by the developer. 139 * @param bufferSize The buffer size 140 * @param writeLength Indicates the string length actually written to the buffer 141 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 142 * Indicates the minimum buffer size that can accommodate the target 143 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 144 * @return The error code. 145 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 146 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 147 * {@link ARKUI_ERROR_CODE_NODE_INDEX_INVALID} if index is an invalid value. 148 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 149 * this may be because the node is not in Navigation. 150 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 151 * @since 12 152 */ 153 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationNameByIndex( 154 ArkUI_NodeHandle node, int32_t index, char* buffer, int32_t bufferSize, int32_t* writeLength); 155 156 /** 157 * @brief Obtain the ID of the NavDestination component where the node is located. 158 * 159 * @param node The node. 160 * @param buffer The buffer to which NavDestination ID writes to the memory, 161 * memory space needs to be allocated by the developer. 162 * @param bufferSize The buffer size 163 * @param writeLength Indicates the string length actually written to the buffer 164 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 165 * Indicates the minimum buffer size that can accommodate the target 166 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 167 * @return The error code. 168 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 169 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 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_GetNavDestinationId( 176 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 177 178 /** 179 * @brief Obtain the state of the NavDestination component where the node is located. 180 * 181 * @param node The node. 182 * @param state The state value of NavDestination is written back into this parameter. 183 * @return The error code. 184 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 185 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 186 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 187 * this may be because the node is not in Navigation. 188 * @since 12 189 */ 190 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationState(ArkUI_NodeHandle node, ArkUI_NavDestinationState* state); 191 192 /** 193 * @brief Obtain the index of the NavDestination component on the Navigation stack where the node is located. 194 * 195 * @param node The node. 196 * @param index Index value, counted from 0. 197 * @return The error code. 198 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 199 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 200 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 201 * this may be because the node is not in Navigation. 202 * @since 12 203 */ 204 ArkUI_ErrorCode OH_ArkUI_GetNavDestinationIndex(ArkUI_NodeHandle node, int32_t* index); 205 206 /** 207 * @brief Obtain the parameters of the NavDestination component where the node is located. 208 * 209 * @param node The node. 210 * @return The parameters. 211 * If a null pointer is returned, it may be because the node is empty or the parameters does not exist. 212 * @since 12 213 */ 214 napi_value OH_ArkUI_GetNavDestinationParam(ArkUI_NodeHandle node); 215 216 /** 217 * @brief Obtain the index of the page where the node resides in the Router page stack. 218 * 219 * @param node The node. 220 * @param index Index value, counted from 1. 221 * @return The error code. 222 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 223 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or index is null. 224 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 225 * this may be because the node is not in RouterPage. 226 * @since 12 227 */ 228 ArkUI_ErrorCode OH_ArkUI_GetRouterPageIndex(ArkUI_NodeHandle node, int32_t* index); 229 230 /** 231 * @brief Obtain the name of the page where the node is located. 232 * 233 * @param node The node. 234 * @param buffer The buffer to which page name writes to the memory, 235 * memory space needs to be allocated by the developer. 236 * @param bufferSize The buffer size 237 * @param writeLength Indicates the string length actually written to the buffer 238 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 239 * Indicates the minimum buffer size that can accommodate the target 240 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 241 * @return The error code. 242 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 243 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 244 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 245 * this may be because the node is not in RouterPage. 246 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 247 * @since 12 248 */ 249 ArkUI_ErrorCode OH_ArkUI_GetRouterPageName( 250 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 251 252 /** 253 * @brief Obtain the path of the page where the node is located. 254 * 255 * @param node The node. 256 * @param buffer The buffer to which page path 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_GetRouterPagePath( 272 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 273 /** 274 * @brief Obtain the state of the page where the node is located. 275 * 276 * @param node The node. 277 * @param state The state value of the page is written back to this parameter. 278 * @return The error code. 279 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 280 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node or state is null. 281 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 282 * this may be because the node is not in RouterPage. 283 * @since 12 284 */ 285 ArkUI_ErrorCode OH_ArkUI_GetRouterPageState(ArkUI_NodeHandle node, ArkUI_RouterPageState* state); 286 287 /** 288 * @brief Obtain the ID of the page where the node is located. 289 * 290 * @param node The node. 291 * @param buffer The buffer to which page ID writes to the memory, memory space needs to be allocated by the developer. 292 * @param bufferSize The buffer size 293 * @param writeLength Indicates the string length actually written to the buffer 294 * when returning {@link ARKUI_ERROR_CODE_NO_ERROR}. 295 * Indicates the minimum buffer size that can accommodate the target 296 * when {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} is returned. 297 * @return The error code. 298 * {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 299 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node, buffer or writeLength is null. 300 * {@link ARKUI_ERROR_CODE_GET_INFO_FAILED} if query information failed, 301 * this may be because the node is not in RouterPage. 302 * {@link ARKUI_ERROR_CODE_BUFFER_SIZE_ERROR} If the buffer size is less than the minimum buffer size. 303 * @since 12 304 */ 305 ArkUI_ErrorCode OH_ArkUI_GetRouterPageId( 306 ArkUI_NodeHandle node, char* buffer, int32_t bufferSize, int32_t* writeLength); 307 308 #ifdef __cplusplus 309 }; 310 #endif 311 312 #endif // ARKUI_NATIVE_NODE_NAPI_H 313 /** @} */ 314