1 /* 2 * Copyright (c) 2023-2025 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 #ifndef HID_DDK_API_H 16 #define HID_DDK_API_H 17 18 /** 19 * @addtogroup HidDdk 20 * @{ 21 * 22 * @brief Provides HID DDK interfaces, including creating a device, sending an event, and destroying a device. 23 * 24 * @syscap SystemCapability.Driver.HID.Extension 25 * @since 11 26 * @version 1.0 27 */ 28 29 /** 30 * @file hid_ddk_api.h 31 * 32 * @brief Declares the HID DDK interfaces for the host to access an input device. 33 * 34 * File to include: <hid/hid_ddk_api.h> 35 * @since 11 36 * @version 1.0 37 */ 38 39 #include <stdint.h> 40 #include "hid_ddk_types.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif /* __cplusplus */ 45 46 /** 47 * @brief Creates a device. 48 * 49 * @permission ohos.permission.ACCESS_DDK_HID 50 * @param hidDevice Pointer to the basic information required for creating a device, including the device name, 51 * vendor ID, and product ID. 52 * @param hidEventProperties Pointer to the events of the device to be observed, including the event type and 53 * properties of the key event, absolute coordinate event, and relative coordinate event. 54 * @return Returns the device ID (a non-negative number) if the operation is successful; 55 * returns a negative number otherwise. 56 * @since 11 57 * @version 1.0 58 */ 59 int32_t OH_Hid_CreateDevice(Hid_Device *hidDevice, Hid_EventProperties *hidEventProperties); 60 61 /** 62 * @brief Sends an event list to a device. 63 * 64 * @permission ohos.permission.ACCESS_DDK_HID 65 * @param deviceId ID of the device, to which the event list is sent. 66 * @param items List of events to sent. The event information includes the event type (<b>Hid_EventType</b>), 67 * event code (<b>Hid_SynEvent</b> for a synchronization event code, <b>Hid_KeyCode</b> for a key code, 68 * <b>Hid_AbsAxes</b> for an absolute coordinate code, <b>Hid_RelAxes</b> for a relative coordinate event, 69 * and <b>Hid_MscEvent</b> for other input event code), and value input by the device. 70 * @param length Length of the event list (number of events sent at a time). 71 * @return Returns <b>0</b> if the operation is successful; returns a negative number otherwise. 72 * @since 11 73 * @version 1.0 74 */ 75 int32_t OH_Hid_EmitEvent(int32_t deviceId, const Hid_EmitItem items[], uint16_t length); 76 77 /** 78 * @brief Destroys a device. 79 * 80 * @permission ohos.permission.ACCESS_DDK_HID 81 * @param deviceId ID of the device to destroy. 82 * @return Returns <b>0</b> if the operation is successful; returns a negative number otherwise. 83 * @since 11 84 * @version 1.0 85 */ 86 int32_t OH_Hid_DestroyDevice(int32_t deviceId); 87 88 /** 89 * @brief Initializes the HID DDK. 90 * 91 * @permission ohos.permission.ACCESS_DDK_HID 92 * @return {@link HID_DDK_SUCCESS} the operation is successful. 93 * {@link HID_DDK_NO_PERM} permission check failed. 94 * {@link HID_DDK_INIT_ERROR} create DDK instance failed. 95 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 96 * @since 16 97 */ 98 int32_t OH_Hid_Init(void); 99 100 /** 101 * @brief Releases the HID DDK. 102 * 103 * @permission ohos.permission.ACCESS_DDK_HID 104 * @return {@link HID_DDK_SUCCESS} the operation is successful. 105 * {@link HID_DDK_NO_PERM} permission check failed. 106 * {@link HID_DDK_INIT_ERROR} the DDK not init. 107 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 108 * @since 16 109 */ 110 int32_t OH_Hid_Release(void); 111 112 /** 113 * @brief Open HID device by deviceId in blocking mode. 114 * 115 * @permission ohos.permission.ACCESS_DDK_HID 116 * @param deviceId ID of the device to be operated. 117 * @param interfaceIndex Interface index, which corresponds to interface which supports USB protocol HID. 118 * @param dev Device operation handle. 119 * @return {@link HID_DDK_SUCCESS} the operation is successful. 120 * {@link HID_DDK_NO_PERM} permission check failed. 121 * {@link HID_DDK_INIT_ERROR} the DDK not init. 122 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 123 * {@link HID_DDK_MEMORY_ERROR } alloc memory of dev failed. 124 * {@link HID_DDK_IO_ERROR} open device failed. 125 * {@link HID_DDK_INVALID_PARAMETER} dev is null. 126 * {@link HID_DDK_DEVICE_NOT_FOUND} device not found by deviceId. 127 * @since 16 128 */ 129 int32_t OH_Hid_Open(uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle **dev); 130 131 /** 132 * @brief Close HID device by dev. 133 * 134 * @permission ohos.permission.ACCESS_DDK_HID 135 * @param dev Device operation handle. 136 * @return {@link HID_DDK_SUCCESS} the operation is successful. 137 * {@link HID_DDK_NO_PERM} permission check failed. 138 * {@link HID_DDK_INIT_ERROR} the DDK not init. 139 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 140 * {@link HID_DDK_IO_ERROR} close device failed. 141 * {@link HID_DDK_INVALID_PARAMETER} dev is null. 142 * @since 16 143 */ 144 int32_t OH_Hid_Close(Hid_DeviceHandle **dev); 145 146 /** 147 * @brief Write an Output report to a HID device. 148 * 149 * @permission ohos.permission.ACCESS_DDK_HID 150 * @param dev Device operation handle. 151 * @param data The data to be sent. 152 * @param length The length in bytes of the data to send. 153 * @param bytesWritten The acture bytes of the data be sent. 154 * @return {@link HID_DDK_SUCCESS} the operation is successful. 155 * {@link HID_DDK_NO_PERM} permission check failed. 156 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 157 * 2.data is null; 3.length is 0; 4.length is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 158 * 5.bytesWritten is null. 159 * {@link HID_DDK_INIT_ERROR} the DDK not init. 160 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 161 * {@link HID_DDK_IO_ERROR } send data failed. 162 * @since 16 163 */ 164 int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten); 165 166 /** 167 * @brief Read an input report from the device with timeout. 168 * 169 * @permission ohos.permission.ACCESS_DDK_HID 170 * @param dev Device operation handle. 171 * @param data A buffer to put the read data into. 172 * @param bufSize A buffer size to put the read data into. 173 * @param timeout Timeout in milliseconds or -1 for blocking wait. 174 * @param bytesRead The number of bytes to read. 175 * @return {@link HID_DDK_SUCCESS} the operation is successful. 176 * {@link HID_DDK_NO_PERM} permission check failed. 177 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 178 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 179 * 5.bytesRead is null. 180 * {@link HID_DDK_INIT_ERROR} the DDK not init. 181 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 182 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 183 * {@link HID_DDK_IO_ERROR } read data failed. 184 * {@link HID_DDK_TIMEOUT } read timeout. 185 * @since 16 186 */ 187 int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, int timeout, uint32_t *bytesRead); 188 189 /** 190 * @brief Read an input report from the device. 191 * 192 * @permission ohos.permission.ACCESS_DDK_HID 193 * @param dev Device operation handle. 194 * @param data A buffer to put the read data into. 195 * @param bufSize A buffer size to put the read data into. 196 * @param bytesRead The number of bytes to read. 197 * @return {@link HID_DDK_SUCCESS} the operation is successful. 198 * {@link HID_DDK_NO_PERM} permission check failed. 199 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 200 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 201 * 5.bytesRead is null. 202 * {@link HID_DDK_INIT_ERROR} the DDK not init. 203 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 204 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 205 * {@link HID_DDK_IO_ERROR } read data failed. 206 * {@link HID_DDK_TIMEOUT } read timeout. 207 * @since 16 208 */ 209 int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, uint32_t *bytesRead); 210 211 /** 212 * @brief Set the device handle to be non-blocking. 213 * 214 * @permission ohos.permission.ACCESS_DDK_HID 215 * @param dev Device operation handle. 216 * @param nonBlock Enable or not the nonblocking reads 217 * - 1 to enable nonblocking 218 * - 0 to disable nonblocking. 219 * @return {@link HID_DDK_SUCCESS} the operation is successful. 220 * {@link HID_DDK_NO_PERM} permission check failed. 221 * {@link HID_DDK_INIT_ERROR} the DDK not init. 222 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes:1.dev is null;\n 223 * 2.nonBlock is not 1 or 0. 224 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 225 * @since 16 226 */ 227 int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonBlock); 228 229 /** 230 * @brief Get a raw info from the device. 231 * 232 * @permission ohos.permission.ACCESS_DDK_HID 233 * @param dev Device operation handle. 234 * @param rawDevInfo Vendor id, product id and bus type get from the device. 235 * @return {@link HID_DDK_SUCCESS} the operation is successful. 236 * {@link HID_DDK_NO_PERM} permission check failed. 237 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 238 * 2.rawDevInfo is null. 239 * {@link HID_DDK_INIT_ERROR} the DDK not init. 240 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 241 * {@link HID_DDK_IO_ERROR } read data failed. 242 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 243 * @since 16 244 */ 245 int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo); 246 247 /** 248 * @brief Get a raw name from the device. 249 * 250 * @permission ohos.permission.ACCESS_DDK_HID 251 * @param dev Device operation handle. 252 * @param data A buffer to put the read data into. 253 * @param bufSize A buffer size to put the read data into. 254 * @return {@link HID_DDK_SUCCESS} the operation is successful. 255 * {@link HID_DDK_NO_PERM} permission check failed. 256 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 257 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 258 * {@link HID_DDK_INIT_ERROR} the DDK not init. 259 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 260 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 261 * {@link HID_DDK_IO_ERROR } read data failed. 262 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 263 * @since 16 264 */ 265 int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t bufSize); 266 267 /** 268 * @brief Get a physical address from the device. 269 * 270 * @permission ohos.permission.ACCESS_DDK_HID 271 * @param dev Device operation handle. 272 * @param data A buffer to put the read data into. 273 * @param bufSize A buffer size to put the read data into. 274 * @return {@link HID_DDK_SUCCESS} the operation is successful. 275 * {@link HID_DDK_NO_PERM} permission check failed. 276 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 277 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 278 * {@link HID_DDK_INIT_ERROR} the DDK not init. 279 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 280 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 281 * {@link HID_DDK_IO_ERROR } read data failed. 282 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 283 * @since 16 284 */ 285 int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t bufSize); 286 287 /** 288 * @brief Get a raw unique id from the device. 289 * 290 * @permission ohos.permission.ACCESS_DDK_HID 291 * @param dev Device operation handle. 292 * @param data A buffer to put the read data into. 293 * @param bufSize A buffer size to put the read data into. 294 * @return {@link HID_DDK_SUCCESS} the operation is successful. 295 * {@link HID_DDK_NO_PERM} permission check failed. 296 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 297 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 298 * {@link HID_DDK_INIT_ERROR} the DDK not init. 299 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 300 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 301 * {@link HID_DDK_IO_ERROR } read data failed. 302 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 303 * @since 16 304 */ 305 int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize); 306 307 /** 308 * @brief Send a report to the device. 309 * 310 * @permission ohos.permission.ACCESS_DDK_HID 311 * @param dev Device operation handle. 312 * @param reportType Report type will be sent. 313 * @param data The data to be sent. 314 * @param length The length in bytes of the data to send. 315 * @return {@link HID_DDK_SUCCESS} the operation is successful. 316 * {@link HID_DDK_NO_PERM} permission check failed. 317 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 318 * 2.data is null; 3.length is 0; 4.length is greater than HID_MAX_REPORT_BUFFER_SIZE. 319 * {@link HID_DDK_INIT_ERROR} the DDK not init. 320 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 321 * {@link HID_DDK_IO_ERROR } send data failed. 322 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 323 * @since 16 324 */ 325 int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length); 326 327 /** 328 * @brief Get a report from the device. 329 * 330 * @permission ohos.permission.ACCESS_DDK_HID 331 * @param dev Device operation handle. 332 * @param reportType Report type get from device. 333 * @param data A buffer to put the read data into. 334 * @param bufSize A buffer size to put the read data into. 335 * @return {@link HID_DDK_SUCCESS} the operation is successful. 336 * {@link HID_DDK_NO_PERM} permission check failed. 337 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 338 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 339 * {@link HID_DDK_INIT_ERROR} the DDK not init. 340 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 341 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 342 * {@link HID_DDK_IO_ERROR } read data failed. 343 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 344 * @since 16 345 */ 346 int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t bufSize); 347 348 /** 349 * @brief Get a report descriptor from the device. 350 * 351 * @permission ohos.permission.ACCESS_DDK_HID 352 * @param dev Device operation handle. 353 * @param buf The buffer to copy descriptor into. 354 * @param bufSize The size of the buffer in bytes, the recommended value is HID_MAX_REPORT_DESCRIPTOR_SIZE. 355 * @param bytesRead The number of bytes to read. 356 * @return {@link HID_DDK_SUCCESS} if the operation is successful. 357 * {@link HID_DDK_NO_PERM} permission check failed. 358 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 359 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 360 * 5.bytesRead is null. 361 * {@link HID_DDK_INIT_ERROR} the DDK not init. 362 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 363 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 364 * {@link HID_DDK_IO_ERROR } read data failed. 365 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 366 * @since 16 367 */ 368 int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t bufSize, uint32_t *bytesRead); 369 #ifdef __cplusplus 370 } 371 #endif /* __cplusplus */ 372 373 #endif // HID_DDK_API_H 374