Struct mpd_client::Client

pub struct Client { /* fields omitted */ }

A client connected to an MPD instance.

You can use this to send commands to the MPD server, and wait for the response. Cloning the Client will reuse the connection, similar to how a channel sender works.

Connection management

Dropping the last clone of a particular Client will close the connection automatically.

Example

use mpd_client::{commands::Play, Client};

async fn connect_to_mpd() -> Result<(), Box<dyn std::error::Error>> {
    let (client, _state_changes) = Client::connect_to("localhost:6600").await?;

    client.command(Play::current()).await?;
    Ok(())
}

Implementations

impl Client

pub async fn connect_to<A: ToSocketAddrs + Debug>(address: A) -> ConnectResult

Connect to an MPD server at the given TCP address.

This requires the dns Tokio feature to resolve domain names.

Panics

This panics for the same reasons as Client::connect.

Errors

This returns errors in the same conditions as Client::connect, and if connecting to the given TCP address fails for any reason.

pub async fn connect_unix<P: AsRef<Path>>(path: P) -> ConnectResult

Connect to an MPD server using the Unix socket at the given path.

This is only available on Unix.

Panics

This panics for the same reasons as Client::connect.

Errors

This returns errors in the same conditions as Client::connect, and if connecting to the Unix socket at the given address fails for any reason.

pub async fn connect<C>(connection: C) -> ConnectResult where
    C: AsyncRead + AsyncWrite + Send + Unpin + 'static, 

Connect to the MPD server using the given connection.

Since this method is generic over the connection type it can be used to connect to either a TCP or Unix socket dynamically or e.g. use a proxy.

See also the Client::connect_to and Client::connect_unix shorthands for the common connection case.

Panics

Since this spawns a task internally, this will panic when called outside a Tokio runtime.

Errors

This will return an error if sending the initial commands over the given transport fails.

pub async fn command<C>(&self, cmd: C) -> Result<C::Response, CommandError> where
    C: Command, 

Send a command.

This will automatically parse the response to a proper type.

Errors

This returns errors in the same conditions as Client::raw_command, and additionally if the response fails to convert to the expected type.

pub async fn command_list<L>(
    &self,
    list: L
) -> Result<L::Response, CommandError> where
    L: CommandList, 

Send the given command list, and return the (typed) responses.

Errors

This returns errors in the same conditions as Client::raw_command_list, and additionally if the response type conversion fails.

pub async fn password(
    &self,
    password: Option<String>
) -> Result<(), CommandError>

Send the connection password, if necessary.

If the MPD instance the Client is connected to is protected by a password, sending commands may result in “Permission denied” errors prior to sending the correct password.

This will not send anything if None is passed.

Errors

Sending an incorrect password will result in a CommandError::ErrorResponse, any other errors are returned in the same conditions as Client::raw_command.

pub async fn raw_command(
    &self,
    command: RawCommand
) -> Result<Frame, CommandError>

Send the given command, and return the response to it.

Errors

This will return an error if the connection to MPD is closed (cleanly) or a protocol error occurs (including IO errors), or if the command results in an MPD error.

pub async fn raw_command_list(
    &self,
    commands: RawCommandList
) -> Result<Vec<Frame>, CommandError>

Send the given command list, and return the raw response frames to the contained commands.

Errors

Errors will be returned in the same conditions as with Client::raw_command, but if any of the commands in the list return an error condition, the entire list will be treated as an error.

You may recover possible succesful fields in a response from the error.

pub fn protocol_version(&self) -> &str

Get the protocol version the underlying connection is using.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.