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