Struct buttplug::client::ButtplugClient

pub struct ButtplugClient {
    pub client_name: String,
    pub server_name: Option<String>,
    // some fields omitted
}

Struct used by applications to communicate with a Buttplug Server.

Buttplug Clients provide an API layer on top of the Buttplug Protocol that handles boring things like message creation and pairing, protocol ordering, etc... This allows developers to concentrate on controlling hardware with the API.

Clients serve a few different purposes:

• Managing connections to servers, thru ButtplugClientConnectors
• Emitting events received from the Server
• Holding state related to the server (i.e. what devices are currently connected, etc...)

When a client is first created, it will be able to create an internal loop as a Future, and return it via the [ButtplugClient::get_loop] call. This loop needs to be awaited before awaiting other client calls (like ButtplugClient::connect), otherwise the system will panic.

Fields

client_name: String

The client name. Depending on the connection type and server being used, this name is sometimes shown on the server logs or GUI.

server_name: Option<String>

The server name. Once connected, this contains the name of the server, so we can know what we're connected to.

Methods

impl ButtplugClient

pub fn run<F, T>(name: &str, func: F) -> impl Future where
    F: FnOnce(ButtplugClient) -> T,
    T: Future, 

Runs the client event loop.

Given a client name and a function that takes the client and returns an future (since we can't have async closures yet), this function

• creates a ButtplugClient instance
• passes it to the func argument to create the application Future
• returns a Future with a [join] for the client event loop future and the client application future.

Parameters

• name: Name of the client, see ButtplugClient::client_name
• func: Function that takes the client instance, and returns a future for what the application will be doing with the client instance.

Examples

use buttplug::client::{ButtplugClient, connector::ButtplugEmbeddedClientConnector};

futures::executor::block_on(async {
    ButtplugClient::run("Test Client", |mut client| {
        async move {
            client
                .connect(ButtplugEmbeddedClientConnector::new("Test Server", 0))
                .await;
            println!("Are we connected? {}", client.connected());
        }
    }).await;
});

pub async fn connect<'_>(
    &'_ mut self,
    connector: impl ButtplugClientConnector + 'static
) -> Option<ButtplugClientError>

Connects and runs handshake flow with [crate::server::server::ButtplugServer], either local or remote.

Tries to connect to a server via the given ButtplugClientConnector struct. If connection is successful, also runs the handshake flow and retrieves a list of currently connected devices. These devices will be emitted as ButtplugClientEvent::DeviceAdded events next time ButtplugClient::wait_for_event is run.

Parameters

• connector: A connector of some type that will handle the connection to the server. The core library ships with an "embedded" connector (connector::ButtplugEmbeddedClientConnector) that will run a server in-process with the client, or there are add-on libraries like buttplug-ws-connector that will handle other communication methods like websockets, TCP/UDP, etc...

Returns

An Option which is:

• None if connection succeeded
• Some containing a ButtplugClientError on connection failure.

pub fn connected(&self) -> bool

Returns true if client is currently connected to server.

pub fn disconnect(&mut self) -> Option<ButtplugClientError>

Disconnects from server, if connected.

pub async fn start_scanning<'_>(&'_ mut self) -> Option<ButtplugClientError>

Tells server to start scanning for devices.

pub async fn wait_for_event<'_>(&'_ mut self) -> Vec<ButtplugClientEvent>

Produces a future that will wait for a set of events from the internal loop. Returns once any number of events is received.

This should be called whenever the client isn't doing anything otherwise, so we can respond to unexpected updates from the server, such as devices connections/disconnections, log messages, etc... This is basically what event handlers in C# and JS would deal with, but we're in Rust so this requires us to be slightly more explicit.

Trait Implementations

impl Send for ButtplugClient

impl Sync for ButtplugClient

impl Clone for ButtplugClient

fn clone(&self) -> ButtplugClient

Returns a copy of the value.

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

Performs copy-assignment from source.