Struct websocket::client::sync::Client

pub struct Client<S> where
    S: Stream,  { /* fields omitted */ }

Represents a WebSocket client, which can send and receive messages/data frames.

The client just wraps around a Stream (which is something that can be read from and written to) and handles the websocket protocol. TCP or SSL over TCP is common, but any stream can be used.

A Client can also be split into a Reader and a Writer which can then be moved to different threads, often using a send loop and receiver loop concurrently, as shown in the client example in examples/client.rs. This is only possible for streams that implement the Splittable trait, which currently is only TCP streams. (it is unsafe to duplicate an SSL stream)

Connecting to a Server

extern crate websocket;

use websocket::{ClientBuilder, Message};

let mut client = ClientBuilder::new("ws://127.0.0.1:1234")
    .unwrap()
    .connect_insecure()
    .unwrap();

let message = Message::text("Hello, World!");
client.send_message(&message).unwrap(); // Send message

Methods

impl Client<TcpStream>

pub fn shutdown_sender(&self) -> IoResult<()>

Shuts down the sending half of the client connection, will cause all pending and future IO to return immediately with an appropriate value.

pub fn shutdown_receiver(&self) -> IoResult<()>

Shuts down the receiving half of the client connection, will cause all pending and future IO to return immediately with an appropriate value.

impl<S> Client<S> where     S: AsTcpStream + Stream,

pub fn shutdown(&self) -> IoResult<()>

Shuts down the client connection, will cause all pending and future IO to return immediately with an appropriate value.

pub fn peer_addr(&self) -> IoResult<SocketAddr>

See TcpStream::peer_addr (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.peer_addr).

pub fn local_addr(&self) -> IoResult<SocketAddr>

See TcpStream::local_addr (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.local_addr).

pub fn set_nodelay(&mut self, nodelay: bool) -> IoResult<()>

See TcpStream::set_nodelay (https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.set_nodelay).

pub fn set_nonblocking(&self, nonblocking: bool) -> IoResult<()>

Changes whether the stream is in nonblocking mode.

impl<S> Client<S> where     S: Stream,

pub fn send_dataframe<D>(&mut self, dataframe: &D) -> WebSocketResult<()> where     D: DataFrameable,

Sends a single data frame to the remote endpoint.

pub fn send_message<M>(&mut self, message: &M) -> WebSocketResult<()> where     M: Message,

Sends a single message to the remote endpoint.

pub fn recv_dataframe(&mut self) -> WebSocketResult<DataFrame>

Reads a single data frame from the remote endpoint.

Important traits for DataFrameIterator<'a, Recv, R>

impl<'a, Recv, R> Iterator for DataFrameIterator<'a, Recv, R> where
    Recv: 'a + Receiver,
    R: Read,  type Item = WebSocketResult<Recv::F>;

pub fn incoming_dataframes(     &mut self ) -> DataFrameIterator<Receiver, BufReader<S>>

Returns an iterator over incoming data frames.

pub fn recv_message(&mut self) -> WebSocketResult<OwnedMessage>

Reads a single message from this receiver.

use websocket::{ClientBuilder, Message};
let mut client = ClientBuilder::new("ws://localhost:3000")
    .unwrap()
    .connect_insecure()
    .unwrap();

client.send_message(&Message::text("Hello world!")).unwrap();

let response = client.recv_message().unwrap();

pub fn headers(&self) -> &Headers

Access the headers that were sent in the server's handshake response. This is a catch all for headers other than protocols and extensions.

pub fn protocols(&self) -> &[String]

If you supplied a protocol, you must check that it was accepted by the server using this function. This is not done automatically because the terms of accepting a protocol can get complicated, especially if some protocols depend on others, etc.

let mut client = ClientBuilder::new("wss://test.fysh.in").unwrap()
    .add_protocol("xmpp")
    .connect_insecure()
    .unwrap();

// be sure to check the protocol is there!
assert!(client.protocols().iter().any(|p| p as &str == "xmpp"));

pub fn extensions(&self) -> &[Extension]

