Struct buttplug::client::ButtplugClient

pub struct ButtplugClient {
    pub client_name: String,
    pub server_name: 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 [ButtplugClientConnector]s
• Emitting events received from the Server
• Holding state related to the server (i.e. what devices are currently connected, etc...)

Clients are created by the [ButtplugClient::run()] method, which also handles spinning up the event loop and connecting the client to the server. Closures passed to the run() method can access and use the Client object.

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: String

The server name that we're current connected to.

Implementations

impl ButtplugClient

pub fn connect<ConnectorType>(
    name: &str,
    connector: ConnectorType
) -> BoxFuture<'static, Result<(Self, impl StreamExt<Item = ButtplugClientEvent>), ButtplugClientError>> where
    ConnectorType: ButtplugConnector<ButtplugCurrentSpecClientMessage, ButtplugCurrentSpecServerMessage> + 'static, 

pub fn connect_in_process(
    name: &str,
    max_ping_time: u64
) -> impl Future<Output = Result<(Self, impl StreamExt<Item = ButtplugClientEvent>), ButtplugClientError>>

Convenience function for creating in-process connectors.

Creates a ButtplugClient event loop, with an in-process connector with all device managers that ship with the library and work on the current platform added to it already. Takes a maximum ping time to build the server with, other parameters match run().

When To Use This Instead of run()

If you just want to build a quick example and save yourself a few use statements and setup, this will get you going. For anything production, we recommend using run() as you will have more control over what happens. This method may gain/lose device comm managers at any time.

The Device I Want To Use Doesn't Show Up

If you are trying to use this method to create your client, and do not see the devices you want, there are a couple of things to check:

• Are you on a platform that the device communication manager supports? For instance, we only support XInput on windows.
• Did the developers add a new Device CommunicationManager type and forget to add it to this method? It's more likely than you think! File a bug.

Errors

If the library was compiled without any device managers, the ButtplugClient will have nothing to do. This is considered a catastrophic failure and the library will return an error.

If the library is using outside device managers, it is recommended to build your own connector, add your device manager to those, and use the run() method to pass it in.

pub fn connected(&self) -> bool

Returns true if client is currently connected.

pub fn disconnect(&self) -> BoxFuture<'static, Result<(), ButtplugClientError>>

Disconnects from server, if connected.

Returns Err(ButtplugClientError) if disconnection fails. It can be assumed that even on failure, the client will be disconnected.

pub fn start_scanning(
    &self
) -> BoxFuture<'static, Result<(), ButtplugClientError>>

Tells server to start scanning for devices.

Returns Err(ButtplugClientError) if request fails due to issues with DeviceManagers on the server, disconnection, etc.

pub fn stop_scanning(
    &self
) -> BoxFuture<'static, Result<(), ButtplugClientError>>

Tells server to stop scanning for devices.

Returns Err(ButtplugClientError) if request fails due to issues with DeviceManagers on the server, disconnection, etc.

pub fn devices(&self) -> Vec<ButtplugClientDevice>

Retreives a list of currently connected devices.

As the device list is maintained in the event loop structure, retreiving the list requires an asynchronous call to retreive the list from the task.

Trait Implementations

impl Send for ButtplugClient

impl Sync for ButtplugClient