Struct TargetHandle 

pub struct TargetHandle<T> { /* private fields */ }

An opaque handle to a plugged-in virtual controller.

This handle is returned when a new target is successfully plugged into the bus. It is used to identify the target for subsequent operations like updating its state, listening for notifications, or removing it.

This handle uses reference counting (Arc). Cloning it is cheap and creates another handle to the same virtual controller. The controller is only unplugged from the bus when the last handle is dropped.

Implementations

impl<T> TargetHandle<T>

pub fn is_attached(&self) -> Result<bool, ClientError>

Checks if the virtual controller is still attached to the bus.

This can return false if the controller was manually unplugged or if the client was dropped.

pub fn unplug(&self) -> Result<(), ClientError>

Explicitly unplugs the virtual controller from the bus.

After calling this, any further operations on this TargetHandle (and any of its clones) will fail. The controller is also automatically unplugged when the last TargetHandle is dropped.

impl TargetHandle<Xbox360>

pub fn get_user_index(&self) -> Result<u32, ClientError>

Gets the user index of a virtual Xbox 360 controller.

It doesn’t seem like this method is reliable for getting the dynamic player index assigned by a game. It often returns 0 even after an index has been assigned.

To reliably get the player index, use TargetHandle<X360>::register_notification and check the led_number field of the received X360Notification.

pub fn wait_for_ready(&self) -> Result<(), ClientError>

Blocks until the virtual controller is fully enumerated and ready to receive updates.

It is recommended to call this after plugging in a new controller if you want to immediately send a report to the controller.

Example

use vigem_rust::{Client, X360Report};
let client = Client::connect().unwrap();
let x360 = client.new_x360_target().plugin().unwrap();

// Wait for the controller to be ready
x360.wait_for_ready().unwrap();

// Now it's safe to send updates
x360.update(&X360Report::default()).unwrap();

Examples found in repository

examples/x360.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

pub fn register_notification( &self, ) -> Result<Receiver<Result<X360Notification, BusError>>, ClientError>

Registers to receive notifications for this Xbox 360 target.

This returns a Receiver that will yield X360Notifications from the bus, which contain information like rumble data and the controller’s player LED index.

Important

Calling this function spawns a dedicated background thread that lives as long as the Receiver does.

Example

let receiver = x360.register_notification().unwrap();

// In a loop or another thread:
if let Ok(Ok(notification)) = receiver.try_recv() {
    println!("Player LED is now {}", notification.led_number);
}

Examples found in repository

examples/x360.rs (line 23)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

pub fn update(&self, report: &X360Report) -> Result<(), ClientError>

Submits an input state report for this Xbox 360 target.

This is the primary method for sending controller inputs to the system. The provided X360Report contains the state of all buttons, triggers, and thumbsticks.

Warning

Calling this method immediately after plugging in the target will likely fail, as the system needs time to enumerate the device.

To reliably send updates right after creation, you must first call [wait_for_ready()].

Example

let mut report = X360Report::default();
report.buttons = X360Button::A | X360Button::START;
report.thumb_lx = 16384; // Move left stick right

x360.update(&report)?;

Examples found in repository

examples/x360.rs (line 56)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let x360 = client.new_x360_target().plugin()?;
    println!("Plugged in virtual Xbox 360 controller");

    // Wait for the controller to be ready
    // The virtual controller needs a moment to be recognized
    // by the system before it can receive updates.
    x360.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = x360.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!("  - LED Number/Player Index: {}", notification.led_number);
        }
    });

    // Here, we'll send reports to the controller to simulate input.
    let mut report = X360Report::default();
    let mut angle: f64 = 0.0;
    let mut step = 0;

    loop {
        // Animate the left thumbstick in a circle
        angle += 0.1;
        let (sin, cos) = angle.sin_cos();
        report.thumb_lx = (sin * 32767.0) as i16;
        report.thumb_ly = (cos * 32767.0) as i16;

        // Alternate pressing A and B buttons
        if step % 2 == 0 {
            report.buttons = X360Button::A;
        } else {
            report.buttons = X360Button::B;
        }

        // Send the updated report to the controller
        x360.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        step += 1;
    }
}

impl TargetHandle<DualShock4>

pub fn wait_for_ready(&self) -> Result<(), ClientError>

Blocks until the virtual controller is fully enumerated and ready to receive updates.

It is recommended to call this after plugging in a new controller if you want to immediately send a report to the controller.

Example

use vigem_rust::{Client, Ds4Report};
let client = Client::connect().unwrap();
let ds4 = client.new_ds4_target().plugin().unwrap();

// Wait for the controller to be ready
ds4.wait_for_ready().unwrap();

// Now it's safe to send updates
ds4.update(&Ds4Report::default()).unwrap();

Examples found in repository

examples/ds4.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

examples/ds4_ex.rs (line 17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}

pub fn register_notification( &self, ) -> Result<Receiver<Result<Ds4Notification, BusError>>, ClientError>

Registers to receive notifications for this DualShock 4 target.

This returns a Receiver that will yield Ds4Notifications from the bus, which contain information like rumble data and lightbar color commands.

Important

Calling this function spawns a dedicated background thread that lives as long as the Receiver does.

Example

let receiver = ds4.register_notification().unwrap();

// In a loop or another thread:
if let Ok(Ok(notification)) = receiver.try_recv() {
    println!("Lightbar color changed to: {:?}", notification.lightbar);
}

Examples found in repository

