1 /******************************************************* 2 HIDAPI - Multi-Platform library for 3 communication with HID devices. 4 5 Alan Ott 6 Signal 11 Software 7 8 8/22/2009 9 10 Copyright 2009, All Rights Reserved. 11 12 At the discretion of the user of this library, 13 this software may be licensed under the terms of the 14 GNU General Public License v3, a BSD-Style license, or the 15 original HIDAPI license as outlined in the LICENSE.txt, 16 LICENSE-gpl3.txt, LICENSE-bsd.txt, and LICENSE-orig.txt 17 files located at the root of the source distribution. 18 These files may also be found in the public source 19 code repository located at: 20 https://github.com/libusb/hidapi . 21 ********************************************************/ 22 23 /** @file 24 * @defgroup API hidapi API 25 */ 26 27 #ifndef HIDAPI_H__ 28 #define HIDAPI_H__ 29 30 #include <wchar.h> 31 32 #if defined(_WIN32) && !defined(NAMESPACE) && (0) /* SDL: don't export hidapi syms */ 33 #define HID_API_EXPORT __declspec(dllexport) 34 #define HID_API_CALL 35 #else 36 #ifndef HID_API_EXPORT 37 #define HID_API_EXPORT /**< API export macro */ 38 #endif 39 #ifndef HID_API_CALL 40 #define HID_API_CALL /**< API call macro */ 41 #endif 42 #endif 43 44 #define HID_API_EXPORT_CALL HID_API_EXPORT HID_API_CALL /**< API export and call macro*/ 45 46 #if defined(__cplusplus) && !defined(NAMESPACE) 47 extern "C" { 48 #endif 49 #ifdef NAMESPACE 50 namespace NAMESPACE { 51 #endif 52 53 struct hid_device_; 54 typedef struct hid_device_ hid_device; /**< opaque hidapi structure */ 55 56 /** hidapi info structure */ 57 struct hid_device_info { 58 /** Platform-specific device path */ 59 char *path; 60 /** Device Vendor ID */ 61 unsigned short vendor_id; 62 /** Device Product ID */ 63 unsigned short product_id; 64 /** Serial Number */ 65 wchar_t *serial_number; 66 /** Device Release Number in binary-coded decimal, 67 also known as Device Version Number */ 68 unsigned short release_number; 69 /** Manufacturer String */ 70 wchar_t *manufacturer_string; 71 /** Product string */ 72 wchar_t *product_string; 73 /** Usage Page for this Device/Interface 74 (Windows/Mac only). */ 75 unsigned short usage_page; 76 /** Usage for this Device/Interface 77 (Windows/Mac only).*/ 78 unsigned short usage; 79 /** The USB interface which this logical device 80 represents. Valid on both Linux implementations 81 in all cases, and valid on the Windows implementation 82 only if the device contains more than one interface. */ 83 int interface_number; 84 85 /** Additional information about the USB interface. 86 Valid on libusb and Android implementations. */ 87 int interface_class; 88 int interface_subclass; 89 int interface_protocol; 90 91 /** Pointer to the next device */ 92 struct hid_device_info *next; 93 }; 94 95 96 /** @brief Initialize the HIDAPI library. 97 98 This function initializes the HIDAPI library. Calling it is not 99 strictly necessary, as it will be called automatically by 100 hid_enumerate() and any of the hid_open_*() functions if it is 101 needed. This function should be called at the beginning of 102 execution however, if there is a chance of HIDAPI handles 103 being opened by different threads simultaneously. 104 105 @ingroup API 106 107 @returns 108 This function returns 0 on success and -1 on error. 109 */ 110 int HID_API_EXPORT HID_API_CALL hid_init(void); 111 112 /** @brief Finalize the HIDAPI library. 113 114 This function frees all of the static data associated with 115 HIDAPI. It should be called at the end of execution to avoid 116 memory leaks. 117 118 @ingroup API 119 120 @returns 121 This function returns 0 on success and -1 on error. 122 */ 123 int HID_API_EXPORT HID_API_CALL hid_exit(void); 124 125 /** @brief Enumerate the HID Devices. 126 127 This function returns a linked list of all the HID devices 128 attached to the system which match vendor_id and product_id. 129 If @p vendor_id is set to 0 then any vendor matches. 130 If @p product_id is set to 0 then any product matches. 131 If @p vendor_id and @p product_id are both set to 0, then 132 all HID devices will be returned. 133 134 @ingroup API 135 @param vendor_id The Vendor ID (VID) of the types of device 136 to open. 137 @param product_id The Product ID (PID) of the types of 138 device to open. 139 140 @returns 141 This function returns a pointer to a linked list of type 142 struct #hid_device, containing information about the HID devices 143 attached to the system, or NULL in the case of failure. Free 144 this linked list by calling hid_free_enumeration(). 145 */ 146 struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id); 147 148 /** @brief Free an enumeration Linked List 149 150 This function frees a linked list created by hid_enumerate(). 151 152 @ingroup API 153 @param devs Pointer to a list of struct_device returned from 154 hid_enumerate(). 155 */ 156 void HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs); 157 158 /** @brief Open a HID device using a Vendor ID (VID), Product ID 159 (PID) and optionally a serial number. 160 161 If @p serial_number is NULL, the first device with the 162 specified VID and PID is opened. 163 164 @ingroup API 165 @param vendor_id The Vendor ID (VID) of the device to open. 166 @param product_id The Product ID (PID) of the device to open. 167 @param serial_number The Serial Number of the device to open 168 (Optionally NULL). 169 170 @returns 171 This function returns a pointer to a #hid_device object on 172 success or NULL on failure. 173 */ 174 HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); 175 176 /** @brief Open a HID device by its path name. 177 178 The path name be determined by calling hid_enumerate(), or a 179 platform-specific path name can be used (eg: /dev/hidraw0 on 180 Linux). 181 182 @ingroup API 183 @param path The path name of the device to open 184 185 @returns 186 This function returns a pointer to a #hid_device object on 187 success or NULL on failure. 188 */ 189 HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path, int bExclusive /* = false */); 190 191 /** @brief Write an Output report to a HID device. 192 193 The first byte of @p data[] must contain the Report ID. For 194 devices which only support a single report, this must be set 195 to 0x0. The remaining bytes contain the report data. Since 196 the Report ID is mandatory, calls to hid_write() will always 197 contain one more byte than the report contains. For example, 198 if a hid report is 16 bytes long, 17 bytes must be passed to 199 hid_write(), the Report ID (or 0x0, for devices with a 200 single report), followed by the report data (16 bytes). In 201 this example, the length passed in would be 17. 202 203 hid_write() will send the data on the first OUT endpoint, if 204 one exists. If it does not, it will send the data through 205 the Control Endpoint (Endpoint 0). 206 207 @ingroup API 208 @param device A device handle returned from hid_open(). 209 @param data The data to send, including the report number as 210 the first byte. 211 @param length The length in bytes of the data to send. 212 213 @returns 214 This function returns the actual number of bytes written and 215 -1 on error. 216 */ 217 int HID_API_EXPORT HID_API_CALL hid_write(hid_device *device, const unsigned char *data, size_t length); 218 219 /** @brief Read an Input report from a HID device with timeout. 220 221 Input reports are returned 222 to the host through the INTERRUPT IN endpoint. The first byte will 223 contain the Report number if the device uses numbered reports. 224 225 @ingroup API 226 @param device A device handle returned from hid_open(). 227 @param data A buffer to put the read data into. 228 @param length The number of bytes to read. For devices with 229 multiple reports, make sure to read an extra byte for 230 the report number. 231 @param milliseconds timeout in milliseconds or -1 for blocking wait. 232 233 @returns 234 This function returns the actual number of bytes read and 235 -1 on error. If no packet was available to be read within 236 the timeout period, this function returns 0. 237 */ 238 int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *device, unsigned char *data, size_t length, int milliseconds); 239 240 /** @brief Read an Input report from a HID device. 241 242 Input reports are returned 243 to the host through the INTERRUPT IN endpoint. The first byte will 244 contain the Report number if the device uses numbered reports. 245 246 @ingroup API 247 @param device A device handle returned from hid_open(). 248 @param data A buffer to put the read data into. 249 @param length The number of bytes to read. For devices with 250 multiple reports, make sure to read an extra byte for 251 the report number. 252 253 @returns 254 This function returns the actual number of bytes read and 255 -1 on error. If no packet was available to be read and 256 the handle is in non-blocking mode, this function returns 0. 257 */ 258 int HID_API_EXPORT HID_API_CALL hid_read(hid_device *device, unsigned char *data, size_t length); 259 260 /** @brief Set the device handle to be non-blocking. 261 262 In non-blocking mode calls to hid_read() will return 263 immediately with a value of 0 if there is no data to be 264 read. In blocking mode, hid_read() will wait (block) until 265 there is data to read before returning. 266 267 Nonblocking can be turned on and off at any time. 268 269 @ingroup API 270 @param device A device handle returned from hid_open(). 271 @param nonblock enable or not the nonblocking reads 272 - 1 to enable nonblocking 273 - 0 to disable nonblocking. 274 275 @returns 276 This function returns 0 on success and -1 on error. 277 */ 278 int HID_API_EXPORT HID_API_CALL hid_set_nonblocking(hid_device *device, int nonblock); 279 280 /** @brief Send a Feature report to the device. 281 282 Feature reports are sent over the Control endpoint as a 283 Set_Report transfer. The first byte of @p data[] must 284 contain the Report ID. For devices which only support a 285 single report, this must be set to 0x0. The remaining bytes 286 contain the report data. Since the Report ID is mandatory, 287 calls to hid_send_feature_report() will always contain one 288 more byte than the report contains. For example, if a hid 289 report is 16 bytes long, 17 bytes must be passed to 290 hid_send_feature_report(): the Report ID (or 0x0, for 291 devices which do not use numbered reports), followed by the 292 report data (16 bytes). In this example, the length passed 293 in would be 17. 294 295 @ingroup API 296 @param device A device handle returned from hid_open(). 297 @param data The data to send, including the report number as 298 the first byte. 299 @param length The length in bytes of the data to send, including 300 the report number. 301 302 @returns 303 This function returns the actual number of bytes written and 304 -1 on error. 305 */ 306 int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *device, const unsigned char *data, size_t length); 307 308 /** @brief Get a feature report from a HID device. 309 310 Set the first byte of @p data[] to the Report ID of the 311 report to be read. Make sure to allow space for this 312 extra byte in @p data[]. Upon return, the first byte will 313 still contain the Report ID, and the report data will 314 start in data[1]. 315 316 @ingroup API 317 @param device A device handle returned from hid_open(). 318 @param data A buffer to put the read data into, including 319 the Report ID. Set the first byte of @p data[] to the 320 Report ID of the report to be read, or set it to zero 321 if your device does not use numbered reports. 322 @param length The number of bytes to read, including an 323 extra byte for the report ID. The buffer can be longer 324 than the actual report. 325 326 @returns 327 This function returns the number of bytes read plus 328 one for the report ID (which is still in the first 329 byte), or -1 on error. 330 */ 331 int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *device, unsigned char *data, size_t length); 332 333 /** @brief Close a HID device. 334 335 @ingroup API 336 @param device A device handle returned from hid_open(). 337 */ 338 void HID_API_EXPORT HID_API_CALL hid_close(hid_device *device); 339 340 /** @brief Get The Manufacturer String from a HID device. 341 342 @ingroup API 343 @param device A device handle returned from hid_open(). 344 @param string A wide string buffer to put the data into. 345 @param maxlen The length of the buffer in multiples of wchar_t. 346 347 @returns 348 This function returns 0 on success and -1 on error. 349 */ 350 int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *device, wchar_t *string, size_t maxlen); 351 352 /** @brief Get The Product String from a HID device. 353 354 @ingroup API 355 @param device A device handle returned from hid_open(). 356 @param string A wide string buffer to put the data into. 357 @param maxlen The length of the buffer in multiples of wchar_t. 358 359 @returns 360 This function returns 0 on success and -1 on error. 361 */ 362 int HID_API_EXPORT_CALL hid_get_product_string(hid_device *device, wchar_t *string, size_t maxlen); 363 364 /** @brief Get The Serial Number String from a HID device. 365 366 @ingroup API 367 @param device A device handle returned from hid_open(). 368 @param string A wide string buffer to put the data into. 369 @param maxlen The length of the buffer in multiples of wchar_t. 370 371 @returns 372 This function returns 0 on success and -1 on error. 373 */ 374 int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *device, wchar_t *string, size_t maxlen); 375 376 /** @brief Get a string from a HID device, based on its string index. 377 378 @ingroup API 379 @param device A device handle returned from hid_open(). 380 @param string_index The index of the string to get. 381 @param string A wide string buffer to put the data into. 382 @param maxlen The length of the buffer in multiples of wchar_t. 383 384 @returns 385 This function returns 0 on success and -1 on error. 386 */ 387 int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *device, int string_index, wchar_t *string, size_t maxlen); 388 389 /** @brief Get a string describing the last error which occurred. 390 391 @ingroup API 392 @param device A device handle returned from hid_open(). 393 394 @returns 395 This function returns a string containing the last error 396 which occurred or NULL if none has occurred. 397 */ 398 HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *device); 399 400 #if defined(__cplusplus) && !defined(NAMESPACE) 401 } 402 #endif 403 #ifdef NAMESPACE 404 } 405 #endif 406 407 #endif 408 409