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 * {@link HID_DDK_NULL_PTR} the device does not exist. 101 * @since 11 102 * @version 1.0 103 */ 104 int32_t OH_Hid_DestroyDevice(int32_t deviceId); 105 106 /** 107 * @brief Initializes the HID DDK. 108 * 109 * @permission ohos.permission.ACCESS_DDK_HID 110 * @return {@link HID_DDK_SUCCESS} the operation is successful. 111 * {@link HID_DDK_NO_PERM} permission check failed. 112 * {@link HID_DDK_INIT_ERROR} create DDK instance failed. 113 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 114 * @since 18 115 */ 116 int32_t OH_Hid_Init(void); 117 118 /** 119 * @brief Releases the HID DDK. 120 * 121 * @permission ohos.permission.ACCESS_DDK_HID 122 * @return {@link HID_DDK_SUCCESS} the operation is successful. 123 * {@link HID_DDK_NO_PERM} permission check failed. 124 * {@link HID_DDK_INIT_ERROR} the DDK not init. 125 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 126 * @since 18 127 */ 128 int32_t OH_Hid_Release(void); 129 130 /** 131 * @brief Open HID device by deviceId in blocking mode. 132 * 133 * @permission ohos.permission.ACCESS_DDK_HID 134 * @param deviceId ID of the device to be operated. 135 * @param interfaceIndex Interface index, which corresponds to interface which supports USB protocol HID. 136 * @param dev Device operation handle. 137 * @return {@link HID_DDK_SUCCESS} the operation is successful. 138 * {@link HID_DDK_NO_PERM} permission check failed. 139 * {@link HID_DDK_INIT_ERROR} the DDK not init. 140 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 141 * {@link HID_DDK_MEMORY_ERROR } alloc memory of dev failed. 142 * {@link HID_DDK_IO_ERROR} open device failed. 143 * {@link HID_DDK_INVALID_PARAMETER} dev is null. 144 * {@link HID_DDK_DEVICE_NOT_FOUND} device not found by deviceId. 145 * @since 18 146 */ 147 int32_t OH_Hid_Open(uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle **dev); 148 149 /** 150 * @brief Close HID device by dev. 151 * 152 * @permission ohos.permission.ACCESS_DDK_HID 153 * @param dev Device operation handle. 154 * @return {@link HID_DDK_SUCCESS} the operation is successful. 155 * {@link HID_DDK_NO_PERM} permission check failed. 156 * {@link HID_DDK_INIT_ERROR} the DDK not init. 157 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 158 * {@link HID_DDK_IO_ERROR} close device failed. 159 * {@link HID_DDK_INVALID_PARAMETER} dev is null. 160 * @since 18 161 */ 162 int32_t OH_Hid_Close(Hid_DeviceHandle **dev); 163 164 /** 165 * @brief Write an Output report to a HID device. 166 * 167 * @permission ohos.permission.ACCESS_DDK_HID 168 * @param dev Device operation handle. 169 * @param data The data to be sent. 170 * @param length The length in bytes of the data to send. 171 * @param bytesWritten The acture bytes of the data be sent. 172 * @return {@link HID_DDK_SUCCESS} the operation is successful. 173 * {@link HID_DDK_NO_PERM} permission check failed. 174 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 175 * 2.data is null; 3.length is 0; 4.length is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 176 * 5.bytesWritten is null. 177 * {@link HID_DDK_INIT_ERROR} the DDK not init. 178 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 179 * {@link HID_DDK_IO_ERROR } send data failed. 180 * @since 18 181 */ 182 int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten); 183 184 /** 185 * @brief Read an input report from the device with timeout. 186 * 187 * @permission ohos.permission.ACCESS_DDK_HID 188 * @param dev Device operation handle. 189 * @param data A buffer to put the read data into. 190 * @param bufSize A buffer size to put the read data into. 191 * @param timeout Timeout in milliseconds or -1 for blocking wait. 192 * @param bytesRead The number of bytes to read. 193 * @return {@link HID_DDK_SUCCESS} the operation is successful. 194 * {@link HID_DDK_NO_PERM} permission check failed. 195 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 196 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 197 * 5.bytesRead is null. 198 * {@link HID_DDK_INIT_ERROR} the DDK not init. 199 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 200 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 201 * {@link HID_DDK_IO_ERROR } read data failed. 202 * {@link HID_DDK_TIMEOUT } read timeout. 203 * @since 18 204 */ 205 int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, int timeout, uint32_t *bytesRead); 206 207 /** 208 * @brief Read an input report from the device. 209 * 210 * @permission ohos.permission.ACCESS_DDK_HID 211 * @param dev Device operation handle. 212 * @param data A buffer to put the read data into. 213 * @param bufSize A buffer size to put the read data into. 214 * @param bytesRead The number of bytes to read. 215 * @return {@link HID_DDK_SUCCESS} the operation is successful. 216 * {@link HID_DDK_NO_PERM} permission check failed. 217 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 218 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 219 * 5.bytesRead is null. 220 * {@link HID_DDK_INIT_ERROR} the DDK not init. 221 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 222 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 223 * {@link HID_DDK_IO_ERROR } read data failed. 224 * {@link HID_DDK_TIMEOUT } read timeout. 225 * @since 18 226 */ 227 int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, uint32_t *bytesRead); 228 229 /** 230 * @brief Set the device handle to be non-blocking. 231 * 232 * @permission ohos.permission.ACCESS_DDK_HID 233 * @param dev Device operation handle. 234 * @param nonBlock Enable or not the nonblocking reads 235 * - 1 to enable nonblocking 236 * - 0 to disable nonblocking. 237 * @return {@link HID_DDK_SUCCESS} the operation is successful. 238 * {@link HID_DDK_NO_PERM} permission check failed. 239 * {@link HID_DDK_INIT_ERROR} the DDK not init. 240 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes:1.dev is null;\n 241 * 2.nonBlock is not 1 or 0. 242 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 243 * @since 18 244 */ 245 int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonBlock); 246 247 /** 248 * @brief Get a raw info from the device. 249 * 250 * @permission ohos.permission.ACCESS_DDK_HID 251 * @param dev Device operation handle. 252 * @param rawDevInfo Vendor id, product id and bus type get from the device. 253 * @return {@link HID_DDK_SUCCESS} the operation is successful. 254 * {@link HID_DDK_NO_PERM} permission check failed. 255 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 256 * 2.rawDevInfo is null. 257 * {@link HID_DDK_INIT_ERROR} the DDK not init. 258 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 259 * {@link HID_DDK_IO_ERROR } read data failed. 260 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 261 * @since 18 262 */ 263 int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo); 264 265 /** 266 * @brief Get a raw name from the device. 267 * 268 * @permission ohos.permission.ACCESS_DDK_HID 269 * @param dev Device operation handle. 270 * @param data A buffer to put the read data into. 271 * @param bufSize A buffer size to put the read data into. 272 * @return {@link HID_DDK_SUCCESS} the operation is successful. 273 * {@link HID_DDK_NO_PERM} permission check failed. 274 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 275 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 276 * {@link HID_DDK_INIT_ERROR} the DDK not init. 277 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 278 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 279 * {@link HID_DDK_IO_ERROR } read data failed. 280 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 281 * @since 18 282 */ 283 int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t bufSize); 284 285 /** 286 * @brief Get a physical address from the device. 287 * 288 * @permission ohos.permission.ACCESS_DDK_HID 289 * @param dev Device operation handle. 290 * @param data A buffer to put the read data into. 291 * @param bufSize A buffer size to put the read data into. 292 * @return {@link HID_DDK_SUCCESS} the operation is successful. 293 * {@link HID_DDK_NO_PERM} permission check failed. 294 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 295 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 296 * {@link HID_DDK_INIT_ERROR} the DDK not init. 297 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 298 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 299 * {@link HID_DDK_IO_ERROR } read data failed. 300 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 301 * @since 18 302 */ 303 int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t bufSize); 304 305 /** 306 * @brief Get a raw unique id from the device. 307 * 308 * @permission ohos.permission.ACCESS_DDK_HID 309 * @param dev Device operation handle. 310 * @param data A buffer to put the read data into. 311 * @param bufSize A buffer size to put the read data into. 312 * @return {@link HID_DDK_SUCCESS} the operation is successful. 313 * {@link HID_DDK_NO_PERM} permission check failed. 314 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 315 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 316 * {@link HID_DDK_INIT_ERROR} the DDK not init. 317 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 318 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 319 * {@link HID_DDK_IO_ERROR } read data failed. 320 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 321 * @since 18 322 */ 323 int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize); 324 325 /** 326 * @brief Send a report to the device. 327 * 328 * @permission ohos.permission.ACCESS_DDK_HID 329 * @param dev Device operation handle. 330 * @param reportType Report type will be sent. 331 * @param data The data to be sent. 332 * @param length The length in bytes of the data to send. 333 * @return {@link HID_DDK_SUCCESS} the operation is successful. 334 * {@link HID_DDK_NO_PERM} permission check failed. 335 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 336 * 2.data is null; 3.length is 0; 4.length is greater than HID_MAX_REPORT_BUFFER_SIZE. 337 * {@link HID_DDK_INIT_ERROR} the DDK not init. 338 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 339 * {@link HID_DDK_IO_ERROR } send data failed. 340 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 341 * @since 18 342 */ 343 int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length); 344 345 /** 346 * @brief Get a report from the device. 347 * 348 * @permission ohos.permission.ACCESS_DDK_HID 349 * @param dev Device operation handle. 350 * @param reportType Report type get from device. 351 * @param data A buffer to put the read data into. 352 * @param bufSize A buffer size to put the read data into. 353 * @return {@link HID_DDK_SUCCESS} the operation is successful. 354 * {@link HID_DDK_NO_PERM} permission check failed. 355 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 356 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE. 357 * {@link HID_DDK_INIT_ERROR} the DDK not init. 358 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 359 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 360 * {@link HID_DDK_IO_ERROR } read data failed. 361 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 362 * @since 18 363 */ 364 int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t bufSize); 365 366 /** 367 * @brief Get a report descriptor from the device. 368 * 369 * @permission ohos.permission.ACCESS_DDK_HID 370 * @param dev Device operation handle. 371 * @param buf The buffer to copy descriptor into. 372 * @param bufSize The size of the buffer in bytes, the recommended value is HID_MAX_REPORT_DESCRIPTOR_SIZE. 373 * @param bytesRead The number of bytes to read. 374 * @return {@link HID_DDK_SUCCESS} if the operation is successful. 375 * {@link HID_DDK_NO_PERM} permission check failed. 376 * {@link HID_DDK_INVALID_PARAMETER} parameter check failed. Possible causes: 1.dev is null;\n 377 * 2.data is null; 3.bufSize is 0; 4.bufSize is greater than HID_MAX_REPORT_BUFFER_SIZE;\n 378 * 5.bytesRead is null. 379 * {@link HID_DDK_INIT_ERROR} the DDK not init. 380 * {@link HID_DDK_SERVICE_ERROR} communication with the ddk service failed. 381 * {@link HID_DDK_MEMORY_ERROR } the memory of data copies failed. 382 * {@link HID_DDK_IO_ERROR } read data failed. 383 * {@link HID_DDK_INVALID_OPERATION } the operation is not supported. 384 * @since 18 385 */ 386 int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t bufSize, uint32_t *bytesRead); 387 /** @} */ 388 #ifdef __cplusplus 389 } 390 #endif /* __cplusplus */ 391 392 #endif // HID_DDK_API_H 393