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