SDL 3.0
SDL_hidapi.h File Reference
+ Include dependency graph for SDL_hidapi.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_hid_device_info
 

Typedefs

typedef struct SDL_hid_device SDL_hid_device
 

Enumerations

enum  SDL_hid_bus_type {
  SDL_HID_API_BUS_UNKNOWN = 0x00 ,
  SDL_HID_API_BUS_USB = 0x01 ,
  SDL_HID_API_BUS_BLUETOOTH = 0x02 ,
  SDL_HID_API_BUS_I2C = 0x03 ,
  SDL_HID_API_BUS_SPI = 0x04
}
 

Functions

int SDL_hid_init (void)
 
int SDL_hid_exit (void)
 
Uint32 SDL_hid_device_change_count (void)
 
SDL_hid_device_infoSDL_hid_enumerate (unsigned short vendor_id, unsigned short product_id)
 
void SDL_hid_free_enumeration (SDL_hid_device_info *devs)
 
SDL_hid_deviceSDL_hid_open (unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
 
SDL_hid_deviceSDL_hid_open_path (const char *path)
 
int SDL_hid_write (SDL_hid_device *dev, const unsigned char *data, size_t length)
 
int SDL_hid_read_timeout (SDL_hid_device *dev, unsigned char *data, size_t length, int milliseconds)
 
int SDL_hid_read (SDL_hid_device *dev, unsigned char *data, size_t length)
 
int SDL_hid_set_nonblocking (SDL_hid_device *dev, int nonblock)
 
int SDL_hid_send_feature_report (SDL_hid_device *dev, const unsigned char *data, size_t length)
 
int SDL_hid_get_feature_report (SDL_hid_device *dev, unsigned char *data, size_t length)
 
int SDL_hid_get_input_report (SDL_hid_device *dev, unsigned char *data, size_t length)
 
int SDL_hid_close (SDL_hid_device *dev)
 
int SDL_hid_get_manufacturer_string (SDL_hid_device *dev, wchar_t *string, size_t maxlen)
 
int SDL_hid_get_product_string (SDL_hid_device *dev, wchar_t *string, size_t maxlen)
 
int SDL_hid_get_serial_number_string (SDL_hid_device *dev, wchar_t *string, size_t maxlen)
 
int SDL_hid_get_indexed_string (SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen)
 
SDL_hid_device_infoSDL_hid_get_device_info (SDL_hid_device *dev)
 
int SDL_hid_get_report_descriptor (SDL_hid_device *dev, unsigned char *buf, size_t buf_size)
 
void SDL_hid_ble_scan (bool active)
 

Typedef Documentation

◆ SDL_hid_device

CategoryHIDAPI

Header file for SDL HIDAPI functions.

This is an adaptation of the original HIDAPI interface by Alan Ott, and includes source code licensed under the following license:

HIDAPI - Multi-Platform library for
communication with HID devices.
Copyright 2009, Alan Ott, Signal 11 Software.
All Rights Reserved.
This software may be used by anyone for any reason so
long as the copyright notice in the source files
remains intact.

(Note that this license is the same as item three of SDL's zlib license, so it adds no new requirements on the user.)

If you would like a version of SDL without this code, you can build SDL with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example on iOS or tvOS to avoid a dependency on the CoreBluetooth framework. An opaque handle representing an open HID device.

Since
This struct is available since SDL 3.1.3.

Definition at line 70 of file SDL_hidapi.h.

Enumeration Type Documentation

◆ SDL_hid_bus_type

HID underlying bus types.

Since
This enum is available since SDL 3.1.3.
Enumerator
SDL_HID_API_BUS_UNKNOWN 

Unknown bus type

SDL_HID_API_BUS_USB 

USB bus Specifications: https://usb.org/hid

SDL_HID_API_BUS_BLUETOOTH 

Bluetooth or Bluetooth LE bus Specifications: https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/ https://www.bluetooth.com/specifications/specs/hid-service-1-0/ https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/

SDL_HID_API_BUS_I2C 

I2C bus Specifications: https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85)

SDL_HID_API_BUS_SPI 

SPI bus Specifications: https://www.microsoft.com/download/details.aspx?id=103325

Definition at line 77 of file SDL_hidapi.h.

77 {
78 /** Unknown bus type */
80
81 /** USB bus
82 Specifications:
83 https://usb.org/hid */
85
86 /** Bluetooth or Bluetooth LE bus
87 Specifications:
88 https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/
89 https://www.bluetooth.com/specifications/specs/hid-service-1-0/
90 https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */
92
93 /** I2C bus
94 Specifications:
95 https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */
97
98 /** SPI bus
99 Specifications:
100 https://www.microsoft.com/download/details.aspx?id=103325 */
102
SDL_hid_bus_type
Definition SDL_hidapi.h:77
@ SDL_HID_API_BUS_SPI
Definition SDL_hidapi.h:101
@ SDL_HID_API_BUS_I2C
Definition SDL_hidapi.h:96
@ SDL_HID_API_BUS_UNKNOWN
Definition SDL_hidapi.h:79
@ SDL_HID_API_BUS_BLUETOOTH
Definition SDL_hidapi.h:91
@ SDL_HID_API_BUS_USB
Definition SDL_hidapi.h:84

Function Documentation

◆ SDL_hid_ble_scan()

void SDL_hid_ble_scan ( bool  active)
extern

Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.

Parameters
activetrue to start the scan, false to stop the scan.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_close()

int SDL_hid_close ( SDL_hid_device dev)
extern

Close a HID device.

Parameters
deva device handle returned from SDL_hid_open().
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_device_change_count()

Uint32 SDL_hid_device_change_count ( void  )
extern

Check to see if devices may have been added or removed.

Enumerating the HID devices is an expensive operation, so you can call this to see if there have been any system device changes since the last call to this function. A change in the counter returned doesn't necessarily mean that anything has changed, but you can call SDL_hid_enumerate() to get an updated device list.

Calling this function for the first time may cause a thread or other system resource to be allocated to track device change notifications.

Returns
a change counter that is incremented with each potential device change, or 0 if device change detection isn't available.
Since
This function is available since SDL 3.1.3.
See also
SDL_hid_enumerate

◆ SDL_hid_enumerate()

SDL_hid_device_info * SDL_hid_enumerate ( unsigned short  vendor_id,
unsigned short  product_id 
)
extern

Enumerate the HID Devices.

This function returns a linked list of all the HID devices attached to the system which match vendor_id and product_id. If vendor_id is set to 0 then any vendor matches. If product_id is set to 0 then any product matches. If vendor_id and product_id are both set to 0, then all HID devices will be returned.

By default SDL will only enumerate controllers, to reduce risk of hanging or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS can be set to "0" to enumerate all HID devices.

Parameters
vendor_idthe Vendor ID (VID) of the types of device to open, or 0 to match any vendor.
product_idthe Product ID (PID) of the types of device to open, or 0 to match any product.
Returns
a pointer to a linked list of type SDL_hid_device_info, containing information about the HID devices attached to the system, or NULL in the case of failure. Free this linked list by calling SDL_hid_free_enumeration().
Since
This function is available since SDL 3.1.3.
See also
SDL_hid_device_change_count

◆ SDL_hid_exit()

int SDL_hid_exit ( void  )
extern

Finalize the HIDAPI library.

This function frees all of the static data associated with HIDAPI. It should be called at the end of execution to avoid memory leaks.

Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.
See also
SDL_hid_init

◆ SDL_hid_free_enumeration()

void SDL_hid_free_enumeration ( SDL_hid_device_info devs)
extern

Free an enumeration linked list.

This function frees a linked list created by SDL_hid_enumerate().

Parameters
devspointer to a list of struct_device returned from SDL_hid_enumerate().
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_device_info()

SDL_hid_device_info * SDL_hid_get_device_info ( SDL_hid_device dev)
extern

Get the device info from a HID device.

Parameters
deva device handle returned from SDL_hid_open().
Returns
a pointer to the SDL_hid_device_info for this hid_device or NULL on failure; call SDL_GetError() for more information. This struct is valid until the device is closed with SDL_hid_close().
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_feature_report()

int SDL_hid_get_feature_report ( SDL_hid_device dev,
unsigned char *  data,
size_t  length 
)
extern

Get a feature report from a HID device.

Set the first byte of data to the Report ID of the report to be read. Make sure to allow space for this extra byte in data. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1].

Parameters
deva device handle returned from SDL_hid_open().
dataa buffer to put the read data into, including the Report ID. Set the first byte of data to the Report ID of the report to be read, or set it to zero if your device does not use numbered reports.
lengththe number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report.
Returns
the number of bytes read plus one for the report ID (which is still in the first byte), or -1 on on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_indexed_string()

int SDL_hid_get_indexed_string ( SDL_hid_device dev,
int  string_index,
wchar_t *  string,
size_t  maxlen 
)
extern

Get a string from a HID device, based on its string index.

Parameters
deva device handle returned from SDL_hid_open().
string_indexthe index of the string to get.
stringa wide string buffer to put the data into.
maxlenthe length of the buffer in multiples of wchar_t.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_input_report()

int SDL_hid_get_input_report ( SDL_hid_device dev,
unsigned char *  data,
size_t  length 
)
extern

Get an input report from a HID device.

Set the first byte of data to the Report ID of the report to be read. Make sure to allow space for this extra byte in data. Upon return, the first byte will still contain the Report ID, and the report data will start in data[1].

Parameters
deva device handle returned from SDL_hid_open().
dataa buffer to put the read data into, including the Report ID. Set the first byte of data to the Report ID of the report to be read, or set it to zero if your device does not use numbered reports.
lengththe number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report.
Returns
the number of bytes read plus one for the report ID (which is still in the first byte), or -1 on on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_manufacturer_string()

int SDL_hid_get_manufacturer_string ( SDL_hid_device dev,
wchar_t *  string,
size_t  maxlen 
)
extern

Get The Manufacturer String from a HID device.

Parameters
deva device handle returned from SDL_hid_open().
stringa wide string buffer to put the data into.
maxlenthe length of the buffer in multiples of wchar_t.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_product_string()

int SDL_hid_get_product_string ( SDL_hid_device dev,
wchar_t *  string,
size_t  maxlen 
)
extern

Get The Product String from a HID device.

Parameters
deva device handle returned from SDL_hid_open().
stringa wide string buffer to put the data into.
maxlenthe length of the buffer in multiples of wchar_t.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_report_descriptor()

int SDL_hid_get_report_descriptor ( SDL_hid_device dev,
unsigned char *  buf,
size_t  buf_size 
)
extern

Get a report descriptor from a HID device.

User has to provide a preallocated buffer where descriptor will be copied to. The recommended size for a preallocated buffer is 4096 bytes.

Parameters
deva device handle returned from SDL_hid_open().
bufthe buffer to copy descriptor into.
buf_sizethe size of the buffer in bytes.
Returns
the number of bytes actually copied or -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_get_serial_number_string()

int SDL_hid_get_serial_number_string ( SDL_hid_device dev,
wchar_t *  string,
size_t  maxlen 
)
extern

Get The Serial Number String from a HID device.

Parameters
deva device handle returned from SDL_hid_open().
stringa wide string buffer to put the data into.
maxlenthe length of the buffer in multiples of wchar_t.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_init()

int SDL_hid_init ( void  )
extern

Initialize the HIDAPI library.

This function initializes the HIDAPI library. Calling it is not strictly necessary, as it will be called automatically by SDL_hid_enumerate() and any of the SDL_hid_open_*() functions if it is needed. This function should be called at the beginning of execution however, if there is a chance of HIDAPI handles being opened by different threads simultaneously.

Each call to this function should have a matching call to SDL_hid_exit()

Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.
See also
SDL_hid_exit

◆ SDL_hid_open()

SDL_hid_device * SDL_hid_open ( unsigned short  vendor_id,
unsigned short  product_id,
const wchar_t *  serial_number 
)
extern

Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.

If serial_number is NULL, the first device with the specified VID and PID is opened.

Parameters
vendor_idthe Vendor ID (VID) of the device to open.
product_idthe Product ID (PID) of the device to open.
serial_numberthe Serial Number of the device to open (Optionally NULL).
Returns
a pointer to a SDL_hid_device object on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_open_path()

SDL_hid_device * SDL_hid_open_path ( const char *  path)
extern

Open a HID device by its path name.

The path name be determined by calling SDL_hid_enumerate(), or a platform-specific path name can be used (eg: /dev/hidraw0 on Linux).

Parameters
paththe path name of the device to open.
Returns
a pointer to a SDL_hid_device object on success or NULL on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_read()

int SDL_hid_read ( SDL_hid_device dev,
unsigned char *  data,
size_t  length 
)
extern

Read an Input report from a HID device.

Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.

Parameters
deva device handle returned from SDL_hid_open().
dataa buffer to put the read data into.
lengththe number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
Returns
the actual number of bytes read and -1 on failure; call SDL_GetError() for more information. If no packet was available to be read and the handle is in non-blocking mode, this function returns 0.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_read_timeout()

int SDL_hid_read_timeout ( SDL_hid_device dev,
unsigned char *  data,
size_t  length,
int  milliseconds 
)
extern

Read an Input report from a HID device with timeout.

Input reports are returned to the host through the INTERRUPT IN endpoint. The first byte will contain the Report number if the device uses numbered reports.

Parameters
deva device handle returned from SDL_hid_open().
dataa buffer to put the read data into.
lengththe number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number.
millisecondstimeout in milliseconds or -1 for blocking wait.
Returns
the actual number of bytes read and -1 on on failure; call SDL_GetError() for more information. If no packet was available to be read within the timeout period, this function returns 0.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_send_feature_report()

int SDL_hid_send_feature_report ( SDL_hid_device dev,
const unsigned char *  data,
size_t  length 
)
extern

Send a Feature report to the device.

Feature reports are sent over the Control endpoint as a Set_Report transfer. The first byte of data must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to SDL_hid_send_feature_report() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for devices which do not use numbered reports), followed by the report data (16 bytes). In this example, the length passed in would be 17.

