WebSocket Class Reference

#include <Pt/Http/WebSocket.h>

Framed WebSocket I/O device. More...

Inherits IODevice, and Connectable.

Public Types
enum	Frame {   Unknow ,   Text ,   Binary ,   Ping ,   Pong }
	WebSocket frame opcode. More...

Public Member Functions
	WebSocket ()
	Creates a closed WebSocket.
	WebSocket (Pt::Http::IOStream *stream)
	Creates a WebSocket that accepts stream.
virtual	~WebSocket ()
	Destructor.
void	accept (Pt::Http::IOStream *stream)
	Accepts an upgraded connection stream.
void	beginConnect (const std::string &url, const std::string &origin=std::string(), bool keepAlive=true)
	Begins a client handshake to url.
Pt::Signal< WebSocket & > &	connected ()
	Returns the signal emitted when the handshake finishes.
void	endConnect ()
	Completes the client handshake.
void	setSendFrame (Frame m)
	Sets the opcode for the next send.
Frame	receiveFrame () const
	Returns the opcode of the last received frame.
void	sendPongFrame ()
	Sends a pong frame.
void	sendPingFrame ()
	Sends a ping frame.
void	close ()
	Closes the device.
void	setTimeout (std::size_t timeout)
	Sets the timeout for blocking I/O in milliseconds.
void	beginRead (char *buffer, std::size_t n)
	Begins to read data.
std::size_t	endRead ()
	Ends reading data.
std::size_t	read (char *buffer, std::size_t n)
	Read data from I/O device.
void	beginWrite (const char *buffer, std::size_t n)
	Begins to write data.
std::size_t	endWrite ()
	Ends writing data.
std::size_t	write (const char *buffer, std::size_t n)
	Write data to I/O device.
bool	seekable () const
	Returns true if device is seekable.
pos_type	seek (off_type offset, seekdir sd)
	Moves the read position to the given offset.
std::size_t	peek (char *buffer, std::size_t n)
	Peek data from I/O device without consuming them.
void	sync ()
	Synchronize device.
pos_type	position ()
	Returns the current I/O position.
bool	isEof () const
	Returns if the device has reached EOF.
Signal< IODevice & > &	inputReady ()
	Notifies about available data.
Signal< IODevice & > &	outputReady ()
	Notifies when data can be written.
bool	isReading () const
	Returns true if the device is reading.
bool	isWriting () const
	Returns true if the device is writing.
EventLoop *	loop () const
	Returns the used event loop.
void	setActive (EventLoop &parent)
	Sets the parent loop, so that operations can be run.
void	detach ()
	Remove from event loop and cancels outstanding operations.
void	cancel ()
	Cancels all operations.
bool	run ()
	Run operation if it is ready.
EventLoop *	parent () const
	Returns the used event loop.

Protected Member Functions
virtual void	onCancel ()
	Blocks until operation has cancelled.
virtual bool	onRun ()
	Check if ready and run.
virtual void	onAttach (Pt::System::EventLoop &loop)
	Attached to loop.
virtual void	onDetach (Pt::System::EventLoop &loop)
	Detached from loop.
void	post ()
	Posts this selectable to its event loop from any thread.

Detailed Description

WebSocket is the IODevice that follows a WebSocket handshake. After the handshake the same TCP connection carries framed messages instead of HTTP request and reply messages. read() and write() transfer payload bytes. The frame type is separate: setSendFrame() selects the opcode for the next send, and receiveFrame() reports the opcode of the frame that was last received.

On the client, attach the socket to an event loop, connect connected(), and call beginConnect() with a ws:// URL. endConnect() completes the handshake and throws if it failed. On the server, accept() takes the IOStream of an upgraded connection, which a WebSocketService handshake produces.

Ping and pong are control frames. sendPingFrame() writes a ping, and after a ping is received sendPongFrame() writes the matching pong. Text and binary are the data payload. Unknown is the unset frame type.

Member Enumeration Documentation

Frame

enum Frame

Enumerator
Unknow	Unset frame type.
Text	Text data frame.
Binary	Binary data frame.
Ping	Ping frame.
Pong	Pong frame.

Member Function Documentation

beginConnect()

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

origin is the Origin header. keepAlive requests a persistent HTTP connection for the handshake.

endConnect()

void endConnect

(

)

Exceptions

%std::exception

if the handshake failed.

read()

std::size_t read ( char * buffer, std::size_t n )

inherited

Reads up to n bytes and stores them in buffer. Returns the number of bytes read, which may be less than requested and even 0 if the device operates in asynchronous (non-blocking) mode. In case of EOF the IODevice is set to eof.

Parameters

buffer	buffer where to place the data to be read.
n	number of bytes to read

Returns

number of bytes read, which may be less than requested.

Exceptions

IOError

write()

std::size_t write ( const char * buffer, std::size_t n )

inherited

Writes n bytes from buffer to this I/O device. Returns the number of bytes written, which may be less than requested. In case of EOF the IODevice is set to eof.

Exceptions

IOError

seek()

pos_type seek ( off_type offset, seekdir sd )

inherited

Exceptions

IOError

peek()

std::size_t peek ( char * buffer, std::size_t n )

inherited

Exceptions

IOError

sync()

void sync ( )

inherited

Commits written data to physical device.

Exceptions

IOError

position()

pos_type position ( )

inherited

The current I/O position is returned or an IOError is thrown if the device is not seekable. Seekability can be tested with seekable().

Exceptions

IOError

inputReady()

Signal< IODevice & > & inputReady ( )

inherited

This signal is send when the IODevice is monitored in an EventLoop and data becomes available.

outputReady()

Signal< IODevice & > & outputReady ( )

inherited

This signal is send when the IODevice is monitored in an EventLoop and the device is ready to write data.