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]
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,
[src]
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>
fn set_nodelay(&mut self, nodelay: bool) -> IoResult<()>
fn set_nonblocking(&self, nonblocking: bool) -> IoResult<()>
Changes whether the stream is in nonblocking mode.
impl<S> Client<S> where
S: Stream,
[src]
S: Stream,
fn send_dataframe<D>(&mut self, dataframe: &D) -> WebSocketResult<()> where
D: DataFrameable,
D: DataFrameable,
Sends a single data frame to the remote endpoint.
fn send_message<M>(&mut self, message: &M) -> WebSocketResult<()> where
M: Message,
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>>
&'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,
[src]
S: Splittable + Stream,
fn split(
self
) -> IoResult<(Reader<<S as Splittable>::Reader>, Writer<<S as Splittable>::Writer>)>
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();