Struct evzht9h3nznqzwl::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>

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.

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, 

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

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

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

See TcpStream::peer_addr.

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

See TcpStream::local_addr.

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

See TcpStream::set_nodelay.

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

Changes whether the stream is in nonblocking mode.

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

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

Sends a single data frame to the remote endpoint.

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

Sends a single message to the remote endpoint.

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

Reads a single data frame from the remote endpoint.

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

Returns an iterator over incoming data frames.

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();

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.

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"));

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.

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();

fn writer_mut(&mut self) -> &mut 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);

fn reader_mut(&mut self) -> &mut 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();

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)

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, 

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();