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_USERAUTH = 0x1 << 8, /** UserAuth device */ 59 DEVICE_CLASS_MAX = 0x1 << 9, /** Maximum value of a device class */ 60 } DeviceClass; 61 62 /** 63 * @brief Called when a driver event occurs. 64 * 65 * You can implement this function and bind it to the custom {@link HdfDevEventlistener} object. \n 66 * 67 * @param priv Indicates the pointer to the private data bound to this listener. 68 * @param id Indicates the serial number of the driver event occurred. 69 * @param data Indicates the pointer to the content data of the driver event. 70 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 71 * 72 * @since 1.0 73 */ 74 typedef int (*OnEventReceived)(void *priv, uint32_t id, struct HdfSBuf *data); 75 76 /** 77 * @brief Called when a driver event occurs. 78 * 79 * You can implement this function and bind it to the custom {@link HdfDevEventlistener} object. \n 80 * 81 * @param listener Indicates the pointer to the listener that receives the driver event. 82 * @param service Indicates the pointer to the driver service object that generates the driver event. 83 * @param id Indicates the serial number of the driver event occurred. 84 * @param data Indicates the pointer to the content data of the driver event. 85 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 86 * 87 * @since 1.0 88 */ 89 typedef int (*OnDevEventReceive)( 90 struct HdfDevEventlistener *listener, struct HdfIoService *service, uint32_t id, struct HdfSBuf *data); 91 92 /** 93 * @brief Defines a driver event listener object. 94 * 95 * @since 1.0 96 */ 97 struct HdfDevEventlistener { 98 /** Deprecated. Use {@link onReceive} instead. */ 99 OnEventReceived callBack; 100 /** Callback invoked when the monitored device reports an event */ 101 OnDevEventReceive onReceive; 102 /** Intrusive list node used by the HDF to manage listeners. You can ignore this node. */ 103 struct DListHead listNode; 104 /** Private data of the listener */ 105 void *priv; 106 }; 107 108 /** 109 * @brief Defines a driver service call dispatcher. 110 * 111 * @since 1.0 112 */ 113 struct HdfIoDispatcher { 114 /** Dispatches a driver service call. <b>service</b> indicates the pointer to the driver service object, <b>id</b> 115 indicates the command word of the function, <b>data</b> indicates the pointer to the data you want to pass to 116 the driver, and <b>reply</b> indicates the pointer to the data returned by the driver. */ 117 int (*Dispatch)(struct HdfObject *service, int cmdId, struct HdfSBuf *data, struct HdfSBuf *reply); 118 }; 119 120 /** 121 * @brief Defines a driver service object. 122 * 123 * @since 1.0 124 */ 125 struct HdfIoService { 126 /** Base class object */ 127 struct HdfObject object; 128 /** Pointer to the bound service entity, which is used for framework management. You can ignore it. */ 129 struct HdfObject *target; 130 /** Service call dispatcher */ 131 struct HdfIoDispatcher *dispatcher; 132 /** Private data of the service */ 133 void *priv; 134 }; 135 136 /** 137 * @brief Defines a driver service group object. 138 * 139 * @since 1.0 140 */ 141 struct HdfIoServiceGroup { 142 /** Base class object */ 143 struct HdfObject object; 144 }; 145 146 /** 147 * @brief Obtains an instance of the driver service group object. 148 * 149 * @return Returns the pointer to the driver service group object if the operation is successful; 150 * returns <b>NULL</b> otherwise. 151 * 152 * @since 1.0 153 */ 154 struct HdfIoServiceGroup *HdfIoServiceGroupObtain(void); 155 156 /** 157 * @brief Destroys a driver service group object. 158 * 159 * @param group Indicates the pointer to the driver service group object to destroy. 160 * 161 * @since 1.0 162 */ 163 void HdfIoServiceGroupRecycle(struct HdfIoServiceGroup *group); 164 165 /** 166 * @brief Adds a driver service object to a specified driver service group. 167 * 168 * @param group Indicates the pointer to the driver service group object to 169 * which the driver service object is to be added. 170 * @param service Indicates the pointer to the driver service object to add. 171 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 172 * 173 * @since 1.0 174 */ 175 int32_t HdfIoServiceGroupAddService(struct HdfIoServiceGroup *group, struct HdfIoService *service); 176 177 /** 178 * @brief Removes a driver service object from a specified driver service group. 179 * 180 * @param group Indicates the pointer to the driver service group object from 181 * which the driver service object is to be removed. 182 * @param service Indicates the pointer to the driver service object to remove. 183 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 184 * 185 * @since 1.0 186 */ 187 void HdfIoServiceGroupRemoveService(struct HdfIoServiceGroup *group, struct HdfIoService *service); 188 189 /** 190 * @brief Registers a custom {@link HdfDevEventlistener} for listening for events reported by driver services 191 * in a specified driver service group object. 192 * 193 * @param group Indicates the pointer to the driver service group object to listen to, 194 * which is obtained via {@link HdfIoServiceGroupObtain}. 195 * @param listener Indicates the pointer to the {@link HdfDevEventlistener} to register. 196 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 197 * 198 * @since 1.0 199 */ 200 int32_t HdfIoServiceGroupRegisterListener(struct HdfIoServiceGroup *group, struct HdfDevEventlistener *listener); 201 202 /** 203 * @brief Unregisters a previously registered {@link HdfDevEventlistener} that is used for listening for events 204 * reported by driver services in a specified driver service group object. 205 * 206 * @param group Indicates the pointer to the driver service group object that has been listened to. 207 * @param listener Indicates the pointer to the {@link HdfDevEventlistener} to unregister. 208 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 209 * 210 * @since 1.0 211 */ 212 int32_t HdfIoServiceGroupUnregisterListener(struct HdfIoServiceGroup *group, struct HdfDevEventlistener *listener); 213 214 /** 215 * @brief Obtains a driver service object. 216 * 217 * 218 * 219 * @param serviceName Indicates the pointer to the name of the service to obtain. 220 * @return Returns the pointer to the driver service object if the operation is successful; 221 * returns <b>NULL</b> otherwise. 222 * 223 * @since 1.0 224 */ 225 struct HdfIoService *HdfIoServiceBind(const char *serviceName); 226 227 /** 228 * @brief Destroys a specified driver service object to release resources if it is no longer required. 229 * 230 * @param service Indicates the pointer to the driver service object to destroy. 231 * 232 * @since 1.0 233 */ 234 void HdfIoServiceRecycle(struct HdfIoService *service); 235 236 /** 237 * @brief Registers a custom {@link HdfDevEventlistener} for listening for events reported 238 * by a specified driver service object. 239 * 240 * @param target Indicates the pointer to the driver service object to listen, which is obtained through 241 * the {@link HdfIoServiceBind} function. 242 * @param listener Indicates the pointer to the listener to register. 243 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 244 * 245 * @since 1.0 246 */ 247 int HdfDeviceRegisterEventListener(struct HdfIoService *target, struct HdfDevEventlistener *listener); 248 249 /** 250 * @brief Unregisters a previously registered {@link HdfDevEventlistener} to release resources 251 * if it is no longer required. 252 * 253 * @param target Indicates the pointer to the driver service object that has been listened. 254 * @param listener Indicates the listener object registered by {@link HdfDeviceRegisterEventListener}. 255 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 256 * 257 * @since 1.0 258 */ 259 int HdfDeviceUnregisterEventListener(struct HdfIoService *target, struct HdfDevEventlistener *listener); 260 261 /** 262 * @brief Obtains the number of event listeners that are registered for a specified driver service object. 263 * 264 * @param service Indicates the pointer to the driver service object for which the event listeners are registered. 265 * @return Returns the number of listeners if the operation is successful; returns a negative value otherwise. 266 * 267 * @since 1.0 268 */ 269 int HdfIoserviceGetListenerCount(const struct HdfIoService *service); 270 271 /** 272 * @brief Obtains the number of event listeners that are registered for a specified driver service group object. 273 * 274 * @param group Indicates the pointer to the driver service group object for which the event listeners are registered. 275 * @return Returns the number of listeners if the operation is successful; returns a negative value otherwise. 276 * 277 * @since 1.0 278 */ 279 int HdfIoserviceGroupGetListenerCount(const struct HdfIoServiceGroup *group); 280 281 /** 282 * @brief Obtains the number of driver services included in a specified driver service group. 283 * 284 * @param group Indicates the pointer to the driver service group object. 285 * @return Returns the number of services if the operation is successful; returns a negative value otherwise. 286 * 287 * @since 1.0 288 */ 289 int HdfIoserviceGroupGetServiceCount(const struct HdfIoServiceGroup *group); 290 291 /** 292 * @brief Obtains the names of device services of a specified device class defined by {@link DeviceClass}. 293 * 294 * 295 * @param deviceClass Indicates the device class to query. 296 * @param reply Indicates the pointer to the service name, which is stored as a string in an <b>HdfSBuf</b> structure. 297 * You can use {@link HdfSbufReadString} to continuously read the service names until a null pointer appears. 298 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 299 * 300 * @since 1.0 301 */ 302 int32_t HdfGetServiceNameByDeviceClass(DeviceClass deviceClass, struct HdfSBuf *reply); 303 304 #ifdef __cplusplus 305 } 306 #endif /* __cplusplus */ 307 308 #endif /* HDF_IO_SERVICE_IF_H */ 309 /** @} */ 310