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