sdl3_sys/generated/
hidapi.rs

1//! Header file for SDL HIDAPI functions.
2//!
3//! This is an adaptation of the original HIDAPI interface by Alan Ott, and
4//! includes source code licensed under the following license:
5//!
6//! ```text
7//! HIDAPI - Multi-Platform library for
8//! communication with HID devices.
9//!
10//! Copyright 2009, Alan Ott, Signal 11 Software.
11//! All Rights Reserved.
12//!
13//! This software may be used by anyone for any reason so
14//! long as the copyright notice in the source files
15//! remains intact.
16//! ```
17//!
18//! (Note that this license is the same as item three of SDL's zlib license, so
19//! it adds no new requirements on the user.)
20//!
21//! If you would like a version of SDL without this code, you can build SDL
22//! with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for
23//! example on iOS or tvOS to avoid a dependency on the CoreBluetooth
24//! framework.
25
26use super::stdinc::*;
27
28use super::error::*;
29
30use super::properties::*;
31
32/// HID underlying bus types.
33///
34/// ## Availability
35/// This enum is available since SDL 3.2.0.
36///
37/// ## Known values (`sdl3-sys`)
38/// | Associated constant | Global constant | Description |
39/// | ------------------- | --------------- | ----------- |
40/// | [`UNKNOWN`](SDL_hid_bus_type::UNKNOWN) | [`SDL_HID_API_BUS_UNKNOWN`] | Unknown bus type |
41/// | [`USB`](SDL_hid_bus_type::USB) | [`SDL_HID_API_BUS_USB`] |  USB bus Specifications: <https://usb.org/hid> |
42/// | [`BLUETOOTH`](SDL_hid_bus_type::BLUETOOTH) | [`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/> |
43/// | [`I2C`](SDL_hid_bus_type::I2C) | [`SDL_HID_API_BUS_I2C`] |  I2C bus Specifications: <https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85)> |
44/// | [`SPI`](SDL_hid_bus_type::SPI) | [`SDL_HID_API_BUS_SPI`] |  SPI bus Specifications: <https://www.microsoft.com/download/details.aspx?id=103325> |
45#[repr(transparent)]
46#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
47pub struct SDL_hid_bus_type(pub ::core::ffi::c_int);
48
49impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_hid_bus_type {
50    #[inline(always)]
51    fn eq(&self, other: &::core::ffi::c_int) -> bool {
52        &self.0 == other
53    }
54}
55
56impl ::core::cmp::PartialEq<SDL_hid_bus_type> for ::core::ffi::c_int {
57    #[inline(always)]
58    fn eq(&self, other: &SDL_hid_bus_type) -> bool {
59        self == &other.0
60    }
61}
62
63impl From<SDL_hid_bus_type> for ::core::ffi::c_int {
64    #[inline(always)]
65    fn from(value: SDL_hid_bus_type) -> Self {
66        value.0
67    }
68}
69
70#[cfg(feature = "debug-impls")]
71impl ::core::fmt::Debug for SDL_hid_bus_type {
72    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
73        #[allow(unreachable_patterns)]
74        f.write_str(match *self {
75            Self::UNKNOWN => "SDL_HID_API_BUS_UNKNOWN",
76            Self::USB => "SDL_HID_API_BUS_USB",
77            Self::BLUETOOTH => "SDL_HID_API_BUS_BLUETOOTH",
78            Self::I2C => "SDL_HID_API_BUS_I2C",
79            Self::SPI => "SDL_HID_API_BUS_SPI",
80
81            _ => return write!(f, "SDL_hid_bus_type({})", self.0),
82        })
83    }
84}
85
86impl SDL_hid_bus_type {
87    /// Unknown bus type
88    pub const UNKNOWN: Self = Self((0x00 as ::core::ffi::c_int));
89    ///  USB bus
90    /// Specifications:
91    /// <https://usb.org/hid>
92    pub const USB: Self = Self((0x01 as ::core::ffi::c_int));
93    ///  Bluetooth or Bluetooth LE bus
94    /// Specifications:
95    /// <https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/>
96    /// <https://www.bluetooth.com/specifications/specs/hid-service-1-0/>
97    /// <https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/>
98    pub const BLUETOOTH: Self = Self((0x02 as ::core::ffi::c_int));
99    ///  I2C bus
100    /// Specifications:
101    /// <https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85)>
102    pub const I2C: Self = Self((0x03 as ::core::ffi::c_int));
103    ///  SPI bus
104    /// Specifications:
105    /// <https://www.microsoft.com/download/details.aspx?id=103325>
106    pub const SPI: Self = Self((0x04 as ::core::ffi::c_int));
107}
108
109/// Unknown bus type
110pub const SDL_HID_API_BUS_UNKNOWN: SDL_hid_bus_type = SDL_hid_bus_type::UNKNOWN;
111///  USB bus
112/// Specifications:
113/// <https://usb.org/hid>
114pub const SDL_HID_API_BUS_USB: SDL_hid_bus_type = SDL_hid_bus_type::USB;
115///  Bluetooth or Bluetooth LE bus
116/// Specifications:
117/// <https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/>
118/// <https://www.bluetooth.com/specifications/specs/hid-service-1-0/>
119/// <https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/>
120pub const SDL_HID_API_BUS_BLUETOOTH: SDL_hid_bus_type = SDL_hid_bus_type::BLUETOOTH;
121///  I2C bus
122/// Specifications:
123/// <https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85)>
124pub const SDL_HID_API_BUS_I2C: SDL_hid_bus_type = SDL_hid_bus_type::I2C;
125///  SPI bus
126/// Specifications:
127/// <https://www.microsoft.com/download/details.aspx?id=103325>
128pub const SDL_HID_API_BUS_SPI: SDL_hid_bus_type = SDL_hid_bus_type::SPI;
129
130#[cfg(feature = "metadata")]
131impl sdl3_sys::metadata::GroupMetadata for SDL_hid_bus_type {
132    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
133        &crate::metadata::hidapi::METADATA_SDL_hid_bus_type;
134}
135
136/// Information about a connected HID device
137///
138/// ## Availability
139/// This struct is available since SDL 3.2.0.
140#[repr(C)]
141#[cfg_attr(feature = "debug-impls", derive(Debug))]
142pub struct SDL_hid_device_info {
143    /// Platform-specific device path
144    pub path: *mut ::core::ffi::c_char,
145    /// Device Vendor ID
146    pub vendor_id: ::core::ffi::c_ushort,
147    /// Device Product ID
148    pub product_id: ::core::ffi::c_ushort,
149    /// Serial Number
150    pub serial_number: *mut crate::ffi::c_wchar_t,
151    ///  Device Release Number in binary-coded decimal,
152    /// also known as Device Version Number
153    pub release_number: ::core::ffi::c_ushort,
154    /// Manufacturer String
155    pub manufacturer_string: *mut crate::ffi::c_wchar_t,
156    /// Product string
157    pub product_string: *mut crate::ffi::c_wchar_t,
158    ///  Usage Page for this Device/Interface
159    /// (Windows/Mac/hidraw only)
160    pub usage_page: ::core::ffi::c_ushort,
161    ///  Usage for this Device/Interface
162    /// (Windows/Mac/hidraw only)
163    pub usage: ::core::ffi::c_ushort,
164    ///  The USB interface which this logical device
165    /// represents.
166    ///
167    /// Valid only if the device is a USB HID device.
168    /// Set to -1 in all other cases.
169    pub interface_number: ::core::ffi::c_int,
170    ///  Additional information about the USB interface.
171    /// Valid on libusb and Android implementations.
172    pub interface_class: ::core::ffi::c_int,
173    pub interface_subclass: ::core::ffi::c_int,
174    pub interface_protocol: ::core::ffi::c_int,
175    /// Underlying bus type
176    pub bus_type: SDL_hid_bus_type,
177    /// Pointer to the next device
178    pub next: *mut SDL_hid_device_info,
179}
180
181impl ::core::default::Default for SDL_hid_device_info {
182    /// Initialize all fields to zero
183    #[inline(always)]
184    fn default() -> Self {
185        unsafe { ::core::mem::MaybeUninit::<Self>::zeroed().assume_init() }
186    }
187}
188
189unsafe extern "C" {
190    /// Initialize the HIDAPI library.
191    ///
192    /// This function initializes the HIDAPI library. Calling it is not strictly
193    /// necessary, as it will be called automatically by [`SDL_hid_enumerate()`] and
194    /// any of the SDL_hid_open_*() functions if it is needed. This function should
195    /// be called at the beginning of execution however, if there is a chance of
196    /// HIDAPI handles being opened by different threads simultaneously.
197    ///
198    /// Each call to this function should have a matching call to [`SDL_hid_exit()`]
199    ///
200    /// ## Return value
201    /// Returns 0 on success or a negative error code on failure; call
202    ///   [`SDL_GetError()`] for more information.
203    ///
204    /// ## Availability
205    /// This function is available since SDL 3.2.0.
206    ///
207    /// ## See also
208    /// - [`SDL_hid_exit`]
209    pub fn SDL_hid_init() -> ::core::ffi::c_int;
210}
211
212unsafe extern "C" {
213    /// Finalize the HIDAPI library.
214    ///
215    /// This function frees all of the static data associated with HIDAPI. It
216    /// should be called at the end of execution to avoid memory leaks.
217    ///
218    /// ## Return value
219    /// Returns 0 on success or a negative error code on failure; call
220    ///   [`SDL_GetError()`] for more information.
221    ///
222    /// ## Availability
223    /// This function is available since SDL 3.2.0.
224    ///
225    /// ## See also
226    /// - [`SDL_hid_init`]
227    pub fn SDL_hid_exit() -> ::core::ffi::c_int;
228}
229
230unsafe extern "C" {
231    /// Check to see if devices may have been added or removed.
232    ///
233    /// Enumerating the HID devices is an expensive operation, so you can call this
234    /// to see if there have been any system device changes since the last call to
235    /// this function. A change in the counter returned doesn't necessarily mean
236    /// that anything has changed, but you can call [`SDL_hid_enumerate()`] to get an
237    /// updated device list.
238    ///
239    /// Calling this function for the first time may cause a thread or other system
240    /// resource to be allocated to track device change notifications.
241    ///
242    /// ## Return value
243    /// Returns a change counter that is incremented with each potential device
244    ///   change, or 0 if device change detection isn't available.
245    ///
246    /// ## Availability
247    /// This function is available since SDL 3.2.0.
248    ///
249    /// ## See also
250    /// - [`SDL_hid_enumerate`]
251    pub fn SDL_hid_device_change_count() -> Uint32;
252}
253
254unsafe extern "C" {
255    /// Enumerate the HID Devices.
256    ///
257    /// This function returns a linked list of all the HID devices attached to the
258    /// system which match vendor_id and product_id. If `vendor_id` is set to 0
259    /// then any vendor matches. If `product_id` is set to 0 then any product
260    /// matches. If `vendor_id` and `product_id` are both set to 0, then all HID
261    /// devices will be returned.
262    ///
263    /// By default SDL will only enumerate controllers, to reduce risk of hanging
264    /// or crashing on bad drivers, but [`SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS`]
265    /// can be set to "0" to enumerate all HID devices.
266    ///
267    /// ## Parameters
268    /// - `vendor_id`: the Vendor ID (VID) of the types of device to open, or 0
269    ///   to match any vendor.
270    /// - `product_id`: the Product ID (PID) of the types of device to open, or 0
271    ///   to match any product.
272    ///
273    /// ## Return value
274    /// Returns a pointer to a linked list of type [`SDL_hid_device_info`], containing
275    ///   information about the HID devices attached to the system, or NULL
276    ///   in the case of failure. Free this linked list by calling
277    ///   [`SDL_hid_free_enumeration()`].
278    ///
279    /// ## Availability
280    /// This function is available since SDL 3.2.0.
281    ///
282    /// ## See also
283    /// - [`SDL_hid_device_change_count`]
284    pub fn SDL_hid_enumerate(
285        vendor_id: ::core::ffi::c_ushort,
286        product_id: ::core::ffi::c_ushort,
287    ) -> *mut SDL_hid_device_info;
288}
289
290unsafe extern "C" {
291    /// Free an enumeration linked list.
292    ///
293    /// This function frees a linked list created by [`SDL_hid_enumerate()`].
294    ///
295    /// ## Parameters
296    /// - `devs`: pointer to a list of struct_device returned from
297    ///   [`SDL_hid_enumerate()`].
298    ///
299    /// ## Availability
300    /// This function is available since SDL 3.2.0.
301    pub fn SDL_hid_free_enumeration(devs: *mut SDL_hid_device_info);
302}
303
304unsafe extern "C" {
305    /// Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally
306    /// a serial number.
307    ///
308    /// If `serial_number` is NULL, the first device with the specified VID and PID
309    /// is opened.
310    ///
311    /// ## Parameters
312    /// - `vendor_id`: the Vendor ID (VID) of the device to open.
313    /// - `product_id`: the Product ID (PID) of the device to open.
314    /// - `serial_number`: the Serial Number of the device to open (Optionally
315    ///   NULL).
316    ///
317    /// ## Return value
318    /// Returns a pointer to a [`SDL_hid_device`] object on success or NULL on
319    ///   failure; call [`SDL_GetError()`] for more information.
320    ///
321    /// ## Availability
322    /// This function is available since SDL 3.2.0.
323    pub fn SDL_hid_open(
324        vendor_id: ::core::ffi::c_ushort,
325        product_id: ::core::ffi::c_ushort,
326        serial_number: *const crate::ffi::c_wchar_t,
327    ) -> *mut SDL_hid_device;
328}
329
330unsafe extern "C" {
331    /// Open a HID device by its path name.
332    ///
333    /// The path name be determined by calling [`SDL_hid_enumerate()`], or a
334    /// platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
335    ///
336    /// ## Parameters
337    /// - `path`: the path name of the device to open.
338    ///
339    /// ## Return value
340    /// Returns a pointer to a [`SDL_hid_device`] object on success or NULL on
341    ///   failure; call [`SDL_GetError()`] for more information.
342    ///
343    /// ## Availability
344    /// This function is available since SDL 3.2.0.
345    pub fn SDL_hid_open_path(path: *const ::core::ffi::c_char) -> *mut SDL_hid_device;
346}
347
348unsafe extern "C" {
349    /// Get the properties associated with an [`SDL_hid_device`].
350    ///
351    /// The following read-only properties are provided by SDL:
352    ///
353    /// - [`SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER`]\: the libusb_device_handle
354    ///   associated with the device, if it was opened using libusb.
355    ///
356    /// ## Parameters
357    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
358    ///
359    /// ## Return value
360    /// Returns a valid property ID on success or 0 on failure; call
361    ///   [`SDL_GetError()`] for more information.
362    ///
363    /// ## Availability
364    /// This function is available since SDL 3.4.0.
365    pub fn SDL_hid_get_properties(dev: *mut SDL_hid_device) -> SDL_PropertiesID;
366}
367
368pub const SDL_PROP_HIDAPI_LIBUSB_DEVICE_HANDLE_POINTER: *const ::core::ffi::c_char =
369    c"SDL.hidapi.libusb.device.handle".as_ptr();
370
371unsafe extern "C" {
372    /// Write an Output report to a HID device.
373    ///
374    /// The first byte of `data` must contain the Report ID. For devices which only
375    /// support a single report, this must be set to 0x0. The remaining bytes
376    /// contain the report data. Since the Report ID is mandatory, calls to
377    /// [`SDL_hid_write()`] will always contain one more byte than the report contains.
378    /// For example, if a hid report is 16 bytes long, 17 bytes must be passed to
379    /// [`SDL_hid_write()`], the Report ID (or 0x0, for devices with a single report),
380    /// followed by the report data (16 bytes). In this example, the length passed
381    /// in would be 17.
382    ///
383    /// [`SDL_hid_write()`] will send the data on the first OUT endpoint, if one
384    /// exists. If it does not, it will send the data through the Control Endpoint
385    /// (Endpoint 0).
386    ///
387    /// ## Parameters
388    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
389    /// - `data`: the data to send, including the report number as the first
390    ///   byte.
391    /// - `length`: the length in bytes of the data to send.
392    ///
393    /// ## Return value
394    /// Returns the actual number of bytes written and -1 on on failure; call
395    ///   [`SDL_GetError()`] for more information.
396    ///
397    /// ## Availability
398    /// This function is available since SDL 3.2.0.
399    pub fn SDL_hid_write(
400        dev: *mut SDL_hid_device,
401        data: *const ::core::ffi::c_uchar,
402        length: ::core::primitive::usize,
403    ) -> ::core::ffi::c_int;
404}
405
406unsafe extern "C" {
407    /// Read an Input report from a HID device with timeout.
408    ///
409    /// Input reports are returned to the host through the INTERRUPT IN endpoint.
410    /// The first byte will contain the Report number if the device uses numbered
411    /// reports.
412    ///
413    /// ## Parameters
414    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
415    /// - `data`: a buffer to put the read data into.
416    /// - `length`: the number of bytes to read. For devices with multiple
417    ///   reports, make sure to read an extra byte for the report
418    ///   number.
419    /// - `milliseconds`: timeout in milliseconds or -1 for blocking wait.
420    ///
421    /// ## Return value
422    /// Returns the actual number of bytes read and -1 on on failure; call
423    ///   [`SDL_GetError()`] for more information. If no packet was available to
424    ///   be read within the timeout period, this function returns 0.
425    ///
426    /// ## Availability
427    /// This function is available since SDL 3.2.0.
428    pub fn SDL_hid_read_timeout(
429        dev: *mut SDL_hid_device,
430        data: *mut ::core::ffi::c_uchar,
431        length: ::core::primitive::usize,
432        milliseconds: ::core::ffi::c_int,
433    ) -> ::core::ffi::c_int;
434}
435
436unsafe extern "C" {
437    /// Read an Input report from a HID device.
438    ///
439    /// Input reports are returned to the host through the INTERRUPT IN endpoint.
440    /// The first byte will contain the Report number if the device uses numbered
441    /// reports.
442    ///
443    /// ## Parameters
444    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
445    /// - `data`: a buffer to put the read data into.
446    /// - `length`: the number of bytes to read. For devices with multiple
447    ///   reports, make sure to read an extra byte for the report
448    ///   number.
449    ///
450    /// ## Return value
451    /// Returns the actual number of bytes read and -1 on failure; call
452    ///   [`SDL_GetError()`] for more information. If no packet was available to
453    ///   be read and the handle is in non-blocking mode, this function
454    ///   returns 0.
455    ///
456    /// ## Availability
457    /// This function is available since SDL 3.2.0.
458    pub fn SDL_hid_read(
459        dev: *mut SDL_hid_device,
460        data: *mut ::core::ffi::c_uchar,
461        length: ::core::primitive::usize,
462    ) -> ::core::ffi::c_int;
463}
464
465unsafe extern "C" {
466    /// Set the device handle to be non-blocking.
467    ///
468    /// In non-blocking mode calls to [`SDL_hid_read()`] will return immediately with a
469    /// value of 0 if there is no data to be read. In blocking mode, [`SDL_hid_read()`]
470    /// will wait (block) until there is data to read before returning.
471    ///
472    /// Nonblocking can be turned on and off at any time.
473    ///
474    /// ## Parameters
475    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
476    /// - `nonblock`: enable or not the nonblocking reads - 1 to enable
477    ///   nonblocking - 0 to disable nonblocking.
478    ///
479    /// ## Return value
480    /// Returns 0 on success or a negative error code on failure; call
481    ///   [`SDL_GetError()`] for more information.
482    ///
483    /// ## Availability
484    /// This function is available since SDL 3.2.0.
485    pub fn SDL_hid_set_nonblocking(
486        dev: *mut SDL_hid_device,
487        nonblock: ::core::ffi::c_int,
488    ) -> ::core::ffi::c_int;
489}
490
491unsafe extern "C" {
492    /// Send a Feature report to the device.
493    ///
494    /// Feature reports are sent over the Control endpoint as a Set_Report
495    /// transfer. The first byte of `data` must contain the Report ID. For devices
496    /// which only support a single report, this must be set to 0x0. The remaining
497    /// bytes contain the report data. Since the Report ID is mandatory, calls to
498    /// [`SDL_hid_send_feature_report()`] will always contain one more byte than the
499    /// report contains. For example, if a hid report is 16 bytes long, 17 bytes
500    /// must be passed to [`SDL_hid_send_feature_report()`]\: the Report ID (or 0x0, for
501    /// devices which do not use numbered reports), followed by the report data (16
502    /// bytes). In this example, the length passed in would be 17.
503    ///
504    /// ## Parameters
505    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
506    /// - `data`: the data to send, including the report number as the first
507    ///   byte.
508    /// - `length`: the length in bytes of the data to send, including the report
509    ///   number.
510    ///
511    /// ## Return value
512    /// Returns the actual number of bytes written and -1 on failure; call
513    ///   [`SDL_GetError()`] for more information.
514    ///
515    /// ## Availability
516    /// This function is available since SDL 3.2.0.
517    pub fn SDL_hid_send_feature_report(
518        dev: *mut SDL_hid_device,
519        data: *const ::core::ffi::c_uchar,
520        length: ::core::primitive::usize,
521    ) -> ::core::ffi::c_int;
522}
523
524unsafe extern "C" {
525    /// Get a feature report from a HID device.
526    ///
527    /// Set the first byte of `data` to the Report ID of the report to be read.
528    /// Make sure to allow space for this extra byte in `data`. Upon return, the
529    /// first byte will still contain the Report ID, and the report data will start
530    /// in data\[1\].
531    ///
532    /// ## Parameters
533    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
534    /// - `data`: a buffer to put the read data into, including the Report ID.
535    ///   Set the first byte of `data` to the Report ID of the report to
536    ///   be read, or set it to zero if your device does not use numbered
537    ///   reports.
538    /// - `length`: the number of bytes to read, including an extra byte for the
539    ///   report ID. The buffer can be longer than the actual report.
540    ///
541    /// ## Return value
542    /// Returns the number of bytes read plus one for the report ID (which is
543    ///   still in the first byte), or -1 on on failure; call [`SDL_GetError()`]
544    ///   for more information.
545    ///
546    /// ## Availability
547    /// This function is available since SDL 3.2.0.
548    pub fn SDL_hid_get_feature_report(
549        dev: *mut SDL_hid_device,
550        data: *mut ::core::ffi::c_uchar,
551        length: ::core::primitive::usize,
552    ) -> ::core::ffi::c_int;
553}
554
555unsafe extern "C" {
556    /// Get an input report from a HID device.
557    ///
558    /// Set the first byte of `data` to the Report ID of the report to be read.
559    /// Make sure to allow space for this extra byte in `data`. Upon return, the
560    /// first byte will still contain the Report ID, and the report data will start
561    /// in data\[1\].
562    ///
563    /// ## Parameters
564    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
565    /// - `data`: a buffer to put the read data into, including the Report ID.
566    ///   Set the first byte of `data` to the Report ID of the report to
567    ///   be read, or set it to zero if your device does not use numbered
568    ///   reports.
569    /// - `length`: the number of bytes to read, including an extra byte for the
570    ///   report ID. The buffer can be longer than the actual report.
571    ///
572    /// ## Return value
573    /// Returns the number of bytes read plus one for the report ID (which is
574    ///   still in the first byte), or -1 on on failure; call [`SDL_GetError()`]
575    ///   for more information.
576    ///
577    /// ## Availability
578    /// This function is available since SDL 3.2.0.
579    pub fn SDL_hid_get_input_report(
580        dev: *mut SDL_hid_device,
581        data: *mut ::core::ffi::c_uchar,
582        length: ::core::primitive::usize,
583    ) -> ::core::ffi::c_int;
584}
585
586unsafe extern "C" {
587    /// Close a HID device.
588    ///
589    /// ## Parameters
590    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
591    ///
592    /// ## Return value
593    /// Returns 0 on success or a negative error code on failure; call
594    ///   [`SDL_GetError()`] for more information.
595    ///
596    /// ## Availability
597    /// This function is available since SDL 3.2.0.
598    pub fn SDL_hid_close(dev: *mut SDL_hid_device) -> ::core::ffi::c_int;
599}
600
601unsafe extern "C" {
602    /// Get The Manufacturer String from a HID device.
603    ///
604    /// ## Parameters
605    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
606    /// - `string`: a wide string buffer to put the data into.
607    /// - `maxlen`: the length of the buffer in multiples of wchar_t.
608    ///
609    /// ## Return value
610    /// Returns 0 on success or a negative error code on failure; call
611    ///   [`SDL_GetError()`] for more information.
612    ///
613    /// ## Availability
614    /// This function is available since SDL 3.2.0.
615    pub fn SDL_hid_get_manufacturer_string(
616        dev: *mut SDL_hid_device,
617        string: *mut crate::ffi::c_wchar_t,
618        maxlen: ::core::primitive::usize,
619    ) -> ::core::ffi::c_int;
620}
621
622unsafe extern "C" {
623    /// Get The Product String from a HID device.
624    ///
625    /// ## Parameters
626    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
627    /// - `string`: a wide string buffer to put the data into.
628    /// - `maxlen`: the length of the buffer in multiples of wchar_t.
629    ///
630    /// ## Return value
631    /// Returns 0 on success or a negative error code on failure; call
632    ///   [`SDL_GetError()`] for more information.
633    ///
634    /// ## Availability
635    /// This function is available since SDL 3.2.0.
636    pub fn SDL_hid_get_product_string(
637        dev: *mut SDL_hid_device,
638        string: *mut crate::ffi::c_wchar_t,
639        maxlen: ::core::primitive::usize,
640    ) -> ::core::ffi::c_int;
641}
642
643unsafe extern "C" {
644    /// Get The Serial Number String from a HID device.
645    ///
646    /// ## Parameters
647    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
648    /// - `string`: a wide string buffer to put the data into.
649    /// - `maxlen`: the length of the buffer in multiples of wchar_t.
650    ///
651    /// ## Return value
652    /// Returns 0 on success or a negative error code on failure; call
653    ///   [`SDL_GetError()`] for more information.
654    ///
655    /// ## Availability
656    /// This function is available since SDL 3.2.0.
657    pub fn SDL_hid_get_serial_number_string(
658        dev: *mut SDL_hid_device,
659        string: *mut crate::ffi::c_wchar_t,
660        maxlen: ::core::primitive::usize,
661    ) -> ::core::ffi::c_int;
662}
663
664unsafe extern "C" {
665    /// Get a string from a HID device, based on its string index.
666    ///
667    /// ## Parameters
668    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
669    /// - `string_index`: the index of the string to get.
670    /// - `string`: a wide string buffer to put the data into.
671    /// - `maxlen`: the length of the buffer in multiples of wchar_t.
672    ///
673    /// ## Return value
674    /// Returns 0 on success or a negative error code on failure; call
675    ///   [`SDL_GetError()`] for more information.
676    ///
677    /// ## Availability
678    /// This function is available since SDL 3.2.0.
679    pub fn SDL_hid_get_indexed_string(
680        dev: *mut SDL_hid_device,
681        string_index: ::core::ffi::c_int,
682        string: *mut crate::ffi::c_wchar_t,
683        maxlen: ::core::primitive::usize,
684    ) -> ::core::ffi::c_int;
685}
686
687unsafe extern "C" {
688    /// Get the device info from a HID device.
689    ///
690    /// ## Parameters
691    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
692    ///
693    /// ## Return value
694    /// Returns a pointer to the [`SDL_hid_device_info`] for this hid_device or NULL
695    ///   on failure; call [`SDL_GetError()`] for more information. This struct
696    ///   is valid until the device is closed with [`SDL_hid_close()`].
697    ///
698    /// ## Availability
699    /// This function is available since SDL 3.2.0.
700    pub fn SDL_hid_get_device_info(dev: *mut SDL_hid_device) -> *mut SDL_hid_device_info;
701}
702
703unsafe extern "C" {
704    /// Get a report descriptor from a HID device.
705    ///
706    /// User has to provide a preallocated buffer where descriptor will be copied
707    /// to. The recommended size for a preallocated buffer is 4096 bytes.
708    ///
709    /// ## Parameters
710    /// - `dev`: a device handle returned from [`SDL_hid_open()`].
711    /// - `buf`: the buffer to copy descriptor into.
712    /// - `buf_size`: the size of the buffer in bytes.
713    ///
714    /// ## Return value
715    /// Returns the number of bytes actually copied or -1 on failure; call
716    ///   [`SDL_GetError()`] for more information.
717    ///
718    /// ## Availability
719    /// This function is available since SDL 3.2.0.
720    pub fn SDL_hid_get_report_descriptor(
721        dev: *mut SDL_hid_device,
722        buf: *mut ::core::ffi::c_uchar,
723        buf_size: ::core::primitive::usize,
724    ) -> ::core::ffi::c_int;
725}
726
727unsafe extern "C" {
728    /// Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers.
729    ///
730    /// ## Parameters
731    /// - `active`: true to start the scan, false to stop the scan.
732    ///
733    /// ## Availability
734    /// This function is available since SDL 3.2.0.
735    pub fn SDL_hid_ble_scan(active: ::core::primitive::bool);
736}
737
738/// An opaque handle representing an open HID device.
739///
740/// ## Availability
741/// This struct is available since SDL 3.2.0.
742#[repr(C)]
743pub struct SDL_hid_device {
744    _opaque: [::core::primitive::u8; 0],
745}
746
747#[cfg(doc)]
748use crate::everything::*;
sdl3_sys/generated/hidapi.rs

sdl3_sys/generated/
hidapi.rs
