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