SDL 2.0
SDL_hidapi.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/* WIKI CATEGORY: HIDAPI */
23
24/**
25 * # CategoryHIDAPI
26 *
27 * Header file for SDL HIDAPI functions.
28 *
29 * This is an adaptation of the original HIDAPI interface by Alan Ott, and
30 * includes source code licensed under the following license:
31 *
32 * ```
33 * HIDAPI - Multi-Platform library for
34 * communication with HID devices.
35 *
36 * Copyright 2009, Alan Ott, Signal 11 Software.
37 * All Rights Reserved.
38 *
39 * This software may be used by anyone for any reason so
40 * long as the copyright notice in the source files
41 * remains intact.
42 * ```
43 *
44 * (Note that this license is the same as item three of SDL's zlib license, so
45 * it adds no new requirements on the user.)
46 *
47 * If you would like a version of SDL without this code, you can build SDL
48 * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for
49 * example on iOS or tvOS to avoid a dependency on the CoreBluetooth
50 * framework.
51 */
52
53#ifndef SDL_hidapi_h_
54#define SDL_hidapi_h_
55
56#include "SDL_stdinc.h"
57
58#include "begin_code.h"
59/* Set up for C function definitions, even when using C++ */
60#ifdef __cplusplus
61extern "C" {
62#endif
63
64/**
65 * A handle representing an open HID device
66 */
67struct SDL_hid_device_;
68typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */
69
70/** hidapi info structure */
71
72/**
73 * Information about a connected HID device
74 */
75typedef struct SDL_hid_device_info
76{
77 /** Platform-specific device path */
78 char *path;
79 /** Device Vendor ID */
80 unsigned short vendor_id;
81 /** Device Product ID */
82 unsigned short product_id;
83 /** Serial Number */
84 wchar_t *serial_number;
85 /** Device Release Number in binary-coded decimal,
86 also known as Device Version Number */
87 unsigned short release_number;
88 /** Manufacturer String */
90 /** Product string */
92 /** Usage Page for this Device/Interface
93 (Windows/Mac only). */
94 unsigned short usage_page;
95 /** Usage for this Device/Interface
96 (Windows/Mac only).*/
97 unsigned short usage;
98 /** The USB interface which this logical device
99 represents.
100
101 * Valid on both Linux implementations in all cases.
102 * Valid on the Windows implementation only if the device
103 contains more than one interface. */
105
106 /** Additional information about the USB interface.
107 Valid on libusb and Android implementations. */
111
112 /** Pointer to the next device */
115
116
117/**
118 * Initialize the HIDAPI library.
119 *
120 * This function initializes the HIDAPI library. Calling it is not strictly
121 * necessary, as it will be called automatically by SDL_hid_enumerate() and
122 * any of the SDL_hid_open_*() functions if it is needed. This function should
123 * be called at the beginning of execution however, if there is a chance of
124 * HIDAPI handles being opened by different threads simultaneously.
125 *
126 * Each call to this function should have a matching call to SDL_hid_exit()
127 *
128 * \returns 0 on success and -1 on error.
129 *
130 * \since This function is available since SDL 2.0.18.
131 *
132 * \sa SDL_hid_exit
133 */
134extern DECLSPEC int SDLCALL SDL_hid_init(void);
135
136/**
137 * Finalize the HIDAPI library.
138 *
139 * This function frees all of the static data associated with HIDAPI. It
140 * should be called at the end of execution to avoid memory leaks.
141 *
142 * \returns 0 on success and -1 on error.
143 *
144 * \since This function is available since SDL 2.0.18.
145 *
146 * \sa SDL_hid_init
147 */
148extern DECLSPEC int SDLCALL SDL_hid_exit(void);
149
150/**
151 * Check to see if devices may have been added or removed.
152 *
153 * Enumerating the HID devices is an expensive operation, so you can call this
154 * to see if there have been any system device changes since the last call to
155 * this function. A change in the counter returned doesn't necessarily mean
156 * that anything has changed, but you can call SDL_hid_enumerate() to get an
157 * updated device list.
158 *
159 * Calling this function for the first time may cause a thread or other system
160 * resource to be allocated to track device change notifications.
161 *
162 * \returns a change counter that is incremented with each potential device
163 * change, or 0 if device change detection isn't available.
164 *
165 * \since This function is available since SDL 2.0.18.
166 *
167 * \sa SDL_hid_enumerate
168 */
169extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
170
171/**
172 * Enumerate the HID Devices.
173 *
174 * This function returns a linked list of all the HID devices attached to the
175 * system which match vendor_id and product_id. If `vendor_id` is set to 0
176 * then any vendor matches. If `product_id` is set to 0 then any product
177 * matches. If `vendor_id` and `product_id` are both set to 0, then all HID
178 * devices will be returned.
179 *
180 * \param vendor_id The Vendor ID (VID) of the types of device to open.
181 * \param product_id The Product ID (PID) of the types of device to open.
182 * \returns a pointer to a linked list of type SDL_hid_device_info, containing
183 * information about the HID devices attached to the system, or NULL
184 * in the case of failure. Free this linked list by calling
185 * SDL_hid_free_enumeration().
186 *
187 * \since This function is available since SDL 2.0.18.
188 *
189 * \sa SDL_hid_device_change_count
190 */
191extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id);
192
193/**
194 * Free an enumeration Linked List
195 *
196 * This function frees a linked list created by SDL_hid_enumerate().
197 *
198 * \param devs Pointer to a list of struct_device returned from
199 * SDL_hid_enumerate().
200 *
201 * \since This function is available since SDL 2.0.18.
202 */
203extern DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs);
204
205/**
206 * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally
207 * a serial number.
208 *
209 * If `serial_number` is NULL, the first device with the specified VID and PID
210 * is opened.
211 *
212 * \param vendor_id The Vendor ID (VID) of the device to open.
213 * \param product_id The Product ID (PID) of the device to open.
214 * \param serial_number The Serial Number of the device to open (Optionally
215 * NULL).
216 * \returns a pointer to a SDL_hid_device object on success or NULL on
217 * failure.
218 *
219 * \since This function is available since SDL 2.0.18.
220 */
221extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
222
223/**
224 * Open a HID device by its path name.
225 *
226 * The path name be determined by calling SDL_hid_enumerate(), or a
227 * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
228 *
229 * \param path The path name of the device to open.
230 * \returns a pointer to a SDL_hid_device object on success or NULL on
231 * failure.
232 *
233 * \since This function is available since SDL 2.0.18.
234 */
235extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive);
236
237/**
238 * Write an Output report to a HID device.
239 *
240 * The first byte of `data` must contain the Report ID. For devices which only
241 * support a single report, this must be set to 0x0. The remaining bytes
242 * contain the report data. Since the Report ID is mandatory, calls to
243 * SDL_hid_write() will always contain one more byte than the report contains.
244 * For example, if a hid report is 16 bytes long, 17 bytes must be passed to
245 * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report),
246 * followed by the report data (16 bytes). In this example, the length passed
247 * in would be 17.
248 *
249 * SDL_hid_write() will send the data on the first OUT endpoint, if one
250 * exists. If it does not, it will send the data through the Control Endpoint
251 * (Endpoint 0).
252 *
253 * \param dev A device handle returned from SDL_hid_open().
254 * \param data The data to send, including the report number as the first
255 * byte.
256 * \param length The length in bytes of the data to send.
257 * \returns the actual number of bytes written and -1 on error.
258 *
259 * \since This function is available since SDL 2.0.18.
260 */
261extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length);
262
263/**
264 * Read an Input report from a HID device with timeout.
265 *
266 * Input reports are returned to the host through the INTERRUPT IN endpoint.
267 * The first byte will contain the Report number if the device uses numbered
268 * reports.
269 *
270 * \param dev A device handle returned from SDL_hid_open().
271 * \param data A buffer to put the read data into.
272 * \param length The number of bytes to read. For devices with multiple
273 * reports, make sure to read an extra byte for the report
274 * number.
275 * \param milliseconds timeout in milliseconds or -1 for blocking wait.
276 * \returns the actual number of bytes read and -1 on error. If no packet was
277 * available to be read within the timeout period, this function
278 * returns 0.
279 *
280 * \since This function is available since SDL 2.0.18.
281 */
282extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds);
283
284/**
285 * Read an Input report from a HID device.
286 *
287 * Input reports are returned to the host through the INTERRUPT IN endpoint.
288 * The first byte will contain the Report number if the device uses numbered
289 * reports.
290 *
291 * \param dev A device handle returned from SDL_hid_open().
292 * \param data A buffer to put the read data into.
293 * \param length The number of bytes to read. For devices with multiple
294 * reports, make sure to read an extra byte for the report
295 * number.
296 * \returns the actual number of bytes read and -1 on error. If no packet was
297 * available to be read and the handle is in non-blocking mode, this
298 * function returns 0.
299 *
300 * \since This function is available since SDL 2.0.18.
301 */
302extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length);
303
304/**
305 * Set the device handle to be non-blocking.
306 *
307 * In non-blocking mode calls to SDL_hid_read() will return immediately with a
308 * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read()
309 * will wait (block) until there is data to read before returning.
310 *
311 * Nonblocking can be turned on and off at any time.
312 *
313 * \param dev A device handle returned from SDL_hid_open().
314 * \param nonblock enable or not the nonblocking reads - 1 to enable
315 * nonblocking - 0 to disable nonblocking.
316 * \returns 0 on success and -1 on error.
317 *
318 * \since This function is available since SDL 2.0.18.
319 */
320extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock);
321
322/**
323 * Send a Feature report to the device.
324 *
325 * Feature reports are sent over the Control endpoint as a Set_Report
326 * transfer. The first byte of `data` must contain the Report ID. For devices
327 * which only support a single report, this must be set to 0x0. The remaining
328 * bytes contain the report data. Since the Report ID is mandatory, calls to
329 * SDL_hid_send_feature_report() will always contain one more byte than the
330 * report contains. For example, if a hid report is 16 bytes long, 17 bytes
331 * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for
332 * devices which do not use numbered reports), followed by the report data (16
333 * bytes). In this example, the length passed in would be 17.
334 *
335 * \param dev A device handle returned from SDL_hid_open().
336 * \param data The data to send, including the report number as the first
337 * byte.
338 * \param length The length in bytes of the data to send, including the report
339 * number.
340 * \returns the actual number of bytes written and -1 on error.
341 *
342 * \since This function is available since SDL 2.0.18.
343 */
344extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length);
345
346/**
347 * Get a feature report from a HID device.
348 *
349 * Set the first byte of `data` to the Report ID of the report to be read.
350 * Make sure to allow space for this extra byte in `data`. Upon return, the
351 * first byte will still contain the Report ID, and the report data will start
352 * in data[1].
353 *
354 * \param dev A device handle returned from SDL_hid_open().
355 * \param data A buffer to put the read data into, including the Report ID.
356 * Set the first byte of `data` to the Report ID of the report to
357 * be read, or set it to zero if your device does not use numbered
358 * reports.
359 * \param length The number of bytes to read, including an extra byte for the
360 * report ID. The buffer can be longer than the actual report.
361 * \returns the number of bytes read plus one for the report ID (which is
362 * still in the first byte), or -1 on error.
363 *
364 * \since This function is available since SDL 2.0.18.
365 */
366extern DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length);
367
368/**
369 * Close a HID device.
370 *
371 * \param dev A device handle returned from SDL_hid_open().
372 *
373 * \since This function is available since SDL 2.0.18.
374 */
375extern DECLSPEC void SDLCALL SDL_hid_close(SDL_hid_device *dev);
376
377/**
378 * Get The Manufacturer String from a HID device.
379 *
380 * \param dev A device handle returned from SDL_hid_open().
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 * \returns 0 on success and -1 on error.
384 *
385 * \since This function is available since SDL 2.0.18.
386 */
387extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
388
389/**
390 * Get The Product String from a HID device.
391 *
392 * \param dev A device handle returned from SDL_hid_open().
393 * \param string A wide string buffer to put the data into.
394 * \param maxlen The length of the buffer in multiples of wchar_t.
395 * \returns 0 on success and -1 on error.
396 *
397 * \since This function is available since SDL 2.0.18.
398 */
399extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
400
401/**
402 * Get The Serial Number String from a HID device.
403 *
404 * \param dev A device handle returned from SDL_hid_open().
405 * \param string A wide string buffer to put the data into.
406 * \param maxlen The length of the buffer in multiples of wchar_t.
407 * \returns 0 on success and -1 on error.
408 *
409 * \since This function is available since SDL 2.0.18.
410 */
411extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
412
413/**
414 * Get a string from a HID device, based on its string index.
415 *
416 * \param dev A device handle returned from SDL_hid_open().
417 * \param string_index The index of the string to get.
418 * \param string A wide string buffer to put the data into.
419 * \param maxlen The length of the buffer in multiples of wchar_t.
420 * \returns 0 on success and -1 on error.
421 *
422 * \since This function is available since SDL 2.0.18.
423 */
424extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen);
425
426/**
427 * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers
428 *
429 * \param active SDL_TRUE to start the scan, SDL_FALSE to stop the scan.
430 *
431 * \since This function is available since SDL 2.0.18.
432 */
433extern DECLSPEC void SDLCALL SDL_hid_ble_scan(SDL_bool active);
434
435/* Ends C function definitions when using C++ */
436#ifdef __cplusplus
437}
438#endif
439#include "close_code.h"
440
441#endif /* SDL_hidapi_h_ */
442
443/* vi: set sts=4 ts=4 sw=4 expandtab: */
struct SDL_hid_device_ SDL_hid_device
Definition SDL_hidapi.h:68
SDL_hid_device * SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
int SDL_hid_init(void)
void SDL_hid_ble_scan(SDL_bool active)
int SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen)
int SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length)
Uint32 SDL_hid_device_change_count(void)
int SDL_hid_exit(void)
SDL_hid_device * SDL_hid_open_path(const char *path, int bExclusive)
int SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length)
int SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen)
int SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen)
void SDL_hid_free_enumeration(SDL_hid_device_info *devs)
int SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
SDL_hid_device_info * SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id)
int SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length)
int SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length)
void SDL_hid_close(SDL_hid_device *dev)
int SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock)
int SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds)
SDL_bool
Definition SDL_stdinc.h:187
uint32_t Uint32
Definition SDL_stdinc.h:231
unsigned short product_id
Definition SDL_hidapi.h:82
unsigned short vendor_id
Definition SDL_hidapi.h:80
wchar_t * product_string
Definition SDL_hidapi.h:91
struct SDL_hid_device_info * next
Definition SDL_hidapi.h:113
unsigned short usage
Definition SDL_hidapi.h:97
wchar_t * manufacturer_string
Definition SDL_hidapi.h:89
unsigned short usage_page
Definition SDL_hidapi.h:94
unsigned short release_number
Definition SDL_hidapi.h:87
wchar_t * serial_number
Definition SDL_hidapi.h:84