examples/ds4.rs (line 21)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

examples/ds4_ex.rs (line 20)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}

pub fn register_notification_raw_buffer( &self, ) -> Result<Receiver<Result<Ds4OutputBuffer, BusError>>, ClientError>

Subscribes to raw 64-byte output buffers for a DualShock 4 target.

Warning

Unlike the register_notification method, this one gets the raw output buffer of all connected Dualshock 4 virtual controllers via a single thread (centralized system.)

Important

Calling this function spawns a dedicated background thread that lives as long as the Receiver does.

This is an advanced function for applications that need to parse the raw output report from the bus, which may contain more detailed information than the standard Ds4Notification.

pub fn update(&self, report: &Ds4Report) -> Result<(), ClientError>

Submits a standard input state report for this DualShock 4 target.

This method sends a Ds4Report, which covers the state of all buttons, D-Pad, triggers, and thumbsticks. For advanced features like touchpad or motion sensor data, use update_ex instead.

Warning

Calling this method immediately after plugging in the target will likely fail, as the system needs time to enumerate the device.

To reliably send updates right after creation, you must first call [wait_for_ready()].

Example

let mut report = Ds4Report::default();
report.buttons = Ds4Button::CROSS.bits();
report.set_dpad(Ds4Dpad::South);
report.trigger_r = 255;

ds4.update(&report)?;

Examples found in repository

examples/ds4.rs (line 59)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    // Set up a notification listener in a separate thread
    // This allows us to react to feedback from the system, like rumble or LED changes.
    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Here, we'll send reports to the controller to simulate input.

    let mut report = Ds4Report::default();

    // Hold the right D-pad button
    report.set_dpad(Ds4Dpad::East);
    // Hold the Cross button
    report.buttons |= Ds4Button::CROSS.bits();
    // Fully press the right trigger
    report.trigger_r = 255;

    let mut angle: f64 = 0.0;

    loop {
        // Animate the right thumbstick in a circle
        let (sin, cos) = angle.sin_cos();

        // DS4 thumbsticks are 0-255, with 128 as the center.
        report.thumb_rx = (128.0 + sin * 127.0) as u8;
        report.thumb_ry = (128.0 + cos * 127.0) as u8;

        // Send the updated report to the controller
        ds4.update(&report)?;

        thread::sleep(Duration::from_millis(16));
        angle += 0.05;
    }
}

pub fn update_ex(&self, report: &Ds4ReportEx) -> Result<(), ClientError>

Submits an extended input state report for this DualShock 4 target.

This method is used for advanced scenarios that require simulating motion controls (gyroscope/accelerometer) and detailed touchpad activity. It sends a Ds4ReportEx, which is a superset of the standard Ds4Report.

Warning

Calling this method immediately after plugging in the target will likely fail, as the system needs time to enumerate the device.

To reliably send updates right after creation, you must first call [wait_for_ready()].

Example

let mut report_ex = Ds4ReportEx::default();


// Set gyro data
report_ex.gyro_x = 12345;

// The standard report fields are also available
report_ex.thumb_lx = 200;

ds4.update_ex(&report_ex)?;

Examples found in repository

examples/ds4_ex.rs (line 67)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the ViGEm bus
    // This can fail if the ViGEm bus driver is not installed.
    let client = Client::connect()?;
    println!("Connected to ViGEm bus");

    // Create and plugin the virtual controller
    let ds4 = client.new_ds4_target().plugin()?;
    println!("Plugged in virtual DualShock 4 controller");

    // Wait for the controller to be ready
    ds4.wait_for_ready()?;
    println!("Controller is ready. You can test it at https://hardwaretester.com/gamepad");

    let notifications = ds4.register_notification()?;
    thread::spawn(move || {
        println!("Notification Thread Started. Waiting for feedback from the host...");
        while let Ok(Ok(notification)) = notifications.recv() {
            println!("Notification Thread Received feedback:");
            println!(
                "  - Rumble: Large Motor = {}, Small Motor = {}",
                notification.large_motor, notification.small_motor
            );
            println!(
                "  - Lightbar Color: R={}, G={}, B={}",
                notification.lightbar.red, notification.lightbar.green, notification.lightbar.blue
            );
        }
    });

    // Main input loop for extended reports
    let mut report_ex = Ds4ReportEx::default();

    // Variables to animate the touch point
    let mut packet_counter: u8 = 0;
    let mut touch_x: i32 = 0;
    let mut direction: i32 = 12;

    loop {
        // Move the touch point back and forth horizontally.
        if touch_x <= 0 {
            direction = 12;
        }
        if touch_x >= 1919 {
            direction = -12;
        }
        touch_x += direction;

        report_ex.touch_packets_n = 1;

        // Get a mut reference to the touch data struct inside the report.
        let touch = &mut report_ex.current_touch;

        // This counter should increment for each new packet of touch data (not sure if necessary for functionality).
        touch.packet_counter = packet_counter;
        packet_counter = packet_counter.wrapping_add(1);

        touch.set_touch_1(true, 1, touch_x as u16, 471); // Finger 1 is down, centered vertically.
        touch.set_touch_2(false, 0, 0, 0); // Finger 2 is up (inactive).

        // Send the updated report to the controller
        ds4.update_ex(&report_ex)?;

        thread::sleep(Duration::from_millis(16));
    }
}

Trait Implementations

impl<T: Clone> Clone for TargetHandle<T>

fn clone(&self) -> TargetHandle<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.