1 /* 2 * Copyright (c) 2021-2022 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 Native_EventHandler 18 * @{ 19 * 20 * @brief Provides <b>EventHandler</b>-specific functions, including functions for obtaining 21 * <b>EventRunnerNativeImplement</b> instances and adding a file descriptor listener. 22 * 23 * @since 3 24 * @version 2.0 25 */ 26 27 /** 28 * @file native_interface_eventhandler.h 29 * 30 * @brief Declares the <b>EventHandler</b>-specific functions, including functions for obtaining 31 * <b>EventRunnerNativeImplement</b> instances and adding a file descriptor listener. 32 * 33 * @since 3 34 * @version 2.0 35 */ 36 37 #ifndef BASE_EVENTHANDLER_INTERFACES_KITS_NATIVE_NATIVE_INTERFACE_EVENTHANDLER_H 38 #define BASE_EVENTHANDLER_INTERFACES_KITS_NATIVE_NATIVE_INTERFACE_EVENTHANDLER_H 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 namespace OHOS { 45 namespace AppExecFwk { 46 struct EventRunnerNativeImplement; 47 using EventRunnerNativeImplement = struct EventRunnerNativeImplement; 48 49 using FileFDCallback = void (*)(int); 50 51 /** 52 * @brief Defines file descriptor callbacks. 53 * 54 * You should implement this structure before adding a file descriptor listener. 55 * 56 * @since 3 57 * @version 2.0 58 */ 59 struct FileDescriptorCallbacks { 60 /** Callback invoked when the file descriptor is readable */ 61 FileFDCallback readableCallback_; 62 /** Callback invoked when the file descriptor is writable */ 63 FileFDCallback writableCallback_; 64 /** Callback invoked when the file descriptor is closed */ 65 FileFDCallback shutdownCallback_; 66 /** Callback invoked when the file descriptor encounters an exception */ 67 FileFDCallback exceptionCallback_; 68 }; 69 70 /** 71 * @brief Obtains the {@link EventRunnerNativeImplement} instance of the current thread. 72 * 73 * You should call this function or {@link CreateEventRunnerNativeObj} to obtain or create an 74 * {@link EventRunnerNativeImplement} instance so that the instance will be passed as an input parameter 75 * to other <b>EventHandler</b>-specific functions you will call. 76 * 77 * @return Returns a non-NULL value if the instance is obtained; returns <b>NULL</b> otherwise. 78 * @since 3 79 * @version 2.0 80 */ 81 const EventRunnerNativeImplement *GetEventRunnerNativeObjForThread(); 82 83 /** 84 * @brief Creates an {@link EventRunnerNativeImplement} instance in a new thread. 85 * 86 * You should call this function or {@link GetEventRunnerNativeObjForThread} to obtain or create an 87 * {@link EventRunnerNativeImplement} instance so that the instance will be passed as an input parameter 88 * to other <b>EventHandler</b>-specific functions you will call. 89 * 90 * @return Returns a non-NULL value if the instance is created; returns <b>NULL</b> otherwise. 91 * @since 3 92 * @version 2.0 93 */ 94 const EventRunnerNativeImplement *CreateEventRunnerNativeObj(); 95 96 /** 97 * @brief Starts the {@link EventRunnerNativeImplement} instance. 98 * 99 * If a file descriptor listener has been added, particular callbacks can be triggered upon corresponding 100 * operations only when the {@link EventRunnerNativeImplement} instance is running. 101 * 102 * @param nativeObj Indicates the pointer to the {@link EventRunnerNativeImplement} instance obtained 103 * by calling {@link GetEventRunnerNativeObjForThread} or {@link CreateEventRunnerNativeObj}. 104 * 105 * @return Returns <b>0</b> if the instance starts running; returns another value otherwise. 106 * @see EventRunnerAddFileDescriptorListener 107 * @since 3 108 * @version 2.0 109 */ 110 int EventRunnerRun(const EventRunnerNativeImplement *nativeObj); 111 112 /** 113 * @brief Stops the {@link EventRunnerNativeImplement} instance. 114 * 115 * @param nativeObj Indicates the pointer to the {@link EventRunnerNativeImplement} instance obtained 116 * by calling {@link GetEventRunnerNativeObjForThread} or {@link CreateEventRunnerNativeObj}. 117 * 118 * @return Returns <b>0</b> if the instance stops running; returns another value otherwise. 119 * @see EventRunnerRun 120 * @since 3 121 * @version 2.0 122 */ 123 int EventRunnerStop(const EventRunnerNativeImplement *nativeObj); 124 125 /** 126 * @brief Adds a file descriptor listener for the {@link EventRunnerNativeImplement} instance. 127 * 128 * The file descriptor listener includes callbacks that can be invoked when the file descriptor is 129 * readable, writable, or closed, or when it encounters an exception. 130 * 131 * @param nativeObj Indicates the pointer to the {@link EventRunnerNativeImplement} instance obtained 132 * by calling {@link GetEventRunnerNativeObjForThread} or {@link CreateEventRunnerNativeObj}. 133 * @param fileDescriptor Indicates the file descriptor for which the listener is to add. 134 * @param events Indicates the file descriptor events, including input, output, and error events. 135 * @param fileDescriptorCallbacks Indicates the pointer to the {@link FileDescriptorCallbacks} structure 136 * containing file descriptor-related callbacks. You must implement this structure. 137 * 138 * @return Returns <b>0</b> if the file descriptor listener is added; returns another value otherwise. 139 * @see EventRunnerRemoveFileDescriptorListener 140 * @see FileDescriptorCallbacks 141 * @since 3 142 * @version 2.0 143 */ 144 int EventRunnerAddFileDescriptorListener(const EventRunnerNativeImplement *nativeObj, int fileDescriptor, 145 unsigned int events, const FileDescriptorCallbacks *fileDescriptorCallbacks); 146 147 /** 148 * @brief Removes the listener for a given file descriptor from the {@link EventRunnerNativeImplement} instance. 149 * 150 * @param nativeObj Indicates the pointer to the {@link EventRunnerNativeImplement} instance obtained by 151 * calling {@link GetEventRunnerNativeObjForThread} or {@link CreateEventRunnerNativeObj}. 152 * @param fileDescriptor Indicates the file descriptor for which the listener is to remove. 153 * @see EventRunnerAddFileDescriptorListener 154 * @since 3 155 * @version 2.0 156 */ 157 void EventRunnerRemoveFileDescriptorListener(const EventRunnerNativeImplement *nativeObj, int fileDescriptor); 158 } // namespace AppExecFwk 159 } // namespace OHOS 160 161 #ifdef __cplusplus 162 }; 163 #endif 164 165 /** @} */ 166 #endif // BASE_EVENTHANDLER_INTERFACES_KITS_NATIVE_NATIVE_INTERFACE_EVENTHANDLER_H