SDL3pp
A slim C++ wrapper for SDL3
|
Header file for SDL HIDAPI functions. More...
Classes | |
struct | SDL::HidDeviceParam |
Safely wrap HidDevice for non owning parameters. More... | |
class | SDL::HidDevice |
An opaque handle representing an open HID device. More... | |
struct | SDL::HidDeviceRef |
Semi-safe reference for HidDevice. More... | |
Typedefs | |
using | SDL::HidDeviceRaw = SDL_hid_device * |
Alias to raw representation for HidDevice. | |
using | SDL::hid_bus_type = SDL_hid_bus_type |
HID underlying bus types. More... | |
using | SDL::hid_device_info = SDL_hid_device_info |
Information about a connected HID device. More... | |
Functions | |
void | SDL::hid_init () |
Initialize the HIDAPI library. More... | |
void | SDL::hid_exit () |
Finalize the HIDAPI library. More... | |
Uint32 | SDL::hid_device_change_count () |
Check to see if devices may have been added or removed. More... | |
hid_device_info * | SDL::hid_enumerate (unsigned short vendor_id, unsigned short product_id) |
Enumerate the HID Devices. More... | |
void | SDL::hid_free_enumeration (hid_device_info *devs) |
Free an enumeration linked list. More... | |
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. More... | |
HidDevice | SDL::hid_open_path (StringParam path) |
Open a HID device by its path name. More... | |
int | SDL::hid_write (HidDeviceParam dev, SourceBytes data) |
Write an Output report to a HID device. More... | |
int | SDL::hid_read_timeout (HidDeviceParam dev, TargetBytes data, Milliseconds timeout) |
Read an Input report from a HID device with timeout. More... | |
int | SDL::hid_read (HidDeviceParam dev, TargetBytes data) |
Read an Input report from a HID device. More... | |
void | SDL::hid_set_nonblocking (HidDeviceParam dev, bool nonblock) |
Set the device handle to be non-blocking. More... | |
int | SDL::hid_send_feature_report (HidDeviceParam dev, SourceBytes data) |
Send a Feature report to the device. More... | |
int | SDL::hid_get_feature_report (HidDeviceParam dev, TargetBytes data) |
Get a feature report from a HID device. More... | |
int | SDL::hid_get_input_report (HidDeviceParam dev, TargetBytes data) |
Get an input report from a HID device. More... | |
void | SDL::hid_close (HidDeviceRaw dev) |
Close a HID device. More... | |
void | SDL::hid_get_manufacturer_string (HidDeviceParam dev, wchar_t *string, size_t maxlen) |
Get The Manufacturer String from a HID device. More... | |
void | SDL::hid_get_product_string (HidDeviceParam dev, wchar_t *string, size_t maxlen) |
Get The Product String from a HID device. More... | |
void | SDL::hid_get_serial_number_string (HidDeviceParam dev, wchar_t *string, size_t maxlen) |
Get The Serial Number String from a HID device. More... | |
void | SDL::hid_get_indexed_string (HidDeviceParam dev, int string_index, wchar_t *string, size_t maxlen) |
Get a string from a HID device, based on its string index. More... | |
hid_device_info * | SDL::hid_get_device_info (HidDeviceParam dev) |
Get the device info from a HID device. More... | |
int | SDL::hid_get_report_descriptor (HidDeviceParam dev, TargetBytes buf) |
Get a report descriptor from a HID device. More... | |
void | SDL::hid_ble_scan (bool active) |
Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. More... | |
int | SDL::HidDevice::write (SourceBytes data) |
Write an Output report to a HID device. More... | |
int | SDL::HidDevice::read_timeout (TargetBytes data, Milliseconds timeout) |
Read an Input report from a HID device with timeout. More... | |
int | SDL::HidDevice::read (TargetBytes data) |
Read an Input report from a HID device. More... | |
void | SDL::HidDevice::set_nonblocking (bool nonblock) |
Set the device handle to be non-blocking. More... | |
int | SDL::HidDevice::send_feature_report (SourceBytes data) |
Send a Feature report to the device. More... | |
int | SDL::HidDevice::get_feature_report (TargetBytes data) |
Get a feature report from a HID device. More... | |
int | SDL::HidDevice::get_input_report (TargetBytes data) |
Get an input report from a HID device. More... | |
void | SDL::HidDevice::close () |
Close a HID device. More... | |
void | SDL::HidDevice::get_manufacturer_string (wchar_t *string, size_t maxlen) |
Get The Manufacturer String from a HID device. More... | |
void | SDL::HidDevice::get_product_string (wchar_t *string, size_t maxlen) |
Get The Product String from a HID device. More... | |
void | SDL::HidDevice::get_serial_number_string (wchar_t *string, size_t maxlen) |
Get The Serial Number String from a HID device. More... | |
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. More... | |
hid_device_info * | SDL::HidDevice::get_device_info () |
Get the device info from a HID device. More... | |
int | SDL::HidDevice::get_report_descriptor (TargetBytes buf) |
Get a report descriptor from a HID device. More... | |
Variables | |
constexpr hid_bus_type | SDL::HID_API_BUS_UNKNOWN |
Unknown bus type. More... | |
constexpr hid_bus_type | SDL::HID_API_BUS_USB |
[object Object] More... | |
constexpr hid_bus_type | SDL::HID_API_BUS_BLUETOOTH |
[object Object] More... | |
constexpr hid_bus_type | SDL::HID_API_BUS_I2C |
[object Object] More... | |
constexpr hid_bus_type | SDL::HID_API_BUS_SPI |
[object Object] More... | |
This is an adaptation of the original HIDAPI interface by Alan Ott, and includes source code licensed under the following license:
(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.
using SDL::hid_bus_type = typedef SDL_hid_bus_type |
using SDL::hid_device_info = typedef SDL_hid_device_info |
|
inline |
|
inline |
Error | on failure. |
|
inline |
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].
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. |
|
inline |
|
inline |
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].
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. |
|
inline |
|
inline |
|
inline |
User has to provide a preallocated buffer where descriptor will be copied to. The recommended size for a preallocated buffer is 4096 bytes.
buf | the buffer to copy descriptor into. |
|
inline |
|
inline |
active | true to start the scan, false to stop the scan. |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
Error | on failure. |
|
inline |
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.
|
inline |
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.
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. |
Error | on failure. |
|
inline |
|
inline |
This function frees a linked list created by hid_enumerate().
devs | pointer to a list of struct_device returned from hid_enumerate(). |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
Error | on failure. |
|
inline |
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].
dev | a device handle returned from HidDevice.HidDevice(). |
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. |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
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. |
Error | on failure. |
|
inline |
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].
dev | a device handle returned from HidDevice.HidDevice(). |
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. |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
string | a wide string buffer to put the data into. |
maxlen | the length of the buffer in multiples of wchar_t. |
Error | on failure. |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
string | a wide string buffer to put the data into. |
maxlen | the length of the buffer in multiples of wchar_t. |
Error | on failure. |
|
inline |
User has to provide a preallocated buffer where descriptor will be copied to. The recommended size for a preallocated buffer is 4096 bytes.
dev | a device handle returned from HidDevice.HidDevice(). |
buf | the buffer to copy descriptor into. |
|
inline |
dev | a device handle returned from HidDevice.HidDevice(). |
string | a wide string buffer to put the data into. |
maxlen | the length of the buffer in multiples of wchar_t. |
Error | on failure. |
|
inline |
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()
Error | on failure. |
|
inline |
If serial_number
is nullptr, the first device with the specified VID and PID is opened.
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). |
Error | on failure. |
|
inline |
The path name be determined by calling hid_enumerate(), or a platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
path | the path name of the device to open. |
Error | on failure. |
|
inline |
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.
dev | a device handle returned from HidDevice.HidDevice(). |
data | a buffer to put the read data into. |
|
inline |
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.
dev | a device handle returned from HidDevice.HidDevice(). |
data | a buffer to put the read data into. |
timeout | timeout in milliseconds |
|
inline |
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.
dev | a device handle returned from HidDevice.HidDevice(). |
data | the data to send, including the report number as the first byte. |
|
inline |
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.
dev | a device handle returned from HidDevice.HidDevice(). |
nonblock | enable or not the nonblocking reads - true to enable nonblocking - false to disable nonblocking. |
Error | on failure. |
|
inline |
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).
dev | a device handle returned from HidDevice.HidDevice(). |
data | the data to send, including the report number as the first byte. |
|
inline |
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.
data | a buffer to put the read data into. |
|
inline |
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.
data | a buffer to put the read data into. |
timeout | timeout in milliseconds |
|
inline |
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.
data | the data to send, including the report number as the first byte. |
|
inline |
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.
nonblock | enable or not the nonblocking reads - true to enable nonblocking - false to disable nonblocking. |
Error | on failure. |
|
inline |
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).
data | the data to send, including the report number as the first byte. |
|
constexpr |
|
constexpr |
|
constexpr |
|
constexpr |
|
constexpr |