Parameters
deva device handle returned from SDL_hid_open().
datathe data to send, including the report number as the first byte.
lengththe length in bytes of the data to send, including the report number.
Returns
the actual number of bytes written and -1 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_set_nonblocking()

int SDL_hid_set_nonblocking ( SDL_hid_device dev,
int  nonblock 
)
extern

Set the device handle to be non-blocking.

In non-blocking mode calls to SDL_hid_read() will return immediately with a value of 0 if there is no data to be read. In blocking mode, SDL_hid_read() will wait (block) until there is data to read before returning.

Nonblocking can be turned on and off at any time.

Parameters
deva device handle returned from SDL_hid_open().
nonblockenable or not the nonblocking reads - 1 to enable nonblocking - 0 to disable nonblocking.
Returns
0 on success or a negative error code on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.

◆ SDL_hid_write()

int SDL_hid_write ( SDL_hid_device dev,
const unsigned char *  data,
size_t  length 
)
extern

Write an Output report to a HID device.

The first byte of data must contain the Report ID. For devices which only support a single report, this must be set to 0x0. The remaining bytes contain the report data. Since the Report ID is mandatory, calls to SDL_hid_write() will always contain one more byte than the report contains. For example, if a hid report is 16 bytes long, 17 bytes must be passed to SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), followed by the report data (16 bytes). In this example, the length passed in would be 17.

SDL_hid_write() will send the data on the first OUT endpoint, if one exists. If it does not, it will send the data through the Control Endpoint (Endpoint 0).

Parameters
deva device handle returned from SDL_hid_open().
datathe data to send, including the report number as the first byte.
lengththe length in bytes of the data to send.
Returns
the actual number of bytes written and -1 on on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.1.3.