Atlas - hidapi.h
Home / ext / SDL / src / hidapi / hidapi Lines: 1 | Size: 21727 bytes [Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)][FILE BEGIN]1/******************************************************* 2 HIDAPI - Multi-Platform library for 3 communication with HID devices. 4 5 Alan Ott 6 Signal 11 Software 7 8 libusb/hidapi Team 9 10 Copyright 2023, 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/* #480: this is to be refactored properly for v1.0 */ 33#ifdef _WIN32 34 #ifndef HID_API_NO_EXPORT_DEFINE 35 #define HID_API_EXPORT __declspec(dllexport) 36 #endif 37#endif 38#ifndef HID_API_EXPORT 39 #define HID_API_EXPORT /**< API export macro */ 40#endif 41/* To be removed in v1.0 */ 42#define HID_API_CALL /**< API call macro */ 43 44#define HID_API_EXPORT_CALL HID_API_EXPORT HID_API_CALL /**< API export and call macro*/ 45 46/** @brief Static/compile-time major version of the library. 47 48 @ingroup API 49*/ 50#define HID_API_VERSION_MAJOR 0 51/** @brief Static/compile-time minor version of the library. 52 53 @ingroup API 54*/ 55#define HID_API_VERSION_MINOR 14 56/** @brief Static/compile-time patch version of the library. 57 58 @ingroup API 59*/ 60#define HID_API_VERSION_PATCH 0 61 62/* Helper macros */ 63#define HID_API_AS_STR_IMPL(x) #x 64#define HID_API_AS_STR(x) HID_API_AS_STR_IMPL(x) 65#define HID_API_TO_VERSION_STR(v1, v2, v3) HID_API_AS_STR(v1.v2.v3) 66 67/** @brief Coverts a version as Major/Minor/Patch into a number: 68 <8 bit major><16 bit minor><8 bit patch>. 69 70 This macro was added in version 0.12.0. 71 72 Convenient function to be used for compile-time checks, like: 73 @code{.c} 74 #if HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0) 75 @endcode 76 77 @ingroup API 78*/ 79#define HID_API_MAKE_VERSION(mj, mn, p) (((mj) << 24) | ((mn) << 8) | (p)) 80 81/** @brief Static/compile-time version of the library. 82 83 This macro was added in version 0.12.0. 84 85 @see @ref HID_API_MAKE_VERSION. 86 87 @ingroup API 88*/ 89#define HID_API_VERSION HID_API_MAKE_VERSION(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH) 90 91/** @brief Static/compile-time string version of the library. 92 93 @ingroup API 94*/ 95#define HID_API_VERSION_STR HID_API_TO_VERSION_STR(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH) 96 97/** @brief Maximum expected HID Report descriptor size in bytes. 98 99 Since version 0.13.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 13, 0) 100 101 @ingroup API 102*/ 103#define HID_API_MAX_REPORT_DESCRIPTOR_SIZE 4096 104 105#ifdef __cplusplus 106extern "C" { 107#endif 108#ifndef DEFINED_HID_TYPES 109#define DEFINED_HID_TYPES 110 /** A structure to hold the version numbers. */ 111 struct hid_api_version { 112 int major; /**< major version number */ 113 int minor; /**< minor version number */ 114 int patch; /**< patch version number */ 115 }; 116 117 struct hid_device_; 118 typedef struct hid_device_ hid_device; /**< opaque hidapi structure */ 119 120 /** @brief HID underlying bus types. 121 122 @ingroup API 123 */ 124 typedef enum { 125 /** Unknown bus type */ 126 HID_API_BUS_UNKNOWN = 0x00, 127 128 /** USB bus 129 Specifications: 130 https://usb.org/hid */ 131 HID_API_BUS_USB = 0x01, 132 133 /** Bluetooth or Bluetooth LE bus 134 Specifications: 135 https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/ 136 https://www.bluetooth.com/specifications/specs/hid-service-1-0/ 137 https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */ 138 HID_API_BUS_BLUETOOTH = 0x02, 139 140 /** I2C bus 141 Specifications: 142 https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */ 143 HID_API_BUS_I2C = 0x03, 144 145 /** SPI bus 146 Specifications: 147 https://www.microsoft.com/download/details.aspx?id=103325 */ 148 HID_API_BUS_SPI = 0x04, 149 } hid_bus_type; 150 151 /** hidapi info structure */ 152 struct hid_device_info { 153 /** Platform-specific device path */ 154 char *path; 155 /** Device Vendor ID */ 156 unsigned short vendor_id; 157 /** Device Product ID */ 158 unsigned short product_id; 159 /** Serial Number */ 160 wchar_t *serial_number; 161 /** Device Release Number in binary-coded decimal, 162 also known as Device Version Number */ 163 unsigned short release_number; 164 /** Manufacturer String */ 165 wchar_t *manufacturer_string; 166 /** Product string */ 167 wchar_t *product_string; 168 /** Usage Page for this Device/Interface 169 (Windows/Mac/hidraw only) */ 170 unsigned short usage_page; 171 /** Usage for this Device/Interface 172 (Windows/Mac/hidraw only) */ 173 unsigned short usage; 174 /** The USB interface which this logical device 175 represents. 176 177 Valid only if the device is a USB HID device. 178 Set to -1 in all other cases. 179 */ 180 int interface_number; 181 182 /** Pointer to the next device */ 183 struct hid_device_info *next; 184 185 /** Underlying bus type 186 Since version 0.13.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 13, 0) 187 */ 188 hid_bus_type bus_type; 189 190 /** Additional information about the USB interface. 191 (libusb only) */ 192 int interface_class; 193 int interface_subclass; 194 int interface_protocol; 195 }; 196 197#endif /* DEFINED_HID_TYPES */ 198 199 200 /** @brief Initialize the HIDAPI library. 201 202 This function initializes the HIDAPI library. Calling it is not 203 strictly necessary, as it will be called automatically by 204 hid_enumerate() and any of the hid_open_*() functions if it is 205 needed. This function should be called at the beginning of 206 execution however, if there is a chance of HIDAPI handles 207 being opened by different threads simultaneously. 208 209 @ingroup API 210 211 @returns 212 This function returns 0 on success and -1 on error. 213 Call hid_error(NULL) to get the failure reason. 214 */ 215 int HID_API_EXPORT HID_API_CALL hid_init(void); 216 217 /** @brief Finalize the HIDAPI library. 218 219 This function frees all of the static data associated with 220 HIDAPI. It should be called at the end of execution to avoid 221 memory leaks. 222 223 @ingroup API 224 225 @returns 226 This function returns 0 on success and -1 on error. 227 */ 228 int HID_API_EXPORT HID_API_CALL hid_exit(void); 229 230 /** @brief Enumerate the HID Devices. 231 232 This function returns a linked list of all the HID devices 233 attached to the system which match vendor_id and product_id. 234 If @p vendor_id is set to 0 then any vendor matches. 235 If @p product_id is set to 0 then any product matches. 236 If @p vendor_id and @p product_id are both set to 0, then 237 all HID devices will be returned. 238 239 @ingroup API 240 @param vendor_id The Vendor ID (VID) of the types of device 241 to open. 242 @param product_id The Product ID (PID) of the types of 243 device to open. 244 245 @returns 246 This function returns a pointer to a linked list of type 247 struct #hid_device_info, containing information about the HID devices 248 attached to the system, 249 or NULL in the case of failure or if no HID devices present in the system. 250 Call hid_error(NULL) to get the failure reason. 251 252 @note The returned value by this function must to be freed by calling hid_free_enumeration(), 253 when not needed anymore. 254 */ 255 struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id); 256 257 /** @brief Free an enumeration Linked List 258 259 This function frees a linked list created by hid_enumerate(). 260 261 @ingroup API 262 @param devs Pointer to a list of struct_device returned from 263 hid_enumerate(). 264 */ 265 void HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs); 266 267 /** @brief Open a HID device using a Vendor ID (VID), Product ID 268 (PID) and optionally a serial number. 269 270 If @p serial_number is NULL, the first device with the 271 specified VID and PID is opened. 272 273 @ingroup API 274 @param vendor_id The Vendor ID (VID) of the device to open. 275 @param product_id The Product ID (PID) of the device to open. 276 @param serial_number The Serial Number of the device to open 277 (Optionally NULL). 278 279 @returns 280 This function returns a pointer to a #hid_device object on 281 success or NULL on failure. 282 Call hid_error(NULL) to get the failure reason. 283 284 @note The returned object must be freed by calling hid_close(), 285 when not needed anymore. 286 */ 287 HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number); 288 289 /** @brief Open a HID device by its path name. 290 291 The path name be determined by calling hid_enumerate(), or a 292 platform-specific path name can be used (eg: /dev/hidraw0 on 293 Linux). 294 295 @ingroup API 296 @param path The path name of the device to open 297 298 @returns 299 This function returns a pointer to a #hid_device object on 300 success or NULL on failure. 301 Call hid_error(NULL) to get the failure reason. 302 303 @note The returned object must be freed by calling hid_close(), 304 when not needed anymore. 305 */ 306 HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path); 307 308 /** @brief Write an Output report to a HID device. 309 310 The first byte of @p data[] must contain the Report ID. For 311 devices which only support a single report, this must be set 312 to 0x0. The remaining bytes contain the report data. Since 313 the Report ID is mandatory, calls to hid_write() will always 314 contain one more byte than the report contains. For example, 315 if a hid report is 16 bytes long, 17 bytes must be passed to 316 hid_write(), the Report ID (or 0x0, for devices with a 317 single report), followed by the report data (16 bytes). In 318 this example, the length passed in would be 17. 319 320 hid_write() will send the data on the first OUT endpoint, if 321 one exists. If it does not, it will send the data through 322 the Control Endpoint (Endpoint 0). 323 324 @ingroup API 325 @param dev A device handle returned from hid_open(). 326 @param data The data to send, including the report number as 327 the first byte. 328 @param length The length in bytes of the data to send. 329 330 @returns 331 This function returns the actual number of bytes written and 332 -1 on error. 333 Call hid_error(dev) to get the failure reason. 334 */ 335 int HID_API_EXPORT HID_API_CALL hid_write(hid_device *dev, const unsigned char *data, size_t length); 336 337 /** @brief Read an Input report from a HID device with timeout. 338 339 Input reports are returned 340 to the host through the INTERRUPT IN endpoint. The first byte will 341 contain the Report number if the device uses numbered reports. 342 343 @ingroup API 344 @param dev A device handle returned from hid_open(). 345 @param data A buffer to put the read data into. 346 @param length The number of bytes to read. For devices with 347 multiple reports, make sure to read an extra byte for 348 the report number. 349 @param milliseconds timeout in milliseconds or -1 for blocking wait. 350 351 @returns 352 This function returns the actual number of bytes read and 353 -1 on error. 354 Call hid_error(dev) to get the failure reason. 355 If no packet was available to be read within 356 the timeout period, this function returns 0. 357 */ 358 int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds); 359 360 /** @brief Read an Input report from a HID device. 361 362 Input reports are returned 363 to the host through the INTERRUPT IN endpoint. The first byte will 364 contain the Report number if the device uses numbered reports. 365 366 @ingroup API 367 @param dev A device handle returned from hid_open(). 368 @param data A buffer to put the read data into. 369 @param length The number of bytes to read. For devices with 370 multiple reports, make sure to read an extra byte for 371 the report number. 372 373 @returns 374 This function returns the actual number of bytes read and 375 -1 on error. 376 Call hid_error(dev) to get the failure reason. 377 If no packet was available to be read and 378 the handle is in non-blocking mode, this function returns 0. 379 */ 380 int HID_API_EXPORT HID_API_CALL hid_read(hid_device *dev, unsigned char *data, size_t length); 381 382 /** @brief Set the device handle to be non-blocking. 383 384 In non-blocking mode calls to hid_read() will return 385 immediately with a value of 0 if there is no data to be 386 read. In blocking mode, hid_read() will wait (block) until 387 there is data to read before returning. 388 389 Nonblocking can be turned on and off at any time. 390 391 @ingroup API 392 @param dev A device handle returned from hid_open(). 393 @param nonblock enable or not the nonblocking reads 394 - 1 to enable nonblocking 395 - 0 to disable nonblocking. 396 397 @returns 398 This function returns 0 on success and -1 on error. 399 Call hid_error(dev) to get the failure reason. 400 */ 401 int HID_API_EXPORT HID_API_CALL hid_set_nonblocking(hid_device *dev, int nonblock); 402 403 /** @brief Send a Feature report to the device. 404 405 Feature reports are sent over the Control endpoint as a 406 Set_Report transfer. The first byte of @p data[] must 407 contain the Report ID. For devices which only support a 408 single report, this must be set to 0x0. The remaining bytes 409 contain the report data. Since the Report ID is mandatory, 410 calls to hid_send_feature_report() will always contain one 411 more byte than the report contains. For example, if a hid 412 report is 16 bytes long, 17 bytes must be passed to 413 hid_send_feature_report(): the Report ID (or 0x0, for 414 devices which do not use numbered reports), followed by the 415 report data (16 bytes). In this example, the length passed 416 in would be 17. 417 418 @ingroup API 419 @param dev A device handle returned from hid_open(). 420 @param data The data to send, including the report number as 421 the first byte. 422 @param length The length in bytes of the data to send, including 423 the report number. 424 425 @returns 426 This function returns the actual number of bytes written and 427 -1 on error. 428 Call hid_error(dev) to get the failure reason. 429 */ 430 int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *dev, const unsigned char *data, size_t length); 431 432 /** @brief Get a feature report from a HID device. 433 434 Set the first byte of @p data[] to the Report ID of the 435 report to be read. Make sure to allow space for this 436 extra byte in @p data[]. Upon return, the first byte will 437 still contain the Report ID, and the report data will 438 start in data[1]. 439 440 @ingroup API 441 @param dev A device handle returned from hid_open(). 442 @param data A buffer to put the read data into, including 443 the Report ID. Set the first byte of @p data[] to the 444 Report ID of the report to be read, or set it to zero 445 if your device does not use numbered reports. 446 @param length The number of bytes to read, including an 447 extra byte for the report ID. The buffer can be longer 448 than the actual report. 449 450 @returns 451 This function returns the number of bytes read plus 452 one for the report ID (which is still in the first 453 byte), or -1 on error. 454 Call hid_error(dev) to get the failure reason. 455 */ 456 int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *dev, unsigned char *data, size_t length); 457 458 /** @brief Get a input report from a HID device. 459 460 Since version 0.10.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 10, 0) 461 462 Set the first byte of @p data[] to the Report ID of the 463 report to be read. Make sure to allow space for this 464 extra byte in @p data[]. Upon return, the first byte will 465 still contain the Report ID, and the report data will 466 start in data[1]. 467 468 @ingroup API 469 @param dev A device handle returned from hid_open(). 470 @param data A buffer to put the read data into, including 471 the Report ID. Set the first byte of @p data[] to the 472 Report ID of the report to be read, or set it to zero 473 if your device does not use numbered reports. 474 @param length The number of bytes to read, including an 475 extra byte for the report ID. The buffer can be longer 476 than the actual report. 477 478 @returns 479 This function returns the number of bytes read plus 480 one for the report ID (which is still in the first 481 byte), or -1 on error. 482 Call hid_error(dev) to get the failure reason. 483 */ 484 int HID_API_EXPORT HID_API_CALL hid_get_input_report(hid_device *dev, unsigned char *data, size_t length); 485 486 /** @brief Close a HID device. 487 488 @ingroup API 489 @param dev A device handle returned from hid_open(). 490 */ 491 void HID_API_EXPORT HID_API_CALL hid_close(hid_device *dev); 492 493 /** @brief Get The Manufacturer String from a HID device. 494 495 @ingroup API 496 @param dev A device handle returned from hid_open(). 497 @param string A wide string buffer to put the data into. 498 @param maxlen The length of the buffer in multiples of wchar_t. 499 500 @returns 501 This function returns 0 on success and -1 on error. 502 Call hid_error(dev) to get the failure reason. 503 */ 504 int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *dev, wchar_t *string, size_t maxlen); 505 506 /** @brief Get The Product String from a HID device. 507 508 @ingroup API 509 @param dev A device handle returned from hid_open(). 510 @param string A wide string buffer to put the data into. 511 @param maxlen The length of the buffer in multiples of wchar_t. 512 513 @returns 514 This function returns 0 on success and -1 on error. 515 Call hid_error(dev) to get the failure reason. 516 */ 517 int HID_API_EXPORT_CALL hid_get_product_string(hid_device *dev, wchar_t *string, size_t maxlen); 518 519 /** @brief Get The Serial Number String from a HID device. 520 521 @ingroup API 522 @param dev A device handle returned from hid_open(). 523 @param string A wide string buffer to put the data into. 524 @param maxlen The length of the buffer in multiples of wchar_t. 525 526 @returns 527 This function returns 0 on success and -1 on error. 528 Call hid_error(dev) to get the failure reason. 529 */ 530 int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *dev, wchar_t *string, size_t maxlen); 531 532 /** @brief Get The struct #hid_device_info from a HID device. 533 534 Since version 0.13.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 13, 0) 535 536 @ingroup API 537 @param dev A device handle returned from hid_open(). 538 539 @returns 540 This function returns a pointer to the struct #hid_device_info 541 for this hid_device, or NULL in the case of failure. 542 Call hid_error(dev) to get the failure reason. 543 This struct is valid until the device is closed with hid_close(). 544 545 @note The returned object is owned by the @p dev, and SHOULD NOT be freed by the user. 546 */ 547 struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_get_device_info(hid_device *dev); 548 549 /** @brief Get a string from a HID device, based on its string index. 550 551 @ingroup API 552 @param dev A device handle returned from hid_open(). 553 @param string_index The index of the string to get. 554 @param string A wide string buffer to put the data into. 555 @param maxlen The length of the buffer in multiples of wchar_t. 556 557 @returns 558 This function returns 0 on success and -1 on error. 559 Call hid_error(dev) to get the failure reason. 560 */ 561 int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen); 562 563 /** @brief Get a report descriptor from a HID device. 564 565 Since version 0.14.0, @ref HID_API_VERSION >= HID_API_MAKE_VERSION(0, 14, 0) 566 567 User has to provide a preallocated buffer where descriptor will be copied to. 568 The recommended size for preallocated buffer is @ref HID_API_MAX_REPORT_DESCRIPTOR_SIZE bytes. 569 570 @ingroup API 571 @param dev A device handle returned from hid_open(). 572 @param buf The buffer to copy descriptor into. 573 @param buf_size The size of the buffer in bytes. 574 575 @returns 576 This function returns non-negative number of bytes actually copied, or -1 on error. 577 */ 578 int HID_API_EXPORT_CALL hid_get_report_descriptor(hid_device *dev, unsigned char *buf, size_t buf_size); 579 580 /** @brief Get a string describing the last error which occurred. 581 582 This function is intended for logging/debugging purposes. 583 584 This function guarantees to never return NULL. 585 If there was no error in the last function call - 586 the returned string clearly indicates that. 587 588 Any HIDAPI function that can explicitly indicate an execution failure 589 (e.g. by an error code, or by returning NULL) - may set the error string, 590 to be returned by this function. 591 592 Strings returned from hid_error() must not be freed by the user, 593 i.e. owned by HIDAPI library. 594 Device-specific error string may remain allocated at most until hid_close() is called. 595 Global error string may remain allocated at most until hid_exit() is called. 596 597 @ingroup API 598 @param dev A device handle returned from hid_open(), 599 or NULL to get the last non-device-specific error 600 (e.g. for errors in hid_open() or hid_enumerate()). 601 602 @returns 603 A string describing the last error (if any). 604 */ 605 HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *dev); 606 607 /** @brief Get a runtime version of the library. 608 609 This function is thread-safe. 610 611 @ingroup API 612 613 @returns 614 Pointer to statically allocated struct, that contains version. 615 */ 616 HID_API_EXPORT const struct hid_api_version* HID_API_CALL hid_version(void); 617 618 619 /** @brief Get a runtime version string of the library. 620 621 This function is thread-safe. 622 623 @ingroup API 624 625 @returns 626 Pointer to statically allocated string, that contains version string. 627 */ 628 HID_API_EXPORT const char* HID_API_CALL hid_version_str(void); 629 630#ifdef __cplusplus 631} 632#endif 633 634#endif 635[FILE END](C) 2025 0x4248 (C) 2025 4248 Media and 4248 Systems, All part of 0x4248 See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.