Struct tsclientlib::Connection

pub struct Connection { /* fields omitted */ }

The Connection is the main interaction point with this library.

It represents a connection to a TeamSpeak server. It will reconnect automatically when the connection times out. It will not reconnect which the client is kicked or banned from the server.

Implementations

impl Connection

The main type of this crate, which represents a connection to a server.

After creating a connection with Connection::new, the main way to interact with it is get_state. It stores currently visible clients and channels on the server. The setter methods e.g. for the nickname or channel create a command that can be send to the server. The send method returns a handle which can then be used to check if the action succeeded or not.

The second way of interaction is polling with events(), which returns a stream of StreamItems.

The connection will not do anything unless the event stream is polled. Even sending packets will only happen while polling. Make sure to always wait for events when awaiting other futures.

Examples

This will open a connection to the TeamSpeak server at localhost.

use futures::prelude::*;
use tsclientlib::{Connection, StreamItem};

#[tokio::main]
async fn main() {
    let mut con = Connection::build("localhost").connect().unwrap();
    // Wait until connected
    con.events()
        // We are connected when we receive the first BookEvents
        .try_filter(|e| future::ready(matches!(e, StreamItem::BookEvents(_))))
        .next()
        .await
        .unwrap();
}

pub fn build<A: Into<ServerAddress>>(address: A) -> ConnectOptions

Start creating the configuration of a new connection.

Arguments

The address of the server has to be supplied. The address can be a SocketAddr, a string or directly a ServerAddress. A string will automatically be resolved from all formats supported by TeamSpeak. For details, see resolver::resolve.

Examples

This will open a connection to the TeamSpeak server at localhost.

    let mut con = Connection::build("localhost").connect().unwrap();
    // Wait until connected
    con.events()
        // We are connected when we receive the first BookEvents
        .try_filter(|e| future::ready(matches!(e, StreamItem::BookEvents(_))))
        .next()
        .await
        .unwrap();

pub fn new(options: ConnectOptions) -> Result<Self, Error>

👎 Deprecated since 0.2.0:

ConnectOptions::connect should be used instead

Create a connection

This function opens a new connection to a server. The returned future resolves, when the connection is established successfully.

Settings like nickname of the user can be set using the ConnectOptions parameter.

Examples

This will open a connection to the TeamSpeak server at localhost.

    let mut con = Connection::new(ConnectOptions::new("localhost")).unwrap();
    // Wait until connected
    con.events()
        // We are connected when we receive the first BookEvents
        .try_filter(|e| future::ready(matches!(e, StreamItem::BookEvents(_))))
        .next()
        .await
        .unwrap();

pub fn get_options(&self) -> &ConnectOptions

Get the options which were used to create this connection.

The identity of the options is updated while connecting if the identity level needs to be improved.

pub fn events(&mut self) -> impl Stream<Item = Result<StreamItem, Error>> + '_

Get a stream of events. The event stream needs to be polled, otherwise nothing will happen in a connection, not even sending packets will work.

The returned stream can be dropped and recreated if needed.

pub fn cancel_identity_level_increase(&mut self)

Cancels the computation to increase the identity level.

This function initiates the cancellation and immediately returns. It does not wait until the background thread quits.

Does nothing if the identity level is currently not increased.

pub fn get_tsproto_client(&self) -> Result<&Client, Error>

Get access to the raw connection.

Fails if the connection is currently not connected to the server.

pub fn get_tsproto_client_mut(&mut self) -> Result<&mut Client, Error>

Get access to the raw connection.

Fails if the connection is currently not connected to the server.

pub fn get_server_key(&self) -> Result<EccKeyPubP256, Error>

Returns the public key of the server, fails if disconnected.

pub fn get_state(&self) -> Result<&Connection, Error>

Get the current state of clients and channels of this connection.

Fails if the connection is currently not connected to the server.

pub fn disconnect(&mut self, options: DisconnectOptions) -> Result<(), Error>

Disconnect from the server.

Arguments

• options: Either None or DisconnectOptions.

Examples

Use default options:

let mut con = Connection::build("localhost").connect().unwrap();
// Wait until connected
con.events()
    // We are connected when we receive the first BookEvents
    .try_filter(|e| future::ready(matches!(e, StreamItem::BookEvents(_))))
    .next()
    .await
    .unwrap();

// Disconnect
con.disconnect(DisconnectOptions::new()).unwrap();
con.events().for_each(|_| future::ready(())).await;

Specify a reason and a quit message:

let mut con = Connection::build("localhost").connect().unwrap();
// Wait until connected
con.events()
    // We are connected when we receive the first BookEvents
    .try_filter(|e| future::ready(matches!(e, StreamItem::BookEvents(_))))
    .next()
    .await
    .unwrap();

// Disconnect
let options = DisconnectOptions::new()
    .reason(Reason::Clientdisconnect)
    .message("Away for a while");
con.disconnect(options).unwrap();
con.events().for_each(|_| future::ready(())).await;

pub fn send_audio(&mut self, packet: OutPacket) -> Result<(), Error>

Send audio to the server.

This function does only accept Voice and VoiceWhisper packets. Commands should be send with command.send(&mut connection) or command.send_with_result(&mut connection).

Examples

use tsproto_packets::packets::{AudioData, CodecType, OutAudio};
let codec = CodecType::OpusVoice;
// Send an empty packet to signal audio end
let packet = OutAudio::new(&AudioData::C2S { id: 0, codec, data: &[] });
con.send_audio(packet).unwrap();

pub fn download_file(
    &mut self,
    channel_id: ChannelId,
    path: &str,
    channel_password: Option<&str>,
    seek_position: Option<u64>
) -> Result<FiletransferHandle, Error>

Download a file from a channel of the connected TeamSpeak server.

Returns the size of the file and a tcp stream of the requested file.

Examples

Download an icon.

let handle_future = con.download_file(ChannelId(0), &format!("/icon_{}", id), None, None);

pub fn upload_file(
    &mut self,
    channel_id: ChannelId,
    path: &str,
    channel_password: Option<&str>,
    size: u64,
    overwrite: bool,
    resume: bool
) -> Result<FiletransferHandle, Error>

Upload a file to a channel of the connected TeamSpeak server.

Returns the size of the part which is already uploaded (when resume is specified) and a tcp stream where the requested file should be uploaded.

Examples

Upload an avatar.

let handle_future = con.upload_file(ChannelId(0), "/avatar", None, size, true, false);

pub fn get_network_stats(&self) -> Result<&ConnectionStats, Error>

Get statistics about the network connection.

Example

Get the fraction of packets that are currently lost.

let loss: f32 = con.get_network_stats().unwrap().get_packetloss();

Error

Returns an error if currently not connected.

pub fn can_send_audio(&self) -> bool

If this client can send audio or is muted.

If the client is muted, the server will drop any sent audio packets. A client counts as muted if input or output is muted, he is marked away or the talk power is less than the needed talk power in the current channel. Temporary disconnects also count as mutes.

If this changes, the AudioEvent::CanSendAudio event is emitted.

pub fn can_receive_audio(&self) -> bool

If this client can receive audio or the output is muted.

This will return false if the client is currently not connected to the server. Audio packets might still be received but should not be played.

If this changes, the AudioEvent::CanReceiveAudio event is emitted.

Trait Implementations

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl From<Connection> for SyncConnection

fn from(con: Connection) -> Self

Performs the conversion.