WebSocket Class Reference

#include <Pt/Http/WebSocket.h>

Client handshake and messages on an upgraded stream. More...

Inherits Connectable.

Public Member Functions
	WebSocket (Client &client)
	Creates a WebSocket that handshakes through client.
	~WebSocket ()
	Calls close().
void	beginConnect (const std::string &url, const std::string &origin=std::string())
	Begins a client handshake for url.
void	addProtocol (const std::string &name)
	Offers one Sec-WebSocket-Protocol name.
const std::string &	protocol () const
	Returns the protocol name echoed by the server.
Pt::Signal< WebSocket & > &	connected ()
	Returns the signal emitted when the handshake finishes.
void	endConnect ()
	Completes the client handshake.
WebSocketMessage &	incoming ()
	Returns the incoming message.
WebSocketMessage &	outgoing ()
	Returns the outgoing message.
void	beginSend (bool finished=true)
	Begins sending outgoing().
MessageProgress	endSend ()
	Completes the send started by beginSend().
void	beginReceive ()
	Begins receiving into incoming().
MessageProgress	endReceive ()
	Completes the receive started by beginReceive().
void	beginPing (const char *payload=0, std::size_t n=0)
	Begins writing a ping with an optional payload of at most 125 bytes.
void	endPing ()
	Completes the ping started by beginPing().
void	beginShutdown (unsigned code=1000, const std::string &reason=std::string())
	Begins a close handshake.
void	endShutdown ()
	Completes the shutdown started by beginShutdown().
void	close ()
	Releases the stream and writes no frame.
unsigned	closeCode () const
	Returns the close status code of the handshake that ended the stream.
const std::string &	closeReason () const
	Returns the close reason of the handshake that ended the stream.
Pt::Signal< WebSocket & > &	inputReady ()
	Returns the signal emitted when data bytes were received.
Pt::Signal< WebSocket & > &	outputReady ()
	Returns the signal emitted when data bytes were sent.
Pt::Signal< WebSocket & > &	pingReady ()
	Returns the signal emitted when a ping operation completes.
Pt::Signal< WebSocket & > &	shutdownReady ()
	Returns the signal emitted when a shutdown operation completes.
Pt::Signal< WebSocket & > &	closed ()
	Returns the signal emitted when the engine has ended the protocol.
Pt::Signal< WebSocket &, const std::string & > &	pong ()
	Returns the signal emitted for a received pong.
void	setMaxMessageSize (std::size_t maxSize)
	Closes the stream when a data message exceeds maxSize.
void	setIdleTimeout (std::size_t ms)
	Closes the stream after ms without an incoming frame.
void	setPingInterval (std::size_t ms)
	Writes a keepalive ping after ms without an incoming frame.
void	setPingTimeout (std::size_t ms)
	Closes the stream if a ping is unanswered for ms.
void	setCloseTimeout (std::size_t ms)
	Closes the stream if a close handshake is unanswered for ms.

Detailed Description

WebSocket is the client side of a WebSocket upgrade. It performs the HTTP handshake through an HTTP user agent and then sends and receives payloads on the stream that handshake produces. Host, port, event loop, timeout and TLS are settings of that agent. The handshake uses the client's timeout. The socket stores a reference and does not own it, so the agent must outlive the socket, including a handshake that is still waiting on the loop. After a finished 101 the socket formats the stream the client already owns. setIdleTimeout() bounds inbound silence, setPingInterval() a keepalive ping after inbound silence, setPingTimeout() an unanswered ping, and setCloseTimeout() a close handshake the peer never answers. The client still owns the connection. Closing the socket closes the stream. The socket does not own the stream. A client masks every frame it writes.

The example completes the handshake and then writes a text message.

void onOutputReady(Pt::Http::WebSocket& socket)
{
    Pt::Http::MessageProgress progress = socket.endSend();
    if( ! progress.finished() )
        socket.beginSend();
}
 
void onInputReady(Pt::Http::WebSocket& socket)
{
    Pt::Http::MessageProgress progress = socket.endReceive();
    if( ! progress.finished() )
    {
        socket.incoming().discard();
        socket.beginReceive();
        return;
    }
 
    socket.incoming().clear();
    socket.beginReceive();
}
 
