1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 /** 9 * @addtogroup Core 10 * @{ 11 * 12 * @brief Provides functions to use the Hardware Driver Foundation (HDF). 13 * 14 * The HDF implements driver framework capabilities such as driver loading, service management, driver message model, 15 * and power management. You can develop drivers based on the HDF. 16 * 17 * @since 1.0 18 */ 19 20 /** 21 * @file hdf_io_service_if.h 22 * 23 * @brief Declares the structures defining driver service objects and event listeners, as well as the functions 24 * for obtaining a driver service object, dispatching a driver service call, and registering or unregistering 25 * an event listener. 26 * 27 * @since 1.0 28 */ 29 30 #ifndef HDF_IO_SERVICE_IF_H 31 #define HDF_IO_SERVICE_IF_H 32 33 #include "hdf_dlist.h" 34 #include "hdf_object.h" 35 #include "hdf_sbuf.h" 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif /* __cplusplus */ 40 41 struct HdfDevEventlistener; 42 struct HdfIoService; 43 44 /** 45 * @brief Enumerates different classes of driver devices. 46 * 47 * @since 1.0 48 */ 49 typedef enum { 50 DEVICE_CLASS_DEFAULT = 0x1 << 0, /** Default device */ 51 DEVICE_CLASS_PLAT = 0x1 << 1, /** Platform device */ 52 DEVICE_CLASS_SENSOR = 0x1 << 2, /** Sensor device */ 53 DEVICE_CLASS_INPUT = 0x1 << 3, /** Input device */ 54 DEVICE_CLASS_DISPLAY = 0x1 << 4, /** Display device */ 55 DEVICE_CLASS_AUDIO = 0x1 << 5, /** Audio device */ 56 DEVICE_CLASS_CAMERA = 0x1 << 6, /** Camera device */ 57 DEVICE_CLASS_USB = 0x1 << 7, /** USB device */ 58 DEVICE_CLASS_MAX = 0x1 << 8, /** Maximum value of a device class */ 59 } DeviceClass; 60 61 /** 62 * @brief Called when a driver event occurs. 63 * 64 * You can implement this function and bind it to the custom {@link HdfDevEventlistener} object. \n 65 * 66 * @param priv Indicates the pointer to the private data bound to this listener. 67 * @param id Indicates the serial number of the driver event occurred. 68 * @param data Indicates the pointer to the content data of the driver event. 69 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 70 * 71 * @since 1.0 72 */ 73 typedef int (*OnEventReceived)(void *priv, uint32_t id, struct HdfSBuf *data); 74 75 /** 76 * @brief Called when a driver event occurs. 77 * 78 * You can implement this function and bind it to the custom {@link HdfDevEventlistener} object. \n 79 * 80 * @param listener Indicates the pointer to the listener that receives the driver event. 81 * @param service Indicates the pointer to the driver service object that generates the driver event. 82 * @param id Indicates the serial number of the driver event occurred. 83 * @param data Indicates the pointer to the content data of the driver event. 84 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 85 * 86 * @since 1.0 87 */ 88 typedef int (*OnDevEventReceive)( 89 struct HdfDevEventlistener *listener, struct HdfIoService *service, uint32_t id, struct HdfSBuf *data); 90 91 /** 92 * @brief Defines a driver event listener object. 93 * 94 * @since 1.0 95 */ 96 struct HdfDevEventlistener { 97 /** Deprecated. Use {@link onReceive} instead. */ 98 OnEventReceived callBack; 99 /** Callback invoked when the monitored device reports an event */ 100 OnDevEventReceive onReceive; 101 /** Intrusive list node used by the HDF to manage listeners. You can ignore this node. */ 102 struct DListHead listNode; 103 /** Private data of the listener */ 104 void *priv; 105 }; 106 107 /** 108 * @brief Defines a driver service call dispatcher. 109 * 110 * @since 1.0 111 */ 112 struct HdfIoDispatcher { 113 /** Dispatches a driver service call. <b>service</b> indicates the pointer to the driver service object, <b>id</b> 114 indicates the command word of the function, <b>data</b> indicates the pointer to the data you want to pass to 115 the driver, and <b>reply</b> indicates the pointer to the data returned by the driver. */ 116 int (*Dispatch)(struct HdfObject *service, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply); 117 }; 118 119 /** 120 * @brief Defines a driver service object. 121 * 122 * @since 1.0 123 */ 124 struct HdfIoService { 125 /** Base class object */ 126 struct HdfObject object; 127 /** Pointer to the bound service entity, which is used for framework management. You can ignore it. */ 128 struct HdfObject *target; 129 /** Service call dispatcher */ 130 struct HdfIoDispatcher *dispatcher; 131 /** Private data of the service */ 132 void *priv; 133 }; 134 135 /** 136 * @brief Defines a driver service group object. 137 * 138 * @since 1.0 139 */ 140 struct HdfIoServiceGroup { 141 /** Base class object */ 142 struct HdfObject object; 143 }; 144 145 /** 146 * @brief Obtains an instance of the driver service group object. 147 * 148 * @return Returns the pointer to the driver service group object if the operation is successful; 149 * returns <b>NULL</b> otherwise. 150 * 151 * @since 1.0 152 */ 153 struct HdfIoServiceGroup *HdfIoServiceGroupObtain(void); 154 155 /** 156 * @brief Destroys a driver service group object. 157 * 158 * @param group Indicates the pointer to the driver service group object to destroy. 159 * 160 * @since 1.0 161 */ 162 void HdfIoServiceGroupRecycle(struct HdfIoServiceGroup *group); 163 164 /** 165 * @brief Adds a driver service object to a specified driver service group. 166 * 167 * @param group Indicates the pointer to the driver service group object to 168 * which the driver service object is to be added. 169 * @param service Indicates the pointer to the driver service object to add. 170 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 171 * 172 * @since 1.0 173 */ 174 int32_t HdfIoServiceGroupAddService(struct HdfIoServiceGroup *group, struct HdfIoService *service); 175 176 /** 177 * @brief Removes a driver service object from a specified driver service group. 178 * 179 * @param group Indicates the pointer to the driver service group object from 180 * which the driver service object is to be removed. 181 * @param service Indicates the pointer to the driver service object to remove. 182 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 183 * 184 * @since 1.0 185 */ 186 void HdfIoServiceGroupRemoveService(struct HdfIoServiceGroup *group, struct HdfIoService *service); 187 188 /** 189 * @brief Registers a custom {@link HdfDevEventlistener} for listening for events reported by driver services 190 * in a specified driver service group object. 191 * 192 * @param group Indicates the pointer to the driver service group object to listen to, 193 * which is obtained via {@link HdfIoServiceGroupObtain}. 194 * @param listener Indicates the pointer to the {@link HdfDevEventlistener} to register. 195 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 196 * 197 * @since 1.0 198 */ 199 int32_t HdfIoServiceGroupRegisterListener(struct HdfIoServiceGroup *group, struct HdfDevEventlistener *listener); 200 201 /** 202 * @brief Unregisters a previously registered {@link HdfDevEventlistener} that is used for listening for events 203 * reported by driver services in a specified driver service group object. 204 * 205 * @param group Indicates the pointer to the driver service group object that has been listened to. 206 * @param listener Indicates the pointer to the {@link HdfDevEventlistener} to unregister. 207 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 208 * 209 * @since 1.0 210 */ 211 int32_t HdfIoServiceGroupUnregisterListener(struct HdfIoServiceGroup *group, struct HdfDevEventlistener *listener); 212 213 /** 214 * @brief Obtains a driver service object. 215 * 216 * 217 * 218 * @param serviceName Indicates the pointer to the name of the service to obtain. 219 * @return Returns the pointer to the driver service object if the operation is successful; 220 * returns <b>NULL</b> otherwise. 221 * 222 * @since 1.0 223 */ 224 struct HdfIoService *HdfIoServiceBind(const char *serviceName); 225 226 /** 227 * @brief Destroys a specified driver service object to release resources if it is no longer required. 228 * 229 * @param service Indicates the pointer to the driver service object to destroy. 230 * 231 * @since 1.0 232 */ 233 void HdfIoServiceRecycle(struct HdfIoService *service); 234 235 /** 236 * @brief Registers a custom {@link HdfDevEventlistener} for listening for events reported 237 * by a specified driver service object. 238 * 239 * @param target Indicates the pointer to the driver service object to listen, which is obtained through 240 * the {@link HdfIoServiceBind} function. 241 * @param listener Indicates the pointer to the listener to register. 242 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 243 * 244 * @since 1.0 245 */ 246 int HdfDeviceRegisterEventListener(struct HdfIoService *target, struct HdfDevEventlistener *listener); 247 248 /** 249 * @brief Unregisters a previously registered {@link HdfDevEventlistener} to release resources 250 * if it is no longer required. 251 * 252 * @param target Indicates the pointer to the driver service object that has been listened. 253 * @param listener Indicates the listener object registered by {@link HdfDeviceRegisterEventListener}. 254 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 255 * 256 * @since 1.0 257 */ 258 int HdfDeviceUnregisterEventListener(struct HdfIoService *target, struct HdfDevEventlistener *listener); 259 260 /** 261 * @brief Obtains the number of event listeners that are registered for a specified driver service object. 262 * 263 * @param service Indicates the pointer to the driver service object for which the event listeners are registered. 264 * @return Returns the number of listeners if the operation is successful; returns a negative value otherwise. 265 * 266 * @since 1.0 267 */ 268 int HdfIoserviceGetListenerCount(const struct HdfIoService *service); 269 270 /** 271 * @brief Obtains the number of event listeners that are registered for a specified driver service group object. 272 * 273 * @param group Indicates the pointer to the driver service group object for which the event listeners are registered. 274 * @return Returns the number of listeners if the operation is successful; returns a negative value otherwise. 275 * 276 * @since 1.0 277 */ 278 int HdfIoserviceGroupGetListenerCount(const struct HdfIoServiceGroup *group); 279 280 /** 281 * @brief Obtains the number of driver services included in a specified driver service group. 282 * 283 * @param group Indicates the pointer to the driver service group object. 284 * @return Returns the number of services if the operation is successful; returns a negative value otherwise. 285 * 286 * @since 1.0 287 */ 288 int HdfIoserviceGroupGetServiceCount(const struct HdfIoServiceGroup *group); 289 290 /** 291 * @brief Obtains the names of device services of a specified device class defined by {@link DeviceClass}. 292 * 293 * 294 * @param deviceClass Indicates the device class to query. 295 * @param reply Indicates the pointer to the service name, which is stored as a string in an <b>HdfSBuf</b> structure. 296 * You can use {@link HdfSbufReadString} to continuously read the service names until a null pointer appears. 297 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 298 * 299 * @since 1.0 300 */ 301 int32_t HdfGetServiceNameByDeviceClass(DeviceClass deviceClass, struct HdfSBuf *reply); 302 303 #ifdef __cplusplus 304 } 305 #endif /* __cplusplus */ 306 307 #endif /* HDF_IO_SERVICE_IF_H */ 308 /** @} */ 309