Struct evdev::Device

pub struct Device { /* private fields */ }

Available on Unix only.

A physical or virtual device supported by evdev.

Each device corresponds to a path typically found in /dev/input, and supports access via one or more “types”. For example, an optical mouse has buttons that are represented by “keys”, and reflects changes in its position via “relative axis” reports.

This type specifically is a wrapper over RawDevice,that synchronizes with the kernel’s state when events are dropped.

If fetch_events() isn’t called often enough and the kernel drops events from its internal buffer, synthetic events will be injected into the iterator returned by fetch_events() and Device::cached_state() will be kept up to date when fetch_events() is called.

Implementations

impl Device

pub fn open(path: impl AsRef<Path>) -> Result<Device>

Opens a device, given its system path.

Paths are typically something like /dev/input/event0.

pub fn cached_state(&self) -> &DeviceState

Returns the synchronization engine’s current understanding (cache) of the device state.

Note that this represents the internal cache of the synchronization engine as of the last entry that was pulled out. The advantage to calling this instead of invoking get_key_state and the like directly is speed: because reading this cache doesn’t require any syscalls it’s easy to do inside a tight loop. The downside is that if the stream is not being driven quickly, this can very quickly get desynchronized from the kernel and provide inaccurate data.

pub fn name(&self) -> Option<&str>

Returns the device’s name as read from the kernel.

pub fn physical_path(&self) -> Option<&str>

Returns the device’s physical location, either as set by the caller or as read from the kernel.

pub fn unique_name(&self) -> Option<&str>

Returns the user-defined “unique name” of the device, if one has been set.

pub fn input_id(&self) -> InputId

Returns a struct containing bustype, vendor, product, and version identifiers

pub fn get_auto_repeat(&self) -> Option<AutoRepeat>

Returns a struct containing the delay and period for auto repeat

pub fn update_auto_repeat(&mut self, repeat: &AutoRepeat) -> Result<()>

Update the delay and period for autorepeat

pub fn get_scancode_by_keycode(&self, keycode: Key) -> Result<Vec<u8>>

Retrieve the scancode for a keycode, if any

pub fn get_scancode_by_index(&self, index: u16) -> Result<(u32, Vec<u8>)>

Retrieve the keycode and scancode by index, starting at 0

pub fn update_scancode(&self, keycode: Key, scancode: &[u8]) -> Result<Key>

Update a scancode. The return value is the previous keycode

pub fn update_scancode_by_index(
    &self,
    index: u16,
    keycode: Key,
    scancode: &[u8]
) -> Result<u32>

Update a scancode by index. The return value is the previous keycode

pub fn properties(&self) -> &AttributeSetRef<PropType>

Returns the set of supported “properties” for the device (see INPUT_PROP_* in kernel headers)

pub fn driver_version(&self) -> (u8, u8, u8)

Returns a tuple of the driver version containing major, minor, rev

pub fn supported_events(&self) -> &AttributeSetRef<EventType>

Returns a set of the event types supported by this device (Key, Switch, etc)

If you’re interested in the individual keys or switches supported, it’s probably easier to just call the appropriate supported_* function instead.

pub fn supported_keys(&self) -> Option<&AttributeSetRef<Key>>

Returns the set of supported keys reported by the device.

For keyboards, this is the set of all possible keycodes the keyboard may emit. Controllers, mice, and other peripherals may also report buttons as keys.

Examples

use evdev::{Device, Key};
let device = Device::open("/dev/input/event0")?;

// Does this device have an ENTER key?
let supported = device.supported_keys().map_or(false, |keys| keys.contains(Key::KEY_ENTER));

pub fn supported_relative_axes(
    &self
) -> Option<&AttributeSetRef<RelativeAxisType>>

Returns the set of supported “relative axes” reported by the device.

Standard mice will generally report REL_X and REL_Y along with wheel if supported.

Examples

use evdev::{Device, RelativeAxisType};
let device = Device::open("/dev/input/event0")?;

// Does the device have a scroll wheel?
let supported = device
    .supported_relative_axes()
    .map_or(false, |axes| axes.contains(RelativeAxisType::REL_WHEEL));

