dep/sdl/include/SDL_hidapi.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2023 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: */