Atlas - SDL_hidapi.h
Home / ext / SDL / include / SDL3
Lines: 1 | Size: 22043 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1/*
2  Simple DirectMedia Layer
3  Copyright (C) 1997-2025 Sam Lantinga <[email protected]>
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 <SDL3/SDL_stdinc.h>
57#include <SDL3/SDL_error.h>
58#include <SDL3/SDL_properties.h>
59
60#include <SDL3/SDL_begin_code.h>
61/* Set up for C function definitions, even when using C++ */
62#ifdef __cplusplus
63extern "C" {
64#endif
65
66/**
67 * An opaque handle representing an open HID device.
68 *
69 * \since This struct is available since SDL 3.2.0.
70 */
71typedef struct SDL_hid_device SDL_hid_device;
72
73/**
74 * HID underlying bus types.
75 *
76 * \since This enum is available since SDL 3.2.0.
77 */
78typedef enum SDL_hid_bus_type {
79    /** Unknown bus type */
80    SDL_HID_API_BUS_UNKNOWN = 0x00,
81
82    /** USB bus
83       Specifications:
84       https://usb.org/hid */
85    SDL_HID_API_BUS_USB = 0x01,
86
87    /** Bluetooth or Bluetooth LE bus
88       Specifications:
89       https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/
90       https://www.bluetooth.com/specifications/specs/hid-service-1-0/
91       https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */
92    SDL_HID_API_BUS_BLUETOOTH = 0x02,
93
94    /** I2C bus
95       Specifications:
96       https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */
97    SDL_HID_API_BUS_I2C = 0x03,
98
99    /** SPI bus
100       Specifications:
101       https://www.microsoft.com/download/details.aspx?id=103325 */
102    SDL_HID_API_BUS_SPI = 0x04
103
104} SDL_hid_bus_type;
105
106/** hidapi info structure */
107
108/**
109 * Information about a connected HID device
110 *
111 * \since This struct is available since SDL 3.2.0.
112 */
113typedef struct SDL_hid_device_info
114{
115    /** Platform-specific device path */
116    char *path;
117    /** Device Vendor ID */
118    unsigned short vendor_id;
119    /** Device Product ID */
120    unsigned short product_id;
121    /** Serial Number */
122    wchar_t *serial_number;
123    /** Device Release Number in binary-coded decimal,
124        also known as Device Version Number */
125    unsigned short release_number;
126    /** Manufacturer String */
127    wchar_t *manufacturer_string;
128    /** Product string */
129    wchar_t *product_string;
130    /** Usage Page for this Device/Interface
131        (Windows/Mac/hidraw only) */
132    unsigned short usage_page;
133    /** Usage for this Device/Interface
134        (Windows/Mac/hidraw only) */
135    unsigned short usage;
136    /** The USB interface which this logical device
137        represents.
138
139        Valid only if the device is a USB HID device.
140        Set to -1 in all other cases.
141    */
142    int interface_number;
143
144    /** Additional information about the USB interface.
145        Valid on libusb and Android implementations. */
146    int interface_class;
147    int interface_subclass;
148    int interface_protocol;
149
150    /** Underlying bus type */
151    SDL_hid_bus_type bus_type;
152
153    /** Pointer to the next device */
154    struct SDL_hid_device_info *next;
155
156} SDL_hid_device_info;
157
158
159/**
160 * Initialize the HIDAPI library.
161 *
162 * This function initializes the HIDAPI library. Calling it is not strictly
163 * necessary, as it will be called automatically by SDL_hid_enumerate() and
164 * any of the SDL_hid_open_*() functions if it is needed. This function should
165 * be called at the beginning of execution however, if there is a chance of
166 * HIDAPI handles being opened by different threads simultaneously.
167 *
168 * Each call to this function should have a matching call to SDL_hid_exit()
169 *
170 * \returns 0 on success or a negative error code on failure; call
171 *          SDL_GetError() for more information.
172 *
173 * \since This function is available since SDL 3.2.0.
174 *
175 * \sa SDL_hid_exit
176 */
177extern SDL_DECLSPEC int SDLCALL SDL_hid_init(void);
178
179/**
180 * Finalize the HIDAPI library.
181 *
182 * This function frees all of the static data associated with HIDAPI. It
183 * should be called at the end of execution to avoid memory leaks.
184 *
185 * \returns 0 on success or a negative error code on failure; call
186 *          SDL_GetError() for more information.
187 *
188 * \since This function is available since SDL 3.2.0.
189 *
190 * \sa SDL_hid_init
191 */
192extern SDL_DECLSPEC int SDLCALL SDL_hid_exit(void);
193
194/**
195 * Check to see if devices may have been added or removed.
196 *
197 * Enumerating the HID devices is an expensive operation, so you can call this
198 * to see if there have been any system device changes since the last call to
199 * this function. A change in the counter returned doesn't necessarily mean
200 * that anything has changed, but you can call SDL_hid_enumerate() to get an
201 * updated device list.
202 *
203 * Calling this function for the first time may cause a thread or other system
204 * resource to be allocated to track device change notifications.
205 *
206 * \returns a change counter that is incremented with each potential device
207 *          change, or 0 if device change detection isn't available.
208 *
209 * \since This function is available since SDL 3.2.0.
210 *
211 * \sa SDL_hid_enumerate
212 */
213extern SDL_DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void);
214
215/**
216 * Enumerate the HID Devices.
217 *
218 * This function returns a linked list of all the HID devices attached to the
219 * system which match vendor_id and product_id. If `vendor_id` is set to 0
220 * then any vendor matches. If `product_id` is set to 0 then any product
221 * matches. If `vendor_id` and `product_id` are both set to 0, then all HID
222 * devices will be returned.
223 *
224 * By default SDL will only enumerate controllers, to reduce risk of hanging
225 * or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS
226 * can be set to "0" to enumerate all HID devices.
227 *
228 * \param vendor_id the Vendor ID (VID) of the types of device to open, or 0
229 *                  to match any vendor.
230 * \param product_id the Product ID (PID) of the types of device to open, or 0
231 *                   to match any product.
232 * \returns a pointer to a linked list of type SDL_hid_device_info, containing
233 *          information about the HID devices attached to the system, or NULL
234 *          in the case of failure. Free this linked list by calling
235 *          SDL_hid_free_enumeration().
236 *
237 * \since This function is available since SDL 3.2.0.
238 *
239 * \sa SDL_hid_device_change_count
240 */
241extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_enumerate(unsigned short vendor_id, unsigned short product_id);
242
243/**
244 * Free an enumeration linked list.
245 *
246 * This function frees a linked list created by SDL_hid_enumerate().
247 *
248 * \param devs pointer to a list of struct_device returned from
249 *             SDL_hid_enumerate().
250 *
251 * \since This function is available since SDL 3.2.0.
252 */
253extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *devs);
254
255/**
256 * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally
257 * a serial number.
258 *
259 * If `serial_number` is NULL, the first device with the specified VID and PID
260 * is opened.
261 *
262 * \param vendor_id the Vendor ID (VID) of the device to open.
263 * \param product_id the Product ID (PID) of the device to open.
264 * \param serial_number the Serial Number of the device to open (Optionally
265 *                      NULL).
266 * \returns a pointer to a SDL_hid_device object on success or NULL on
267 *          failure; call SDL_GetError() for more information.
268 *
269 * \since This function is available since SDL 3.2.0.
270 */
271extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number);
272
273/**
274 * Open a HID device by its path name.
275 *
276 * The path name be determined by calling SDL_hid_enumerate(), or a
277 * platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
278 *
279 * \param path the path name of the device to open.
280 * \returns a pointer to a SDL_hid_device object on success or NULL on
281 *          failure; call SDL_GetError() for more information.
282 *
283 * \since This function is available since SDL 3.2.0.
284 */
285extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path);
286
287/**
288 * Get the properties associated with an SDL_hid_device.
289 *
290 * The following read-only properties are provided by SDL:
291 *
292 * - `SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER`: the libusb_device_handle
293 *   associated with the device, if it was opened using libusb.
294 *
295 * \param dev a device handle returned from SDL_hid_open().
296 * \returns a valid property ID on success or 0 on failure; call
297 *          SDL_GetError() for more information.
298 *
299 * \since This function is available since SDL 3.4.0.
300 */
301extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_hid_get_properties(SDL_hid_device *dev);
302
303#define SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER   "SDL.hidapi.libusb.device.handle"
304
305/**
306 * Write an Output report to a HID device.
307 *
308 * The first byte of `data` must contain the Report ID. For devices which only
309 * support a single report, this must be set to 0x0. The remaining bytes
310 * contain the report data. Since the Report ID is mandatory, calls to
311 * SDL_hid_write() will always contain one more byte than the report contains.
312 * For example, if a hid report is 16 bytes long, 17 bytes must be passed to
313 * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report),
314 * followed by the report data (16 bytes). In this example, the length passed
315 * in would be 17.
316 *
317 * SDL_hid_write() will send the data on the first OUT endpoint, if one
318 * exists. If it does not, it will send the data through the Control Endpoint
319 * (Endpoint 0).
320 *
321 * \param dev a device handle returned from SDL_hid_open().
322 * \param data the data to send, including the report number as the first
323 *             byte.
324 * \param length the length in bytes of the data to send.
325 * \returns the actual number of bytes written and -1 on on failure; call
326 *          SDL_GetError() for more information.
327 *
328 * \since This function is available since SDL 3.2.0.
329 */
330extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned char *data, size_t length);
331
332/**
333 * Read an Input report from a HID device with timeout.
334 *
335 * Input reports are returned to the host through the INTERRUPT IN endpoint.
336 * The first byte will contain the Report number if the device uses numbered
337 * reports.
338 *
339 * \param dev a device handle returned from SDL_hid_open().
340 * \param data a buffer to put the read data into.
341 * \param length the number of bytes to read. For devices with multiple
342 *               reports, make sure to read an extra byte for the report
343 *               number.
344 * \param milliseconds timeout in milliseconds or -1 for blocking wait.
345 * \returns the actual number of bytes read and -1 on on failure; call
346 *          SDL_GetError() for more information. If no packet was available to
347 *          be read within the timeout period, this function returns 0.
348 *
349 * \since This function is available since SDL 3.2.0.
350 */
351extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds);
352
353/**
354 * Read an Input report from a HID device.
355 *
356 * Input reports are returned to the host through the INTERRUPT IN endpoint.
357 * The first byte will contain the Report number if the device uses numbered
358 * reports.
359 *
360 * \param dev a device handle returned from SDL_hid_open().
361 * \param data a buffer to put the read data into.
362 * \param length the number of bytes to read. For devices with multiple
363 *               reports, make sure to read an extra byte for the report
364 *               number.
365 * \returns the actual number of bytes read and -1 on failure; call
366 *          SDL_GetError() for more information. If no packet was available to
367 *          be read and the handle is in non-blocking mode, this function
368 *          returns 0.
369 *
370 * \since This function is available since SDL 3.2.0.
371 */
372extern SDL_DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *data, size_t length);
373
374/**
375 * Set the device handle to be non-blocking.
376 *
377 * In non-blocking mode calls to SDL_hid_read() will return immediately with a
378 * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read()
379 * will wait (block) until there is data to read before returning.
380 *
381 * Nonblocking can be turned on and off at any time.
382 *
383 * \param dev a device handle returned from SDL_hid_open().
384 * \param nonblock enable or not the nonblocking reads - 1 to enable
385 *                 nonblocking - 0 to disable nonblocking.
386 * \returns 0 on success or a negative error code on failure; call
387 *          SDL_GetError() for more information.
388 *
389 * \since This function is available since SDL 3.2.0.
390 */
391extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int nonblock);
392
393/**
394 * Send a Feature report to the device.
395 *
396 * Feature reports are sent over the Control endpoint as a Set_Report
397 * transfer. The first byte of `data` must contain the Report ID. For devices
398 * which only support a single report, this must be set to 0x0. The remaining
399 * bytes contain the report data. Since the Report ID is mandatory, calls to
400 * SDL_hid_send_feature_report() will always contain one more byte than the
401 * report contains. For example, if a hid report is 16 bytes long, 17 bytes
402 * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for
403 * devices which do not use numbered reports), followed by the report data (16
404 * bytes). In this example, the length passed in would be 17.
405 *
406 * \param dev a device handle returned from SDL_hid_open().
407 * \param data the data to send, including the report number as the first
408 *             byte.
409 * \param length the length in bytes of the data to send, including the report
410 *               number.
411 * \returns the actual number of bytes written and -1 on failure; call
412 *          SDL_GetError() for more information.
413 *
414 * \since This function is available since SDL 3.2.0.
415 */
416extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, const unsigned char *data, size_t length);
417
418/**
419 * Get a feature report from a HID device.
420 *
421 * Set the first byte of `data` to the Report ID of the report to be read.
422 * Make sure to allow space for this extra byte in `data`. Upon return, the
423 * first byte will still contain the Report ID, and the report data will start
424 * in data[1].
425 *
426 * \param dev a device handle returned from SDL_hid_open().
427 * \param data a buffer to put the read data into, including the Report ID.
428 *             Set the first byte of `data` to the Report ID of the report to
429 *             be read, or set it to zero if your device does not use numbered
430 *             reports.
431 * \param length the number of bytes to read, including an extra byte for the
432 *               report ID. The buffer can be longer than the actual report.
433 * \returns the number of bytes read plus one for the report ID (which is
434 *          still in the first byte), or -1 on on failure; call SDL_GetError()
435 *          for more information.
436 *
437 * \since This function is available since SDL 3.2.0.
438 */
439extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length);
440
441/**
442 * Get an input report from a HID device.
443 *
444 * Set the first byte of `data` to the Report ID of the report to be read.
445 * Make sure to allow space for this extra byte in `data`. Upon return, the
446 * first byte will still contain the Report ID, and the report data will start
447 * in data[1].
448 *
449 * \param dev a device handle returned from SDL_hid_open().
450 * \param data a buffer to put the read data into, including the Report ID.
451 *             Set the first byte of `data` to the Report ID of the report to
452 *             be read, or set it to zero if your device does not use numbered
453 *             reports.
454 * \param length the number of bytes to read, including an extra byte for the
455 *               report ID. The buffer can be longer than the actual report.
456 * \returns the number of bytes read plus one for the report ID (which is
457 *          still in the first byte), or -1 on on failure; call SDL_GetError()
458 *          for more information.
459 *
460 * \since This function is available since SDL 3.2.0.
461 */
462extern SDL_DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length);
463
464/**
465 * Close a HID device.
466 *
467 * \param dev a device handle returned from SDL_hid_open().
468 * \returns 0 on success or a negative error code on failure; call
469 *          SDL_GetError() for more information.
470 *
471 * \since This function is available since SDL 3.2.0.
472 */
473extern SDL_DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev);
474
475/**
476 * Get The Manufacturer String from a HID device.
477 *
478 * \param dev a device handle returned from SDL_hid_open().
479 * \param string a wide string buffer to put the data into.
480 * \param maxlen the length of the buffer in multiples of wchar_t.
481 * \returns 0 on success or a negative error code on failure; call
482 *          SDL_GetError() for more information.
483 *
484 * \since This function is available since SDL 3.2.0.
485 */
486extern SDL_DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
487
488/**
489 * Get The Product String from a HID device.
490 *
491 * \param dev a device handle returned from SDL_hid_open().
492 * \param string a wide string buffer to put the data into.
493 * \param maxlen the length of the buffer in multiples of wchar_t.
494 * \returns 0 on success or a negative error code on failure; call
495 *          SDL_GetError() for more information.
496 *
497 * \since This function is available since SDL 3.2.0.
498 */
499extern SDL_DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
500
501/**
502 * Get The Serial Number String from a HID device.
503 *
504 * \param dev a device handle returned from SDL_hid_open().
505 * \param string a wide string buffer to put the data into.
506 * \param maxlen the length of the buffer in multiples of wchar_t.
507 * \returns 0 on success or a negative error code on failure; call
508 *          SDL_GetError() for more information.
509 *
510 * \since This function is available since SDL 3.2.0.
511 */
512extern SDL_DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev, wchar_t *string, size_t maxlen);
513
514/**
515 * Get a string from a HID device, based on its string index.
516 *
517 * \param dev a device handle returned from SDL_hid_open().
518 * \param string_index the index of the string to get.
519 * \param string a wide string buffer to put the data into.
520 * \param maxlen the length of the buffer in multiples of wchar_t.
521 * \returns 0 on success or a negative error code on failure; call
522 *          SDL_GetError() for more information.
523 *
524 * \since This function is available since SDL 3.2.0.
525 */
526extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen);
527
528/**
529 * Get the device info from a HID device.
530 *
531 * \param dev a device handle returned from SDL_hid_open().
532 * \returns a pointer to the SDL_hid_device_info for this hid_device or NULL
533 *          on failure; call SDL_GetError() for more information. This struct
534 *          is valid until the device is closed with SDL_hid_close().
535 *
536 * \since This function is available since SDL 3.2.0.
537 */
538extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev);
539
540/**
541 * Get a report descriptor from a HID device.
542 *
543 * User has to provide a preallocated buffer where descriptor will be copied
544 * to. The recommended size for a preallocated buffer is 4096 bytes.
545 *
546 * \param dev a device handle returned from SDL_hid_open().
547 * \param buf the buffer to copy descriptor into.
548 * \param buf_size the size of the buffer in bytes.
549 * \returns the number of bytes actually copied or -1 on failure; call
550 *          SDL_GetError() for more information.
551 *
552 * \since This function is available since SDL 3.2.0.
553 */
554extern SDL_DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size);
555
556/**
557 * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
558 *
559 * \param active true to start the scan, false to stop the scan.
560 *
561 * \since This function is available since SDL 3.2.0.
562 */
563extern SDL_DECLSPEC void SDLCALL SDL_hid_ble_scan(bool active);
564
565/* Ends C function definitions when using C++ */
566#ifdef __cplusplus
567}
568#endif
569#include <SDL3/SDL_close_code.h>
570
571#endif /* SDL_hidapi_h_ */
572
[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.