pub fn supported_absolute_axes(
    &self
) -> Option<&AttributeSetRef<AbsoluteAxisType>>

Returns the set of supported “absolute axes” reported by the device.

These are most typically supported by joysticks and touchpads.

Examples

use evdev::{Device, AbsoluteAxisType};
let device = Device::open("/dev/input/event0")?;

// Does the device have an absolute X axis?
let supported = device
    .supported_absolute_axes()
    .map_or(false, |axes| axes.contains(AbsoluteAxisType::ABS_X));

pub fn supported_switches(&self) -> Option<&AttributeSetRef<SwitchType>>

Returns the set of supported switches reported by the device.

These are typically used for things like software switches on laptop lids (which the system reacts to by suspending or locking), or virtual switches to indicate whether a headphone jack is plugged in (used to disable external speakers).

Examples

use evdev::{Device, SwitchType};
let device = Device::open("/dev/input/event0")?;

// Does the device report a laptop lid switch?
let supported = device
    .supported_switches()
    .map_or(false, |axes| axes.contains(SwitchType::SW_LID));

pub fn supported_leds(&self) -> Option<&AttributeSetRef<LedType>>

Returns a set of supported LEDs on the device.

Most commonly these are state indicator lights for things like Scroll Lock, but they can also be found in cameras and other devices.

pub fn misc_properties(&self) -> Option<&AttributeSetRef<MiscType>>

Returns a set of supported “miscellaneous” capabilities.

Aside from vendor-specific key scancodes, most of these are uncommon.

pub fn supported_ff(&self) -> Option<&AttributeSetRef<FFEffectType>>

Returns the set of supported force feedback effects supported by a device.

pub fn max_ff_effects(&self) -> usize

Returns the maximum number of force feedback effects that can be played simultaneously.

pub fn supported_sounds(&self) -> Option<&AttributeSetRef<SoundType>>

Returns the set of supported simple sounds supported by a device.

You can use these to make really annoying beep sounds come from an internal self-test speaker, for instance.

pub fn get_key_state(&self) -> Result<AttributeSet<Key>>

Retrieve the current keypress state directly via kernel syscall.

pub fn get_abs_state(&self) -> Result<[input_absinfo; 64]>

Retrieve the current absolute axis state directly via kernel syscall.

pub fn get_switch_state(&self) -> Result<AttributeSet<SwitchType>>

Retrieve the current switch state directly via kernel syscall.

pub fn get_led_state(&self) -> Result<AttributeSet<LedType>>

Retrieve the current LED state directly via kernel syscall.

pub fn fetch_events(&mut self) -> Result<FetchEventsSynced<'_>>

Fetches and returns events from the kernel ring buffer, doing synchronization on SYN_DROPPED.

By default this will block until events are available. Typically, users will want to call this in a tight loop within a thread. Will insert “fake” events.

pub fn into_event_stream(self) -> Result<EventStream>

Available on crate feature tokio only.

pub fn grab(&mut self) -> Result<()>

Grab the device through a kernel syscall.

This prevents other clients (including kernel-internal ones such as rfkill) from receiving events from this device.

pub fn ungrab(&mut self) -> Result<()>

Ungrab the device through a kernel syscall.

pub fn send_events(&mut self, events: &[InputEvent]) -> Result<()>

Send an event to the device.

Events that are typically sent to devices are EventType::LED (turn device LEDs on and off), EventType::SOUND (play a sound on the device) and EventType::FORCEFEEDBACK (play force feedback effects on the device, i.e. rumble).

pub fn upload_ff_effect(&mut self, data: FFEffectData) -> Result<FFEffect>

Uploads a force feedback effect to the device.

pub fn set_ff_gain(&mut self, value: u16) -> Result<()>

Sets the force feedback gain, i.e. how strong the force feedback effects should be for the device. A gain of 0 means no gain, whereas u16::MAX is the maximum gain.

pub fn set_ff_autocenter(&mut self, value: u16) -> Result<()>

Enables or disables autocenter for the force feedback device.

Trait Implementations

impl AsRawFd for Device

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Display for Device

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.