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

sdl3_sys/generated/
hidapi.rs
