pub struct Client<S> where
S: Stream, { /* private fields */ }
Expand description
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
Implementations
sourceimpl Client<TcpStream>
impl Client<TcpStream>
sourcepub fn shutdown_sender(&self) -> IoResult<()>
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.
sourcepub fn shutdown_receiver(&self) -> IoResult<()>
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.
sourceimpl<S> Client<S> where
S: AsTcpStream + Stream,
impl<S> Client<S> where
S: AsTcpStream + Stream,
sourcepub fn shutdown(&self) -> IoResult<()>
pub fn shutdown(&self) -> IoResult<()>
Shuts down the client connection, will cause all pending and future IO to return immediately with an appropriate value.
sourcepub fn peer_addr(&self) -> IoResult<SocketAddr>
pub fn peer_addr(&self) -> IoResult<SocketAddr>
See TcpStream::peer_addr
(https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.peer_addr).
sourcepub fn local_addr(&self) -> IoResult<SocketAddr>
pub fn local_addr(&self) -> IoResult<SocketAddr>
See TcpStream::local_addr
(https://doc.rust-lang.org/std/net/struct.TcpStream.html#method.local_addr).
sourcepub fn set_nodelay(&mut self, nodelay: bool) -> IoResult<()>
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).
sourcepub fn set_nonblocking(&self, nonblocking: bool) -> IoResult<()>
pub fn set_nonblocking(&self, nonblocking: bool) -> IoResult<()>
Changes whether the stream is in nonblocking mode.
sourceimpl<S> Client<S> where
S: Stream,
impl<S> Client<S> where
S: Stream,
sourcepub fn send_dataframe<D>(&mut self, dataframe: &D) -> WebSocketResult<()> where
D: DataFrameable,
pub fn send_dataframe<D>(&mut self, dataframe: &D) -> WebSocketResult<()> where
D: DataFrameable,
Sends a single data frame to the remote endpoint.
sourcepub fn send_message<M>(&mut self, message: &M) -> WebSocketResult<()> where
M: Message,
pub fn send_message<M>(&mut self, message: &M) -> WebSocketResult<()> where
M: Message,
Sends a single message to the remote endpoint.
sourcepub fn recv_dataframe(&mut self) -> WebSocketResult<DataFrame>
pub fn recv_dataframe(&mut self) -> WebSocketResult<DataFrame>
Reads a single data frame from the remote endpoint.
sourcepub fn incoming_dataframes(
&mut self
) -> DataFrameIterator<'_, Receiver, BufReader<S>>ⓘNotable traits for DataFrameIterator<'a, Recv, R>impl<'a, Recv, R> Iterator for DataFrameIterator<'a, Recv, R> where
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::F, WebSocketError>;
pub fn incoming_dataframes(
&mut self
) -> DataFrameIterator<'_, Receiver, BufReader<S>>ⓘNotable traits for DataFrameIterator<'a, Recv, R>impl<'a, Recv, R> Iterator for DataFrameIterator<'a, Recv, R> where
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::F, WebSocketError>;
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::F, WebSocketError>;
Returns an iterator over incoming data frames.
sourcepub fn recv_message(&mut self) -> WebSocketResult<OwnedMessage>
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();
sourcepub fn headers(&self) -> &Headers
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.
sourcepub fn protocols(&self) -> &[String]
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"));
sourcepub fn extensions(&self) -> &[Extension]
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.
sourcepub fn stream_ref(&self) -> &S
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();
sourcepub fn writer_mut(&mut self) -> &mut dyn Write
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);
sourcepub fn reader_mut(&mut self) -> &mut dyn Read
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();
sourcepub fn into_stream(self) -> (S, Option<(Vec<u8>, usize, usize)>)
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)
sourcepub fn incoming_messages<'a>(
&'a mut self
) -> MessageIterator<'a, Receiver, BufReader<S>>ⓘNotable traits for MessageIterator<'a, Recv, R>impl<'a, Recv, R> Iterator for MessageIterator<'a, Recv, R> where
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::M, WebSocketError>;
pub fn incoming_messages<'a>(
&'a mut self
) -> MessageIterator<'a, Receiver, BufReader<S>>ⓘNotable traits for MessageIterator<'a, Recv, R>impl<'a, Recv, R> Iterator for MessageIterator<'a, Recv, R> where
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::M, WebSocketError>;
Recv: 'a + Receiver,
R: Read, type Item = Result<<Recv as Receiver>::M, WebSocketError>;
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();
}
sourceimpl<S> Client<S> where
S: Splittable + Stream,
impl<S> Client<S> where
S: Splittable + Stream,
sourcepub fn split(
self
) -> IoResult<(Reader<<S as Splittable>::Reader>, Writer<<S as Splittable>::Writer>)>
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();
Auto Trait Implementations
impl<S> !RefUnwindSafe for Client<S>
impl<S> Send for Client<S> where
S: Send,
impl<S> !Sync for Client<S>
impl<S> Unpin for Client<S> where
S: Unpin,
impl<S> !UnwindSafe for Client<S>
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more