If you supplied a protocol, be sure to check if it was accepted by the server here. Since no extensions are implemented out of the box yet, using one will require its own implementation.

pub fn stream_ref(&self) -> &S

Get a reference to the stream. Useful to be able to set options on the stream.

let mut client = ClientBuilder::new("ws://double.down").unwrap()
    .connect_insecure()
    .unwrap();

client.stream_ref().set_ttl(60).unwrap();

pub fn writer_mut(&mut self) -> &mut dyn Write

Get a handle to the writable portion of this stream. This can be used to write custom extensions.

use websocket::Message;
use websocket::ws::sender::Sender as SenderTrait;
use websocket::sender::Sender;

let mut client = ClientBuilder::new("ws://the.room").unwrap()
    .connect_insecure()
    .unwrap();

let message = Message::text("Oh hi, Mark.");
let mut sender = Sender::new(true);
let mut buf = Vec::new();

sender.send_message(&mut buf, &message);

/* transform buf somehow */

client.writer_mut().write_all(&buf);

pub fn reader_mut(&mut self) -> &mut dyn Read

Get a handle to the readable portion of this stream. This can be used to transform raw bytes before they are read in.

use std::io::Cursor;
use websocket::ws::receiver::Receiver as ReceiverTrait;
use websocket::receiver::Receiver;

let mut client = ClientBuilder::new("ws://the.room").unwrap()
    .connect_insecure()
    .unwrap();

let mut receiver = Receiver::new(false);
let mut buf = Vec::new();

client.reader_mut().read_to_end(&mut buf);

/* transform buf somehow */

let mut buf_reader = Cursor::new(&mut buf);
let message = receiver.recv_message(&mut buf_reader).unwrap();

pub fn into_stream(self) -> (S, Option<(Vec<u8>, usize, usize)>)

Deconstruct the client into its underlying stream and maybe some of the buffer that was already read from the stream. The client uses a buffered reader to read in messages, so some bytes might already be read from the stream when this is called, these buffered bytes are returned in the form

(byte_buffer: Vec<u8>, buffer_capacity: usize, buffer_position: usize)

Important traits for MessageIterator<'a, Recv, R>

impl<'a, Recv, R> Iterator for MessageIterator<'a, Recv, R> where
    Recv: 'a + Receiver,
    R: Read,  type Item = WebSocketResult<Recv::M>;

pub fn incoming_messages<'a>(     &'a mut self ) -> MessageIterator<'a, Receiver, BufReader<S>>

Returns an iterator over incoming messages.

use websocket::ClientBuilder;

let mut client = ClientBuilder::new("ws://127.0.0.1:1234").unwrap()
                     .connect(None).unwrap();

for message in client.incoming_messages() {
    println!("Recv: {:?}", message.unwrap());
}

Note that since this method mutably borrows the Client, it may be necessary to first split() the Client and call incoming_messages() on the returned Receiver to be able to send messages within an iteration.

use websocket::ClientBuilder;

let mut client = ClientBuilder::new("ws://127.0.0.1:1234").unwrap()
                     .connect_insecure().unwrap();

let (mut receiver, mut sender) = client.split().unwrap();

for message in receiver.incoming_messages() {
    // Echo the message back
    sender.send_message(&message.unwrap()).unwrap();
}

impl<S> Client<S> where     S: Splittable + Stream,

pub fn split(     self ) -> IoResult<(Reader<<S as Splittable>::Reader>, Writer<<S as Splittable>::Writer>)>

Split this client into its constituent Sender and Receiver pair.

This allows the Sender and Receiver to be sent to different threads.

use std::thread;
use websocket::{ClientBuilder, Message};

let mut client = ClientBuilder::new("ws://127.0.0.1:1234").unwrap()
                     .connect_insecure().unwrap();

let (mut receiver, mut sender) = client.split().unwrap();

thread::spawn(move || {
    for message in receiver.incoming_messages() {
        println!("Recv: {:?}", message.unwrap());
    }
});

let message = Message::text("Hello, World!");
sender.send_message(&message).unwrap();