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
46extern "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 */
60int32_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 */
74int32_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  */
89int32_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*/
103int32_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*/
118int32_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 */
140ArkUI_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 */
162ArkUI_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 */
177ArkUI_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 */
202ArkUI_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 */
224ArkUI_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 */
239ArkUI_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 */
253ArkUI_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 */
263napi_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 */
277ArkUI_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 */
298ArkUI_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 */
320ArkUI_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 */
334ArkUI_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 */
355ArkUI_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