void onConnected(Pt::Http::WebSocket& socket)
{
    socket.endConnect();
    socket.outgoing().setType(Pt::Http::WebSocketMessage::Text);
    socket.outgoing().body() << "hello";
    socket.beginSend();
    socket.beginReceive();
}
 
Pt::System::MainLoop loop;
Pt::Net::Endpoint ep("localhost", 80);
Pt::Http::Client client(loop, ep);
Pt::Http::WebSocket socket(client);
socket.connected() += Pt::slot(onConnected);
socket.outputReady() += Pt::slot(onOutputReady);
socket.inputReady() += Pt::slot(onInputReady);
socket.beginConnect("/ws");
loop.run();

Construct the socket with the Client that performs the handshake. Connect connected() and call beginConnect() with a request path, or with a ws:// URL whose host and port are already the client's endpoint. The path and query of that URL become the request URL; the client does not take the host from the URL. The optional second argument is the Origin header. endConnect() completes the handshake and throws if it failed. addProtocol() offers one Sec-WebSocket-Protocol name before beginConnect(). Several calls offer several names, in order. After a finished handshake protocol() is the single name the server echoed, or empty when the server selected none. An echo that was not offered fails the handshake. After that success the socket no longer uses the client for messages.

The socket owns two WebSocketMessage objects, incoming() and outgoing(), the way a client owns a request and a reply. Set the type, write the body, and call beginSend(). Call beginSend(false) while more body will be written, then beginSend(true) for the last part. outputReady() reports that data bytes were sent. endSend() returns MessageProgress. If the send step is not finished, beginSend() continues it with the same completion flag. beginReceive() fills incoming(). inputReady() reports that data bytes were received. endReceive() returns progress. After finished(), clear() drops the body so the same object can carry the next message. beginReceive() starts frame processing. Until then, incoming frames stay in the stream. Control frames are processed while a receive is outstanding. A local beginShutdown() also keeps input running until the peer replies with its close frame. The two are independent: a receive started before or during a shutdown still delivers what the peer sent before that reply.

Ping, pong, shutdown and close are socket operations, not messages.

socket.beginPing();
socket.beginShutdown(1000, "done");
socket.close();

beginPing() enqueues a ping. pingReady() reports that its frame was written; call endPing() from that signal to observe a write error. A received ping is answered by the engine. After a close frame is queued nothing further is written, so beginPing() throws and a received ping is no longer answered. A received pong is reported by pong(). Neither is delivered through incoming(). beginShutdown() enqueues a close frame with a status code and a reason, then keeps reading until the peer replies. shutdownReady() reports the completed handshake; call endShutdown() from that signal to observe an error. A peer that never starts a receive never replies, so setCloseTimeout() bounds that wait. It defaults to ten seconds. Zero leaves the wait unbounded. setPingInterval() writes a keepalive ping after inbound silence. setPingTimeout() bounds that ping and an unanswered beginPing(). Interval, ping and idle default to zero on this type. A received close is answered by the engine. When no local shutdown is outstanding, closed() reports that the protocol has ended. The stream stays bound. Call close() from that signal. An outstanding shutdown completes through shutdownReady(); call endShutdown() and then close(). beginReceive() and beginShutdown() then throw. closeCode() and closeReason() report the handshake that ended the stream. No close frame leaves the code at 1006. close() releases the stream and writes no frame. It does not block and emits nothing. The destructor calls it. Destruction of the stream detaches the channel. The owner deletes this socket.

On the server the application does not construct this type. The server facade is WebSocketSession, which exposes the same message operations without a client handshake.

Constructor & Destructor Documentation

WebSocket()

WebSocket ( Client & client )

explicit

Stores a reference to client. The client must outlive this socket.

Member Function Documentation

beginConnect()

void beginConnect	(	const std::string &	url,
		const std::string &	origin = std::string() )

url is a request path, or a ws:// URL whose host and port are the client's endpoint. origin is the Origin header. Host, port and TLS come from the client.

addProtocol()

void addProtocol

(

const std::string &

name

)

Several calls offer several names, in order. The offer is sent by the next beginConnect().

Exceptions

%std::invalid_argument

if name is empty or is not a single protocol token.

protocol()

const std::string & protocol

(

)

const

Empty before a finished handshake, and empty when the server selected no name.

