Header file for SDL HIDAPI functions. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::Hidapi
	HIDAPI properties.

Classes
struct	SDL::HidDevice
	An opaque handle representing an open HID device. More...

Typedefs
using	SDL::HidDeviceRaw = SDL_hid_device*
	Alias to raw representation for HidDevice.
using	SDL::HidDeviceRef = ResourceRef<HidDevice>
	Reference for HidDevice.
using	SDL::hid_bus_type = SDL_hid_bus_type
	HID underlying bus types.
using	SDL::hid_device_info = SDL_hid_device_info
	Information about a connected HID device.

Functions
void	SDL::hid_init ()
	Initialize the HIDAPI library.
void	SDL::hid_exit ()
	Finalize the HIDAPI library.
Uint32	SDL::hid_device_change_count ()
	Check to see if devices may have been added or removed.
hid_device_info *	SDL::hid_enumerate (unsigned short vendor_id, unsigned short product_id)
	Enumerate the HID Devices.
void	SDL::hid_free_enumeration (hid_device_info *devs)
	Free an enumeration linked list.
HidDevice	SDL::hid_open (unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
	Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.
HidDevice	SDL::hid_open_path (StringParam path)
	Open a HID device by its path name.
PropertiesRef	SDL::hid_get_properties (HidDeviceRef dev)
	Get the properties associated with an HidDevice.
int	SDL::hid_write (HidDeviceRef dev, SourceBytes data)
	Write an Output report to a HID device.
int	SDL::hid_read_timeout (HidDeviceRef dev, TargetBytes data, Milliseconds timeout)
	Read an Input report from a HID device with timeout.
int	SDL::hid_read (HidDeviceRef dev, TargetBytes data)
	Read an Input report from a HID device.
void	SDL::hid_set_nonblocking (HidDeviceRef dev, bool nonblock)
	Set the device handle to be non-blocking.
int	SDL::hid_send_feature_report (HidDeviceRef dev, SourceBytes data)
	Send a Feature report to the device.
int	SDL::hid_get_feature_report (HidDeviceRef dev, TargetBytes data)
	Get a feature report from a HID device.
int	SDL::hid_get_input_report (HidDeviceRef dev, TargetBytes data)
	Get an input report from a HID device.
void	SDL::hid_close (HidDeviceRaw dev)
	Close a HID device.
void	SDL::hid_get_manufacturer_string (HidDeviceRef dev, wchar_t *string, size_t maxlen)
	Get The Manufacturer String from a HID device.
void	SDL::hid_get_product_string (HidDeviceRef dev, wchar_t *string, size_t maxlen)
	Get The Product String from a HID device.
void	SDL::hid_get_serial_number_string (HidDeviceRef dev, wchar_t *string, size_t maxlen)
	Get The Serial Number String from a HID device.
void	SDL::hid_get_indexed_string (HidDeviceRef dev, int string_index, wchar_t *string, size_t maxlen)
	Get a string from a HID device, based on its string index.
hid_device_info *	SDL::hid_get_device_info (HidDeviceRef dev)
	Get the device info from a HID device.
int	SDL::hid_get_report_descriptor (HidDeviceRef dev, TargetBytes buf)
	Get a report descriptor from a HID device.
void	SDL::hid_ble_scan (bool active)
	Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
	SDL::HidDevice::HidDevice (unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number)
	Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally a serial number.
	SDL::HidDevice::HidDevice (StringParam path)
	Open a HID device by its path name.
PropertiesRef	SDL::HidDevice::hid_get_properties ()
	Get the properties associated with an HidDevice.
int	SDL::HidDevice::write (SourceBytes data)
	Write an Output report to a HID device.
int	SDL::HidDevice::read_timeout (TargetBytes data, Milliseconds timeout)
	Read an Input report from a HID device with timeout.
int	SDL::HidDevice::read (TargetBytes data)
	Read an Input report from a HID device.
void	SDL::HidDevice::set_nonblocking (bool nonblock)
	Set the device handle to be non-blocking.
int	SDL::HidDevice::send_feature_report (SourceBytes data)
	Send a Feature report to the device.
int	SDL::HidDevice::get_feature_report (TargetBytes data)
	Get a feature report from a HID device.
int	SDL::HidDevice::get_input_report (TargetBytes data)
	Get an input report from a HID device.
void	SDL::HidDevice::close ()
	Close a HID device.
void	SDL::HidDevice::get_manufacturer_string (wchar_t *string, size_t maxlen)
	Get The Manufacturer String from a HID device.
void	SDL::HidDevice::get_product_string (wchar_t *string, size_t maxlen)
	Get The Product String from a HID device.
void	SDL::HidDevice::get_serial_number_string (wchar_t *string, size_t maxlen)
	Get The Serial Number String from a HID device.
void	SDL::HidDevice::get_indexed_string (int string_index, wchar_t *string, size_t maxlen)
	Get a string from a HID device, based on its string index.
hid_device_info *	SDL::HidDevice::get_device_info ()
	Get the device info from a HID device.
int	SDL::HidDevice::get_report_descriptor (TargetBytes buf)
	Get a report descriptor from a HID device.

Variables
constexpr hid_bus_type	SDL::HID_API_BUS_UNKNOWN
	Unknown bus type.
constexpr hid_bus_type	SDL::HID_API_BUS_USB = SDL_HID_API_BUS_USB
	USB bus Specifications:
constexpr hid_bus_type	SDL::HID_API_BUS_BLUETOOTH = SDL_HID_API_BUS_BLUETOOTH
	Bluetooth or Bluetooth LE bus Specifications:
constexpr hid_bus_type	SDL::HID_API_BUS_I2C = SDL_HID_API_BUS_I2C
	I2C bus Specifications:
constexpr hid_bus_type	SDL::HID_API_BUS_SPI = SDL_HID_API_BUS_SPI
	SPI bus Specifications:

Detailed Description

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.

Typedef Documentation

◆ hid_bus_type

using SDL::hid_bus_type = SDL_hid_bus_type

HID underlying bus types.

Since: This enum is available since SDL 3.2.0.

◆ hid_device_info

using SDL::hid_device_info = SDL_hid_device_info

Information about a connected HID device.

Since: This struct is available since SDL 3.2.0.

◆ HidDeviceRef

using SDL::HidDeviceRef = ResourceRef<HidDevice>

Reference for HidDevice.

This does not take ownership!

Function Documentation

◆ close()

void SDL::HidDevice::close ( )

inline

Close a HID device.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ get_device_info()

hid_device_info * SDL::HidDevice::get_device_info ( )

inline

Get the device info from a HID device.

Returns: a pointer to the hid_device_info for this hid_device on success. This struct is valid until the device is closed with HidDevice.close().

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ get_feature_report()

int SDL::HidDevice::get_feature_report ( TargetBytes data )

inline

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

data	a 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.

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 GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ get_indexed_string()

void SDL::HidDevice::get_indexed_string	(	int	string_index,
		wchar_t *	string,
		size_t	maxlen )

inline

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

Parameters

string_index	the index of the string to get.
string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ get_input_report()

int SDL::HidDevice::get_input_report ( TargetBytes data )

inline

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

data	a 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.

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 GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ get_manufacturer_string()

void SDL::HidDevice::get_manufacturer_string	(	wchar_t *	string,
		size_t	maxlen )

inline

Get The Manufacturer String from a HID device.

Parameters

string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ get_product_string()

void SDL::HidDevice::get_product_string	(	wchar_t *	string,
		size_t	maxlen )

inline

Get The Product String from a HID device.

Parameters

string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ get_report_descriptor()

int SDL::HidDevice::get_report_descriptor ( TargetBytes buf )

inline

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

buf	the buffer to copy descriptor into.

Returns: the number of bytes actually copied or -1 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ get_serial_number_string()

void SDL::HidDevice::get_serial_number_string	(	wchar_t *	string,
		size_t	maxlen )

inline

Get The Serial Number String from a HID device.

Parameters

string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_ble_scan()

void SDL::hid_ble_scan ( bool active )

inline

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

Parameters

active true to start the scan, false to stop the scan.

Since: This function is available since SDL 3.2.0.

◆ hid_close()

void SDL::hid_close ( HidDeviceRaw dev )

inline

Close a HID device.

Parameters

dev	a device handle returned from hid_open().

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_device_change_count()

Uint32 SDL::hid_device_change_count ( )

inline

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 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.2.0.

See also: hid_enumerate

◆ hid_enumerate()

hid_device_info * SDL::hid_enumerate	(	unsigned short	vendor_id,
		unsigned short	product_id )

inline

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_id	the Vendor ID (VID) of the types of device to open, or 0 to match any vendor.
product_id	the 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 hid_device_info, containing information about the HID devices attached to the system on success. Free this linked list by calling hid_free_enumeration().

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: hid_device_change_count

◆ hid_exit()

void SDL::hid_exit ( )

inline

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.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: hid_init

◆ hid_free_enumeration()

void SDL::hid_free_enumeration ( hid_device_info * devs )

inline

Free an enumeration linked list.

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

Parameters

devs	pointer to a list of struct_device returned from hid_enumerate().

Since: This function is available since SDL 3.2.0.

◆ hid_get_device_info()

hid_device_info * SDL::hid_get_device_info ( HidDeviceRef dev )

inline

Get the device info from a HID device.

Parameters

dev	a device handle returned from hid_open().

Returns: a pointer to the hid_device_info for this hid_device on success. This struct is valid until the device is closed with HidDevice.close().

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_get_feature_report()

int SDL::hid_get_feature_report	(	HidDeviceRef	dev,
		TargetBytes	data )

inline

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

dev	a device handle returned from hid_open().
data	a 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.

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 GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ hid_get_indexed_string()

void SDL::hid_get_indexed_string	(	HidDeviceRef	dev,
		int	string_index,
		wchar_t *	string,
		size_t	maxlen )

inline

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

Parameters

dev	a device handle returned from hid_open().
string_index	the index of the string to get.
string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_get_input_report()

int SDL::hid_get_input_report	(	HidDeviceRef	dev,
		TargetBytes	data )

inline

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

dev	a device handle returned from hid_open().
data	a 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.

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 GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ hid_get_manufacturer_string()

void SDL::hid_get_manufacturer_string	(	HidDeviceRef	dev,
		wchar_t *	string,
		size_t	maxlen )

inline

Get The Manufacturer String from a HID device.

Parameters

dev	a device handle returned from hid_open().
string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_get_product_string()

void SDL::hid_get_product_string	(	HidDeviceRef	dev,
		wchar_t *	string,
		size_t	maxlen )

inline

Get The Product String from a HID device.

Parameters

dev	a device handle returned from hid_open().
string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_get_properties() [1/2]

PropertiesRef SDL::hid_get_properties ( HidDeviceRef dev )

inline

Get the properties associated with an HidDevice.

The following read-only properties are provided by SDL:

prop.Hidapi.LIBUSB_DEVICE_HANDLE_POINTER: the libusb_device_handle associated with the device, if it was opened using libusb.

Parameters

dev	a device handle returned from hid_open().

Returns: a valid property ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.4.0.

◆ hid_get_properties() [2/2]

PropertiesRef SDL::HidDevice::hid_get_properties ( )

inline

Get the properties associated with an HidDevice.

The following read-only properties are provided by SDL:

prop.Hidapi.LIBUSB_DEVICE_HANDLE_POINTER: the libusb_device_handle associated with the device, if it was opened using libusb.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.4.0.

◆ hid_get_report_descriptor()

int SDL::hid_get_report_descriptor	(	HidDeviceRef	dev,
		TargetBytes	buf )

inline

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

dev	a device handle returned from hid_open().
buf	the buffer to copy descriptor into.

Returns: the number of bytes actually copied or -1 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ hid_get_serial_number_string()

void SDL::hid_get_serial_number_string	(	HidDeviceRef	dev,
		wchar_t *	string,
		size_t	maxlen )

inline

Get The Serial Number String from a HID device.

Parameters

dev	a device handle returned from hid_open().
string	a wide string buffer to put the data into.
maxlen	the length of the buffer in multiples of wchar_t.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_init()

void SDL::hid_init ( )

inline

Initialize the HIDAPI library.

This function initializes the HIDAPI library. Calling it is not strictly necessary, as it will be called automatically by 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 hid_exit()

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

See also: hid_exit

◆ hid_open()

HidDevice SDL::hid_open	(	unsigned short	vendor_id,
		unsigned short	product_id,
		const wchar_t *	serial_number )

inline

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

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

Parameters

vendor_id	the Vendor ID (VID) of the device to open.
product_id	the Product ID (PID) of the device to open.
serial_number	the Serial Number of the device to open (Optionally nullptr).

Returns: a HidDevice object on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_open_path()

HidDevice SDL::hid_open_path ( StringParam path )

inline

Open a HID device by its path name.

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

Parameters

path	the path name of the device to open.

Returns: a HidDevice object on success.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_read()

int SDL::hid_read	(	HidDeviceRef	dev,
		TargetBytes	data )

inline

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

dev	a device handle returned from hid_open().
data	a buffer to put the read data into.

Returns: the actual number of bytes read and -1 on failure; call 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.2.0.

◆ hid_read_timeout()

int SDL::hid_read_timeout	(	HidDeviceRef	dev,
		TargetBytes	data,
		Milliseconds	timeout )

inline

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

dev	a device handle returned from hid_open().
data	a buffer to put the read data into.
timeout	timeout in milliseconds

Returns: the actual number of bytes read and -1 on on failure; call 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.2.0.

◆ hid_send_feature_report()

int SDL::hid_send_feature_report	(	HidDeviceRef	dev,
		SourceBytes	data )

inline

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 HidDevice.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 HidDevice.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

dev	a device handle returned from hid_open().
data	the data to send, including the report number as the first byte.

Returns: the actual number of bytes written and -1 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ hid_set_nonblocking()

void SDL::hid_set_nonblocking	(	HidDeviceRef	dev,
		bool	nonblock )

inline

Set the device handle to be non-blocking.

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

Nonblocking can be turned on and off at any time.

Parameters

dev	a device handle returned from hid_open().
nonblock	enable or not the nonblocking reads - true to enable nonblocking - false to disable nonblocking.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ hid_write()

int SDL::hid_write	(	HidDeviceRef	dev,
		SourceBytes	data )

inline

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 HidDevice.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 HidDevice.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.

HidDevice.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

dev	a device handle returned from hid_open().
data	the data to send, including the report number as the first byte.

Returns: the actual number of bytes written and -1 on on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ HidDevice() [1/2]

SDL::HidDevice::HidDevice ( StringParam path )

inline

Open a HID device by its path name.

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

Parameters

path	the path name of the device to open.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ HidDevice() [2/2]

SDL::HidDevice::HidDevice	(	unsigned short	vendor_id,
		unsigned short	product_id,
		const wchar_t *	serial_number )

inline

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

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

Parameters

vendor_id	the Vendor ID (VID) of the device to open.
product_id	the Product ID (PID) of the device to open.
serial_number	the Serial Number of the device to open (Optionally nullptr).

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ read()

int SDL::HidDevice::read ( TargetBytes data )

inline

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

data	a buffer to put the read data into.

Returns: the actual number of bytes read and -1 on failure; call 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.2.0.

◆ read_timeout()

int SDL::HidDevice::read_timeout	(	TargetBytes	data,
		Milliseconds	timeout )

inline

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

data	a buffer to put the read data into.
timeout	timeout in milliseconds

Returns: the actual number of bytes read and -1 on on failure; call 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.2.0.

◆ send_feature_report()

int SDL::HidDevice::send_feature_report ( SourceBytes data )

inline

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 HidDevice.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 HidDevice.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

data	the data to send, including the report number as the first byte.

Returns: the actual number of bytes written and -1 on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

◆ set_nonblocking()

void SDL::HidDevice::set_nonblocking ( bool nonblock )

inline

Set the device handle to be non-blocking.

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

Nonblocking can be turned on and off at any time.

Parameters

nonblock enable or not the nonblocking reads - true to enable nonblocking - false to disable nonblocking.

Exceptions

Error on failure.

Since: This function is available since SDL 3.2.0.

◆ write()

int SDL::HidDevice::write ( SourceBytes data )

inline

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 HidDevice.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 HidDevice.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.

HidDevice.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

data	the data to send, including the report number as the first byte.

Returns: the actual number of bytes written and -1 on on failure; call GetError() for more information.

Since: This function is available since SDL 3.2.0.

Variable Documentation

◆ HID_API_BUS_BLUETOOTH

hid_bus_type SDL::HID_API_BUS_BLUETOOTH = SDL_HID_API_BUS_BLUETOOTH

constexpr

Bluetooth or Bluetooth LE bus Specifications:

◆ HID_API_BUS_I2C

hid_bus_type SDL::HID_API_BUS_I2C = SDL_HID_API_BUS_I2C

constexpr

I2C bus Specifications:

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

◆ HID_API_BUS_SPI

hid_bus_type SDL::HID_API_BUS_SPI = SDL_HID_API_BUS_SPI

constexpr

SPI bus Specifications:

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

◆ HID_API_BUS_UNKNOWN

hid_bus_type SDL::HID_API_BUS_UNKNOWN

constexpr

Initial value:

=

SDL_HID_API_BUS_UNKNOWN

Unknown bus type.

◆ HID_API_BUS_USB

hid_bus_type SDL::HID_API_BUS_USB = SDL_HID_API_BUS_USB

constexpr

USB bus Specifications:

https://usb.org/hid

Namespaces

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ hid_bus_type

◆ hid_device_info

◆ HidDeviceRef

Function Documentation

◆ close()

◆ get_device_info()

◆ get_feature_report()

◆ get_indexed_string()

◆ get_input_report()

◆ get_manufacturer_string()

◆ get_product_string()

◆ get_report_descriptor()

◆ get_serial_number_string()

◆ hid_ble_scan()

◆ hid_close()

◆ hid_device_change_count()

◆ hid_enumerate()

◆ hid_exit()

◆ hid_free_enumeration()

◆ hid_get_device_info()

◆ hid_get_feature_report()

◆ hid_get_indexed_string()

◆ hid_get_input_report()

◆ hid_get_manufacturer_string()

◆ hid_get_product_string()

◆ hid_get_properties() [1/2]

◆ hid_get_properties() [2/2]

◆ hid_get_report_descriptor()

◆ hid_get_serial_number_string()

◆ hid_init()

◆ hid_open()

◆ hid_open_path()

◆ hid_read()

◆ hid_read_timeout()

◆ hid_send_feature_report()

◆ hid_set_nonblocking()

◆ hid_write()

◆ HidDevice() [1/2]

◆ HidDevice() [2/2]

◆ read()

◆ read_timeout()

◆ send_feature_report()

◆ set_nonblocking()

◆ write()

Variable Documentation

◆ HID_API_BUS_BLUETOOTH

◆ HID_API_BUS_I2C

◆ HID_API_BUS_SPI

◆ HID_API_BUS_UNKNOWN

◆ HID_API_BUS_USB