SDL
2.0
|
Go to the source code of this file.
Data Structures | |
struct | SDL_hid_device_info |
Information about a connected HID device. More... | |
Typedefs | |
typedef struct SDL_hid_device_ | SDL_hid_device |
Functions | |
int | SDL_hid_init (void) |
int | SDL_hid_exit (void) |
Uint32 | SDL_hid_device_change_count (void) |
SDL_hid_device_info * | SDL_hid_enumerate (unsigned short vendor_id, unsigned short product_id) |
void | SDL_hid_free_enumeration (SDL_hid_device_info *devs) |
SDL_hid_device * | SDL_hid_open (unsigned short vendor_id, unsigned short product_id, const wchar_t *serial_number) |
SDL_hid_device * | SDL_hid_open_path (const char *path, int bExclusive) |
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) |
void | 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) |
void | SDL_hid_ble_scan (SDL_bool active) |
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 BSD license:
Copyright (c) 2010, Alan Ott, Signal 11 Software All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of Signal 11 Software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
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.
Definition in file SDL_hidapi.h.
typedef struct SDL_hid_device_ SDL_hid_device |
opaque hidapi structure
Definition at line 1 of file SDL_hidapi.h.
void SDL_hid_ble_scan | ( | SDL_bool | active | ) |
Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers
active | SDL_TRUE to start the scan, SDL_FALSE to stop the scan |
void SDL_hid_close | ( | SDL_hid_device * | dev | ) |
Close a HID device.
dev | A device handle returned from SDL_hid_open(). |
Uint32 SDL_hid_device_change_count | ( | void | ) |
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.
SDL_hid_device_info* SDL_hid_enumerate | ( | unsigned short | vendor_id, |
unsigned short | product_id | ||
) |
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.
vendor_id | The Vendor ID (VID) of the types of device to open. |
product_id | The Product ID (PID) of the types of device to open. |
int SDL_hid_exit | ( | void | ) |
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.
void SDL_hid_free_enumeration | ( | SDL_hid_device_info * | devs | ) |
Free an enumeration Linked List
This function frees a linked list created by SDL_hid_enumerate().
devs | Pointer to a list of struct_device returned from SDL_hid_enumerate(). |
int SDL_hid_get_feature_report | ( | SDL_hid_device * | dev, |
unsigned char * | data, | ||
size_t | length | ||
) |
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].
dev | A device handle returned from SDL_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. |
length | The number of bytes to read, including an extra byte for the report ID. The buffer can be longer than the actual report. |
int SDL_hid_get_indexed_string | ( | SDL_hid_device * | dev, |
int | string_index, | ||
wchar_t * | string, | ||
size_t | maxlen | ||
) |
Get a string from a HID device, based on its string index.
dev | A device handle returned from SDL_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. |
int SDL_hid_get_manufacturer_string | ( | SDL_hid_device * | dev, |
wchar_t * | string, | ||
size_t | maxlen | ||
) |
Get The Manufacturer String from a HID device.
dev | A device handle returned from SDL_hid_open(). |
string | A wide string buffer to put the data into. |
maxlen | The length of the buffer in multiples of wchar_t. |
int SDL_hid_get_product_string | ( | SDL_hid_device * | dev, |
wchar_t * | string, | ||
size_t | maxlen | ||
) |
Get The Product String from a HID device.
dev | A device handle returned from SDL_hid_open(). |
string | A wide string buffer to put the data into. |
maxlen | The length of the buffer in multiples of wchar_t. |
int SDL_hid_get_serial_number_string | ( | SDL_hid_device * | dev, |
wchar_t * | string, | ||
size_t | maxlen | ||
) |
Get The Serial Number String from a HID device.
dev | A device handle returned from SDL_hid_open(). |
string | A wide string buffer to put the data into. |
maxlen | The length of the buffer in multiples of wchar_t. |
int SDL_hid_init | ( | void | ) |
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()
SDL_hid_device* 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.
If serial_number
is NULL, 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 NULL). |
SDL_hid_device* SDL_hid_open_path | ( | const char * | path, |
int | bExclusive | ||
) |
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).
path | The path name of the device to open |
int SDL_hid_read | ( | SDL_hid_device * | dev, |
unsigned char * | data, | ||
size_t | length | ||
) |
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.
dev | A device handle returned from SDL_hid_open(). |
data | A buffer to put the read data into. |
length | The number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number. |
int SDL_hid_read_timeout | ( | SDL_hid_device * | dev, |
unsigned char * | data, | ||
size_t | length, | ||
int | milliseconds | ||
) |
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.
dev | A device handle returned from SDL_hid_open(). |
data | A buffer to put the read data into. |
length | The number of bytes to read. For devices with multiple reports, make sure to read an extra byte for the report number. |
milliseconds | timeout in milliseconds or -1 for blocking wait. |
int SDL_hid_send_feature_report | ( | SDL_hid_device * | dev, |
const unsigned char * | data, | ||
size_t | length | ||
) |
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.
dev | A device handle returned from SDL_hid_open(). |
data | The data to send, including the report number as the first byte. |
length | The length in bytes of the data to send, including the report number. |
int SDL_hid_set_nonblocking | ( | SDL_hid_device * | dev, |
int | nonblock | ||
) |
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.
dev | A device handle returned from SDL_hid_open(). |
nonblock | enable or not the nonblocking reads - 1 to enable nonblocking - 0 to disable nonblocking. |
int SDL_hid_write | ( | SDL_hid_device * | dev, |
const unsigned char * | data, | ||
size_t | length | ||
) |
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).
dev | A device handle returned from SDL_hid_open(). |
data | The data to send, including the report number as the first byte. |
length | The length in bytes of the data to send. |