Struct websocket::client::sync::Client [−] [src]

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>
[src]

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

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, 
[src]

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

See TcpStream::peer_addr.

See TcpStream::local_addr.

See TcpStream::set_nodelay.

Changes whether the stream is in nonblocking mode.

impl<S> Client<S> where
    S: Stream, 
[src]

Sends a single data frame to the remote endpoint.

Sends a single message to the remote endpoint.

Reads a single data frame from the remote endpoint.

Returns an iterator over incoming data frames.

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

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

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

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.

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

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

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

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)

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, 
[src]

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