endConnect()

void endConnect

(

)

Exceptions

%std::exception

if the handshake failed.

beginSend()

void beginSend

(

bool

finished = true

)

The completion flag is true when this is the last part of the message. Call beginSend(false) while more body will be written. endSend() reports whether this step has left the socket. If it is not finished, call beginSend() again with the same flag. The engine may still split this step into frames.

Parameters

finished

True if this is the last part of the message.

Exceptions

%std::logic_error	if a send is outstanding, the handshake is not finished, or a shutdown is queued.
%std::invalid_argument	if the type is Unknown, or the body is larger than setMaxMessageSize().
%std::exception	if a previous write failed.

endSend()

MessageProgress endSend

(

)

Returns

Progress of this send step.

Exceptions

%std::logic_error

if the send has not completed or the stream has ended.

beginReceive()

void beginReceive

(

)

Starts processing incoming frames. Frames received before this call stay in the stream.

Exceptions

%std::logic_error	if a receive is outstanding, the handshake is not finished, or the stream has ended.
%std::exception	if a protocol violation ended the frame stream, or a previous read failed.

endReceive()

MessageProgress endReceive

(

)

Returns

Progress of this receive step.

Exceptions

%std::logic_error	if the receive has not completed.
%std::exception	if a protocol violation ended the frame stream, or a previous read failed.

beginPing()

void beginPing	(	const char *	payload = 0,
		std::size_t	n = 0 )

Exceptions

%std::invalid_argument	if n is greater than 125, or if payload is null and n is nonzero.
%std::logic_error	if a ping is outstanding, a close is queued, or the handshake is not finished.
%std::exception	if a previous write failed.

endPing()

void endPing

(

)

Exceptions

%std::logic_error	if the ping is not ready.
%std::exception	if writing the ping failed.

beginShutdown()

void beginShutdown	(	unsigned	code = 1000,
		const std::string &	reason = std::string() )

Exceptions

%std::invalid_argument	if code is 1005, 1006 or 1015, if reason is longer than 123 bytes, or if reason is not valid UTF-8.
%std::logic_error	if a shutdown is outstanding, the handshake is not finished, or a close is already queued.
%std::exception	if a previous write failed.

endShutdown()

void endShutdown

(

)

Exceptions

%std::logic_error	if the shutdown is not ready.
%std::exception	if the close handshake failed.

close()

void close

(

)

Does not block and emits nothing. The destructor calls this. beginSend() and beginReceive() then throw. No close frame leaves closeCode() at 1006.

pingReady()

Pt::Signal< WebSocket & > & pingReady

(

)

Call endPing() from the signal to observe a write error.

shutdownReady()

Pt::Signal< WebSocket & > & shutdownReady

(

)

The stream stays bound. Call endShutdown() from the signal to observe a close-handshake error, then close().

closed()

Pt::Signal< WebSocket & > & closed

(

)

No local shutdown is outstanding. The stream stays bound. Call close() from the signal.

pong()

Pt::Signal< WebSocket &, const std::string & > & pong

(

)

The payload contains arbitrary bytes and is valid for the duration of the signal call. A pong does not change incoming() or emit inputReady().

setMaxMessageSize()

void setMaxMessageSize

(

std::size_t

maxSize

)

Zero disables the limit. The count is the declared payload of one data message from the first data opcode to FIN.

setIdleTimeout()

void setIdleTimeout

(

std::size_t

ms

)

Zero disables the idle timeout. Incoming data, a received ping, and a received pong restart it. Sending does not.

setPingInterval()

void setPingInterval

(

std::size_t

ms

)

Zero disables the interval. Incoming data, a received ping, and a received pong restart it. Sending does not. The engine writes an empty ping only while a receive is outstanding. That ping does not emit pingReady(). beginPing() throws while a ping is outstanding. setPingTimeout() bounds the wait.

setPingTimeout()

void setPingTimeout

(

std::size_t

ms

)

Zero disables the ping timeout. The wait starts at beginPing() and at a keepalive ping. A pong stops it. An incoming ping does not.

setCloseTimeout()

void setCloseTimeout

(

std::size_t

ms

)

Zero leaves the wait unbounded. The default is ten seconds. The wait starts at beginShutdown().