1 /* 2 * Copyright (c) 2021-2023 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 DriverHdi 18 * @{ 19 * 20 * @brief Provides APIs for a system ability to obtain hardware device interface (HDI) services, 21 * load or unload a device, and listen for service status, and capabilities for the hdi-gen tool to 22 * automatically generate code in the interface description language (IDL). 23 * 24 * The HDF and the IDL code generated allow system abilities to access the HDI driver service. 25 * 26 * @since 1.0 27 */ 28 29 /** 30 * @file devmgr_hdi.h 31 * 32 * @brief Defines the data structs and interface types related to device management based on the C language. 33 * 34 * @since 1.0 35 */ 36 37 #ifndef HDI_DEVICE_MANAGER_INF_H 38 #define HDI_DEVICE_MANAGER_INF_H 39 40 #include "hdf_base.h" 41 #include "hdf_dlist.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif /* __cplusplus */ 46 47 struct HdfRemoteService; 48 49 /** 50 * @brief Enumerates the types of device services. 51 */ 52 enum HDF_DEVICE_TYPE { 53 /** Local service */ 54 HDF_LOCAL_SERVICE, 55 /** Remote service */ 56 HDF_REMOTE_SERVICE, 57 }; 58 59 /** 60 * @brief Defines the device information struct. 61 */ 62 struct DeviceInfoNode { 63 /** Device service name */ 64 char *svcName; 65 /** Device type */ 66 enum HDF_DEVICE_TYPE deviceType; 67 /** Device information node, which is used to add device information to the device linked list */ 68 struct DListHead node; 69 }; 70 71 /** 72 * @brief Defines the device linked list struct. 73 */ 74 struct DeviceInfoList { 75 /** Number of devices in the linked list */ 76 uint32_t deviceCnt; 77 /** Device information linked list */ 78 struct DListHead list; 79 }; 80 81 /** 82 * @brief Defines the HDI APIs for device management. 83 * Developers using the C language can use these APIs to obtain device information and load or unload a device. 84 */ 85 struct HDIDeviceManager { 86 /** Remote service object */ 87 struct HdfRemoteService *remote; 88 89 /** 90 * @brief Releases the device linked list obtained. 91 * You can use this API to release the device linked list obtained by using <b>QueryUsableDeviceInfo</b> 92 * or <b>QueryUnusableDeviceInfo()</b>. 93 * 94 * @param self Indicates the pointer to the device manager object. 95 * @param list Indicates the pointer to the the device linked list to release. 96 */ 97 void (*FreeQueryDeviceList)(struct HDIDeviceManager *self, struct DeviceInfoList *list); 98 99 /** 100 * @brief Queries information about available devices. 101 * Use <b>FreeQueryDeviceList()</b> to release the device linked list after the device information is used. 102 * 103 * @param self Indicates the pointer to the device manager object. 104 * @param list Indicates the pointer to the device linked list, which contains the device information. 105 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 106 */ 107 int32_t (*QueryUsableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); 108 109 /** 110 * @brief Queries information about unavailable devices. 111 * Use <b>FreeQueryDeviceList()</b> to release the device linked list after the device information is used. 112 * 113 * @param self Indicates the pointer to the device manager object. 114 * @param list Indicates the pointer to the device linked list, which contains the device information. 115 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 116 */ 117 int32_t (*QueryUnusableDeviceInfo)(struct HDIDeviceManager *self, struct DeviceInfoList *list); 118 119 /** 120 * @brief Loads a device driver. 121 * 122 * @param self Indicates the pointer to the device manager object. 123 * @param serviceName Indicates the pointer to the service name of the device to load. 124 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 125 */ 126 int32_t (*LoadDevice)(struct HDIDeviceManager *self, const char *serviceName); 127 128 /** 129 * @brief Unloads a device driver. 130 * 131 * @param self Indicates the pointer to the device manager object. 132 * @param serviceName Indicates the pointer to the service name of the device to unload. 133 * @return Returns <b>HDF_SUCCESS</b> if the operation is successful; otherwise, the operation fails. 134 */ 135 int32_t (*UnloadDevice)(struct HDIDeviceManager *self, const char *serviceName); 136 }; 137 138 /** 139 * @brief Obtains an HDI device manager object. 140 * 141 * @return Returns the device manager object obtained. 142 */ 143 struct HDIDeviceManager *HDIDeviceManagerGet(void); 144 145 /** 146 * @brief Release an HDI device management object. 147 * 148 * @param devmgr Indicates the pointer to the device manager object to release. 149 */ 150 void HDIDeviceManagerRelease(struct HDIDeviceManager *devmgr); 151 #ifdef __cplusplus 152 } 153 #endif /* __cplusplus */ 154 155 #endif /* HDI_DEVICE_MANAGER_INF_H */