hidapi
hidapi.h
Go to the documentation of this file.
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 
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
40 #endif
41 /* To be removed in v1.0 */
42 #define HID_API_CALL
44 #define HID_API_EXPORT_CALL HID_API_EXPORT HID_API_CALL
50 #define HID_API_VERSION_MAJOR 0
51 
55 #define HID_API_VERSION_MINOR 15
56 
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 
79 #define HID_API_MAKE_VERSION(mj, mn, p) (((mj) << 24) | ((mn) << 8) | (p))
80 
89 #define HID_API_VERSION HID_API_MAKE_VERSION(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH)
90 
95 #define HID_API_VERSION_STR HID_API_TO_VERSION_STR(HID_API_VERSION_MAJOR, HID_API_VERSION_MINOR, HID_API_VERSION_PATCH)
96 
103 #define HID_API_MAX_REPORT_DESCRIPTOR_SIZE 4096
104 
105 #ifdef __cplusplus
106 extern "C" {
107 #endif
108 
110  int major;
111  int minor;
112  int patch;
113  };
114 
115  struct hid_device_;
116  typedef struct hid_device_ hid_device;
122  typedef enum {
125 
130 
137 
142 
147  } hid_bus_type;
148 
152  char *path;
154  unsigned short vendor_id;
156  unsigned short product_id;
158  wchar_t *serial_number;
161  unsigned short release_number;
165  wchar_t *product_string;
168  unsigned short usage_page;
171  unsigned short usage;
179 
182 
187  };
188 
189 
206 
219 
245  struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id);
246 
256 
277  HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
278 
297 
325  int HID_API_EXPORT HID_API_CALL hid_write(hid_device *dev, const unsigned char *data, size_t length);
326 
350  int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds);
351 
374  int HID_API_EXPORT HID_API_CALL hid_read(hid_device *dev, unsigned char *data, size_t length);
375 
397 
418 
446  int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *dev, const unsigned char *data, size_t length);
447 
472  int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *dev, unsigned char *data, size_t length);
473 
506  int HID_API_EXPORT HID_API_CALL hid_send_output_report(hid_device* dev, const unsigned char* data, size_t length);
507 
534  int HID_API_EXPORT HID_API_CALL hid_get_input_report(hid_device *dev, unsigned char *data, size_t length);
535 
542 
554  int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *dev, wchar_t *string, size_t maxlen);
555 
567  int HID_API_EXPORT_CALL hid_get_product_string(hid_device *dev, wchar_t *string, size_t maxlen);
568 
580  int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *dev, wchar_t *string, size_t maxlen);
581 
598 
611  int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen);
612 
628  int HID_API_EXPORT_CALL hid_get_report_descriptor(hid_device *dev, unsigned char *buf, size_t buf_size);
629 
655  HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *dev);
656 
667 
668 
678  HID_API_EXPORT const char* HID_API_CALL hid_version_str(void);
679 
680 #ifdef __cplusplus
681 }
682 #endif
683 
684 #endif
Definition: hidapi.h:141
HID_API_EXPORT hid_device *HID_API_CALL hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number...
int interface_number
Definition: hidapi.h:178
Definition: hidapi.h:146
int patch
Definition: hidapi.h:112
int HID_API_EXPORT_CALL hid_get_product_string(hid_device *dev, wchar_t *string, size_t maxlen)
Get The Product String from a HID device.
Definition: hidapi.h:150
Definition: hidapi.h:129
int HID_API_EXPORT HID_API_CALL hid_set_nonblocking(hid_device *dev, int nonblock)
Set the device handle to be non-blocking.
hid_bus_type
HID underlying bus types.
Definition: hidapi.h:122
#define HID_API_EXPORT
Definition: hidapi.h:39
HID_API_EXPORT const struct hid_api_version *HID_API_CALL hid_version(void)
Get a runtime version of the library.
int HID_API_EXPORT HID_API_CALL hid_write(hid_device *dev, const unsigned char *data, size_t length)
Write an Output report to a HID device.
wchar_t * manufacturer_string
Definition: hidapi.h:163
char * path
Definition: hidapi.h:152
Definition: hidapi.h:136
int HID_API_EXPORT HID_API_CALL hid_get_input_report(hid_device *dev, unsigned char *data, size_t length)
Get a input report from a HID device.
int HID_API_EXPORT HID_API_CALL hid_exit(void)
Finalize the HIDAPI library.
Definition: hidapi.h:124
int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *dev, const unsigned char *data, size_t length)
Send a Feature report to the device.
struct hid_device_info * next
Definition: hidapi.h:181
Definition: hidapi.h:109
unsigned short product_id
Definition: hidapi.h:156
HID_API_EXPORT hid_device *HID_API_CALL hid_open_path(const char *path)
Open a HID device by its path name.
wchar_t * serial_number
Definition: hidapi.h:158
int major
Definition: hidapi.h:110
HID_API_EXPORT const wchar_t *HID_API_CALL hid_read_error(hid_device *dev)
Get a string describing the last error which occurred during hid_read/hid_read_timeout.
unsigned short vendor_id
Definition: hidapi.h:154
struct hid_device_info HID_API_EXPORT *HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id)
Enumerate the HID Devices.
int HID_API_EXPORT_CALL hid_get_manufacturer_string(hid_device *dev, wchar_t *string, size_t maxlen)
Get The Manufacturer String from a HID device.
wchar_t * product_string
Definition: hidapi.h:165
int HID_API_EXPORT HID_API_CALL hid_init(void)
Initialize the HIDAPI library.
int HID_API_EXPORT HID_API_CALL hid_read_timeout(hid_device *dev, unsigned char *data, size_t length, int milliseconds)
Read an Input report from a HID device with timeout.
unsigned short usage
Definition: hidapi.h:171
int HID_API_EXPORT HID_API_CALL hid_read(hid_device *dev, unsigned char *data, size_t length)
Read an Input report from a HID device.
HID_API_EXPORT const char *HID_API_CALL hid_version_str(void)
Get a runtime version string of the library.
struct hid_device_ hid_device
Definition: hidapi.h:116
#define HID_API_EXPORT_CALL
Definition: hidapi.h:44
int HID_API_EXPORT_CALL hid_get_report_descriptor(hid_device *dev, unsigned char *buf, size_t buf_size)
Get a report descriptor from a HID device.
int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *dev, unsigned char *data, size_t length)
Get a feature report from a HID device.
unsigned short usage_page
Definition: hidapi.h:168
hid_bus_type bus_type
Definition: hidapi.h:186
int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
Get a string from a HID device, based on its string index.
int HID_API_EXPORT HID_API_CALL hid_send_output_report(hid_device *dev, const unsigned char *data, size_t length)
Send a Output report to the device.
struct hid_device_info HID_API_EXPORT *HID_API_CALL hid_get_device_info(hid_device *dev)
Get The struct hid_device_info from a HID device.
void HID_API_EXPORT HID_API_CALL hid_free_enumeration(struct hid_device_info *devs)
Free an enumeration Linked List.
#define HID_API_CALL
Definition: hidapi.h:42
void HID_API_EXPORT HID_API_CALL hid_close(hid_device *dev)
Close a HID device.
int HID_API_EXPORT_CALL hid_get_serial_number_string(hid_device *dev, wchar_t *string, size_t maxlen)
Get The Serial Number String from a HID device.
unsigned short release_number
Definition: hidapi.h:161
int minor
Definition: hidapi.h:111
HID_API_EXPORT const wchar_t *HID_API_CALL hid_error(hid_device *dev)
Get a string describing the last error which occurred.