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_interface.h
28 *
29 * @brief Provides a unified entry for the native module APIs.
30 *
31 * @library libace_ndk.z.so
32 * @syscap SystemCapability.ArkUI.ArkUI.Full
33 * @since 12
34 */
35
36#ifndef ARKUI_NATIVE_INTERFACE_H
37#define ARKUI_NATIVE_INTERFACE_H
38
39#include <stdint.h>
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 * @brief Defines the native API types.
47 *
48 * @since 12
49 */
50typedef enum {
51    /** API related to UI components. For details, see the struct definition in <arkui/native_node.h>. */
52    ARKUI_NATIVE_NODE,
53    /** API related to dialog boxes. For details, see the struct definition in <arkui/native_dialog.h>. */
54    ARKUI_NATIVE_DIALOG,
55    /** API related to gestures. For details, see the struct definition in <arkui/native_gesture.h>. */
56    ARKUI_NATIVE_GESTURE,
57    /** API related to animations. For details, see the struct definition in <arkui/native_animate.h>.*/
58    ARKUI_NATIVE_ANIMATE,
59} ArkUI_NativeAPIVariantKind;
60
61/**
62 * @brief Obtains the native API set of a specified type.
63 *
64 * @param type Indicates the type of the native API set provided by ArkUI, for example, <b>ARKUI_NATIVE_NODE</b>
65 * and <b>ARKUI_NATIVE_GESTURE</b>.
66 * @param sturctName Indicates the name of a native struct defined in the corresponding header file, for example,
67 * <b>ArkUI_NativeNodeAPI_1</b> in <arkui/native_node.h>.
68 * @return Returns the pointer to the abstract native API, which can be used after being converted into a specific type.
69 * @code {.cpp}
70 * #include<arkui/native_interface.h>
71 * #include<arkui/native_node.h>
72 * #include<arkui/native_gesture.h>
73 *
74 * auto* anyNativeAPI = OH_ArkUI_QueryModuleInterfaceByName(ARKUI_NATIVE_NODE, "ArkUI_NativeNodeAPI_1");
75 * if (anyNativeAPI) {
76 *     auto nativeNodeApi = reinterpret_cast<ArkUI_NativeNodeAPI_1*>(anyNativeAPI);
77 * }
78 * auto anyGestureAPI = OH_ArkUI_QueryModuleInterface(ARKUI_NATIVE_GESTURE, "ArkUI_NativeGestureAPI_1");
79 * if (anyNativeAPI) {
80 *     auto basicGestureApi = reinterpret_cast<ArkUI_NativeGestureAPI_1*>(anyGestureAPI);
81 * }
82 * @endcode
83 *
84 * @since 12
85 */
86void* OH_ArkUI_QueryModuleInterfaceByName(ArkUI_NativeAPIVariantKind type, const char* structName);
87
88/**
89 * @brief Obtains the macro function corresponding to a struct pointer based on the struct type.
90 *
91 * @code {.cpp}
92 * #include<arkui/native_interface.h>
93 * #include<arkui/native_node.h>
94 *
95 * ArkUI_NativeNodeAPI_1* nativeNodeApi = nullptr;
96 * OH_ArkUI_GetModuleInterface(ARKUI_NATIVE_NODE, ArkUI_NativeNodeAPI_1, nativeNodeApi);
97 * @endcode
98 *
99 * @since 12
100 */
101#define OH_ArkUI_GetModuleInterface(nativeAPIVariantKind, structType, structPtr)                     \
102    do {                                                                                             \
103        void* anyNativeAPI = OH_ArkUI_QueryModuleInterfaceByName(nativeAPIVariantKind, #structType); \
104        if (anyNativeAPI) {                                                                          \
105            structPtr = (structType*)(anyNativeAPI);                                                 \
106        }                                                                                            \
107    } while (0)
108
109#ifdef __cplusplus
110};
111#endif
112
113#endif // ARKUI_NATIVE_INTERFACE_H
114/** @} */
115