RFC 6455 compliant WebSocket client and server implementation. More...

#include <wpinet/WebSocket.h>

Inheritance diagram for wpi::WebSocket:

Classes
struct	ClientOptions
	Client connection options. More...

struct	Frame
	Frame. More...

Public Types
enum	State { CONNECTING = 0 , OPEN , CLOSING , FAILED , CLOSED }
	Connection states. More...

Public Member Functions
	WebSocket (uv::Stream &stream, bool server, const private_init &)

	WebSocket (const WebSocket &)=delete

	WebSocket (WebSocket &&)=delete

WebSocket &	operator= (const WebSocket &)=delete

WebSocket &	operator= (WebSocket &&)=delete

	~WebSocket ()

State	GetState () const
	Get connection state. More...

bool	IsOpen () const
	Return if the connection is open. More...

uv::Stream &	GetStream () const
	Get the underlying stream. More...

std::string_view	GetProtocol () const
	Get the selected sub-protocol. More...

void	SetMaxMessageSize (size_t size)
	Set the maximum message size. More...

void	SetCombineFragments (bool combine)
	Set whether or not fragmented frames should be combined. More...

void	Close (uint16_t code=1005, std::string_view reason={})
	Initiate a closing handshake. More...

void	SendText (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message. More...

void	SendText (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message. More...

void	SendBinary (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a binary message. More...

void	SendBinary (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a binary message. More...

void	SendTextFragment (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message fragment. More...

void	SendTextFragment (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message fragment. More...

void	SendBinaryFragment (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message fragment. More...

void	SendBinaryFragment (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a text message fragment. More...

void	SendFragment (std::span< const uv::Buffer > data, bool fin, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a continuation frame. More...

void	SendFragment (std::initializer_list< uv::Buffer > data, bool fin, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a continuation frame. More...

void	SendPing (std::function< void(uv::Error)> callback=nullptr)
	Send a ping frame with no data. More...

void	SendPing (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a ping frame. More...

void	SendPing (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a ping frame. More...

void	SendPong (std::function< void(uv::Error)> callback=nullptr)
	Send a pong frame with no data. More...

void	SendPong (std::span< const uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a pong frame. More...

void	SendPong (std::initializer_list< uv::Buffer > data, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send a pong frame. More...

void	SendFrames (std::span< const Frame > frames, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Send multiple frames. More...

std::span< const Frame >	TrySendFrames (std::span< const Frame > frames, std::function< void(std::span< uv::Buffer >, uv::Error)> callback)
	Try to send multiple frames. More...

bool	IsWriteInProgress () const
	Returns whether or not a previous TrySendFrames is still in progress. More...

void	Fail (uint16_t code=1002, std::string_view reason="protocol error")
	Fail the connection. More...

void	Terminate (uint16_t code=1006, std::string_view reason="terminated")
	Forcibly close the connection. More...

template<typename T = void>
std::shared_ptr< T >	GetData () const
	Gets user-defined data. More...

void	SetData (std::shared_ptr< void > data)
	Sets user-defined data. More...

void	Shutdown ()
	Shuts down and closes the underlying stream. More...

uint64_t	GetLastReceivedTime () const
	Gets the last time data was received on the stream. More...

Static Public Member Functions
static std::shared_ptr< WebSocket >	CreateClient (uv::Stream &stream, std::string_view uri, std::string_view host, std::span< const std::string_view > protocols={}, const ClientOptions &options={})
	Starts a client connection by performing the initial client handshake. More...

static std::shared_ptr< WebSocket >	CreateClient (uv::Stream &stream, std::string_view uri, std::string_view host, std::initializer_list< std::string_view > protocols, const ClientOptions &options={})
	Starts a client connection by performing the initial client handshake. More...

static std::shared_ptr< WebSocket >	CreateServer (uv::Stream &stream, std::string_view key, std::string_view version, std::string_view protocol={})
	Starts a server connection by performing the initial server side handshake. More...

Public Attributes
sig::Signal< std::string_view >	open
	Open event. More...

sig::Signal< uint16_t, std::string_view >	closed
	Close event. More...

sig::Signal< std::string_view, bool >	text
	Text message event. More...

sig::Signal< std::span< const uint8_t >, bool >	binary
	Binary message event. More...

sig::Signal< std::span< const uint8_t > >	ping
	Ping event. More...

sig::Signal< std::span< const uint8_t > >	pong
	Pong event. More...

Static Public Attributes
static constexpr uint8_t	kOpCont = 0x00

static constexpr uint8_t	kOpText = 0x01

static constexpr uint8_t	kOpBinary = 0x02

static constexpr uint8_t	kOpClose = 0x08

static constexpr uint8_t	kOpPing = 0x09

static constexpr uint8_t	kOpPong = 0x0A

static constexpr uint8_t	kOpMask = 0x0F

static constexpr uint8_t	kFlagFin = 0x80

static constexpr uint8_t	kFlagControl = 0x08

Detailed Description

RFC 6455 compliant WebSocket client and server implementation.

Member Enumeration Documentation

◆ State

enum wpi::WebSocket::State

Connection states.

Enumerator
CONNECTING	The connection is not yet open.
OPEN	The connection is open and ready to communicate.
CLOSING	The connection is in the process of closing.
FAILED	The connection failed.
CLOSED	The connection is closed.

Constructor & Destructor Documentation

◆ WebSocket() [1/3]

wpi::WebSocket::WebSocket	(	uv::Stream &	stream,
		bool	server,
		const private_init &
	)

◆ WebSocket() [2/3]

wpi::WebSocket::WebSocket ( const WebSocket & )

delete

◆ WebSocket() [3/3]

wpi::WebSocket::WebSocket ( WebSocket && )

delete

◆ ~WebSocket()

wpi::WebSocket::~WebSocket ( )

Member Function Documentation

◆ Close()

void wpi::WebSocket::Close	(	uint16_t	code = `1005`,
		std::string_view	reason = `{}`
	)

Initiate a closing handshake.

Parameters

code	A numeric status code (defaults to 1005, no status code)
reason	A human-readable string explaining why the connection is closing (optional).

◆ CreateClient() [1/2]

static std::shared_ptr< WebSocket > wpi::WebSocket::CreateClient	(	uv::Stream &	stream,
		std::string_view	uri,
		std::string_view	host,
		std::initializer_list< std::string_view >	protocols,
		const ClientOptions &	options = `{}`
	)

inlinestatic

Starts a client connection by performing the initial client handshake.

An open event is emitted when the handshake completes. This sets the stream user data to the websocket.

Parameters

stream	Connection stream
uri	The Request-URI to send
host	The host or host:port to send
protocols	The list of subprotocols
options	Handshake options

◆ CreateClient() [2/2]

static std::shared_ptr< WebSocket > wpi::WebSocket::CreateClient	(	uv::Stream &	stream,
		std::string_view	uri,
		std::string_view	host,
		std::span< const std::string_view >	protocols = `{}`,
		const ClientOptions &	options = `{}`
	)

static

Starts a client connection by performing the initial client handshake.

An open event is emitted when the handshake completes. This sets the stream user data to the websocket.

Parameters

stream	Connection stream
uri	The Request-URI to send
host	The host or host:port to send
protocols	The list of subprotocols
options	Handshake options

◆ CreateServer()

static std::shared_ptr< WebSocket > wpi::WebSocket::CreateServer	(	uv::Stream &	stream,
		std::string_view	key,
		std::string_view	version,
		std::string_view	protocol = `{}`
	)

static

Starts a server connection by performing the initial server side handshake.

This should be called after the HTTP headers have been received. An open event is emitted when the handshake completes. This sets the stream user data to the websocket.

Parameters

stream	Connection stream
key	The value of the Sec-WebSocket-Key header field in the client request
version	The value of the Sec-WebSocket-Version header field in the client request
protocol	The subprotocol to send to the client (in the Sec-WebSocket-Protocol header field).

◆ Fail()

void wpi::WebSocket::Fail	(	uint16_t	code = `1002`,
		std::string_view	reason = `"protocol error"`
	)

Fail the connection.

◆ GetData()

template<typename T = void>

std::shared_ptr< T > wpi::WebSocket::GetData ( ) const

inline

Gets user-defined data.

Returns: User-defined data if any, nullptr otherwise.

◆ GetLastReceivedTime()

uint64_t wpi::WebSocket::GetLastReceivedTime ( ) const

inline

Gets the last time data was received on the stream.

Returns: Timestamp

◆ GetProtocol()

std::string_view wpi::WebSocket::GetProtocol ( ) const

inline

Get the selected sub-protocol.

Only valid in or after the open() event.

◆ GetState()

State wpi::WebSocket::GetState ( ) const

inline

Get connection state.

◆ GetStream()

uv::Stream & wpi::WebSocket::GetStream ( ) const

inline

Get the underlying stream.

◆ IsOpen()

bool wpi::WebSocket::IsOpen ( ) const

inline

Return if the connection is open.

Messages can only be sent on open connections.

◆ IsWriteInProgress()

bool wpi::WebSocket::IsWriteInProgress ( ) const

inline

Returns whether or not a previous TrySendFrames is still in progress.

Calling TrySendFrames if this returns true will return all frames.

Returns: True if a TryWrite is in progress

◆ operator=() [1/2]

WebSocket & wpi::WebSocket::operator= ( const WebSocket & )

delete

◆ operator=() [2/2]

WebSocket & wpi::WebSocket::operator= ( WebSocket && )

delete

◆ SendBinary() [1/2]

void wpi::WebSocket::SendBinary	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a binary message.

Parameters

data	Data to send
callback	Callback which is invoked when the write completes.

◆ SendBinary() [2/2]

void wpi::WebSocket::SendBinary	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a binary message.

Parameters

data	Data to send
callback	Callback which is invoked when the write completes.

◆ SendBinaryFragment() [1/2]

void wpi::WebSocket::SendBinaryFragment	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters

data	Data to send
callback	Callback which is invoked when the write completes.

◆ SendBinaryFragment() [2/2]

void wpi::WebSocket::SendBinaryFragment	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters

data	Data to send
callback	Callback which is invoked when the write completes.

◆ SendFragment() [1/2]

void wpi::WebSocket::SendFragment	(	std::initializer_list< uv::Buffer >	data,
		bool	fin,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a continuation frame.

This is used to send additional parts of a message started with SendTextFragment() or SendBinaryFragment().

Parameters

data	Data to send
fin	Set to true if this is the final fragment of the message
callback	Callback which is invoked when the write completes.

◆ SendFragment() [2/2]

void wpi::WebSocket::SendFragment	(	std::span< const uv::Buffer >	data,
		bool	fin,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a continuation frame.

This is used to send additional parts of a message started with SendTextFragment() or SendBinaryFragment().

Parameters

data	Data to send
fin	Set to true if this is the final fragment of the message
callback	Callback which is invoked when the write completes.

◆ SendFrames()

void wpi::WebSocket::SendFrames	(	std::span< const Frame >	frames,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

Send multiple frames.

Parameters

frames	Frame type/data pairs
callback	Callback which is invoked when the write completes.

◆ SendPing() [1/3]

void wpi::WebSocket::SendPing ( std::function< void(uv::Error)> callback = nullptr )

inline

Send a ping frame with no data.

Parameters

callback Optional callback which is invoked when the ping frame write completes.

◆ SendPing() [2/3]

void wpi::WebSocket::SendPing	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a ping frame.

Parameters

data	Data to send in the ping frame
callback	Callback which is invoked when the ping frame write completes.

◆ SendPing() [3/3]

void wpi::WebSocket::SendPing	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a ping frame.

Parameters

data	Data to send in the ping frame
callback	Callback which is invoked when the ping frame write completes.

◆ SendPong() [1/3]

void wpi::WebSocket::SendPong ( std::function< void(uv::Error)> callback = nullptr )

inline

Send a pong frame with no data.

Parameters

callback Optional callback which is invoked when the pong frame write completes.

◆ SendPong() [2/3]

void wpi::WebSocket::SendPong	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a pong frame.

Parameters

data	Data to send in the pong frame
callback	Callback which is invoked when the pong frame write completes.

◆ SendPong() [3/3]

void wpi::WebSocket::SendPong	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a pong frame.

Parameters

data	Data to send in the pong frame
callback	Callback which is invoked when the pong frame write completes.

◆ SendText() [1/2]

void wpi::WebSocket::SendText	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message.

Parameters

data	UTF-8 encoded data to send
callback	Callback which is invoked when the write completes.

◆ SendText() [2/2]

void wpi::WebSocket::SendText	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message.

Parameters

data	UTF-8 encoded data to send
callback	Callback which is invoked when the write completes.

◆ SendTextFragment() [1/2]

void wpi::WebSocket::SendTextFragment	(	std::initializer_list< uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters

data	UTF-8 encoded data to send
callback	Callback which is invoked when the write completes.

◆ SendTextFragment() [2/2]

void wpi::WebSocket::SendTextFragment	(	std::span< const uv::Buffer >	data,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

inline

Send a text message fragment.

This must be followed by one or more SendFragment() calls, where the last one has fin=True, to complete the message.

Parameters

data	UTF-8 encoded data to send
callback	Callback which is invoked when the write completes.

◆ SetCombineFragments()

void wpi::WebSocket::SetCombineFragments ( bool combine )

inline

Set whether or not fragmented frames should be combined.

Default is to combine. If fragmented frames are combined, the text and binary callbacks will always have the second parameter (fin) set to true.

Parameters

combine True if fragmented frames should be combined.

◆ SetData()

void wpi::WebSocket::SetData ( std::shared_ptr< void > data )

inline

Sets user-defined data.

Parameters

data	User-defined arbitrary data.

◆ SetMaxMessageSize()

void wpi::WebSocket::SetMaxMessageSize ( size_t size )

inline

Set the maximum message size.

Default is 128 KB. If configured to combine fragments this maximum applies to the entire message (all combined fragments).

Parameters

size	Maximum message size in bytes

◆ Shutdown()

void wpi::WebSocket::Shutdown ( )

Shuts down and closes the underlying stream.

◆ Terminate()

void wpi::WebSocket::Terminate	(	uint16_t	code = `1006`,
		std::string_view	reason = `"terminated"`
	)

Forcibly close the connection.

◆ TrySendFrames()

std::span< const Frame > wpi::WebSocket::TrySendFrames	(	std::span< const Frame >	frames,
		std::function< void(std::span< uv::Buffer >, uv::Error)>	callback
	)

Try to send multiple frames.

Tries to send as many frames as possible immediately, and only queues the "last" frame it can (as the network queue will almost always fill partway through a frame). The frames following the last frame will NOT be queued for transmission; the caller is responsible for how to handle (e.g. re-send) those frames (e.g. when the callback is called).

Parameters

frames	Frame type/data pairs
callback	Callback which is invoked when the write completes of the last frame that is not returned.

Returns: Remaining frames that will not be sent

Member Data Documentation

◆ binary

sig::Signal<std::span<const uint8_t>, bool> wpi::WebSocket::binary

Binary message event.

Emitted when a binary message is received. The first parameter is the data, the second parameter is true if the data is the last fragment of the message.

◆ closed

sig::Signal<uint16_t, std::string_view> wpi::WebSocket::closed

Close event.

Emitted when the connection is closed. The first parameter is a numeric value indicating the status code explaining why the connection has been closed. The second parameter is a human-readable string explaining the reason why the connection has been closed.

◆ kFlagControl

constexpr uint8_t wpi::WebSocket::kFlagControl = 0x08

staticconstexpr

◆ kFlagFin

constexpr uint8_t wpi::WebSocket::kFlagFin = 0x80

staticconstexpr

◆ kOpBinary

constexpr uint8_t wpi::WebSocket::kOpBinary = 0x02

staticconstexpr

◆ kOpClose

constexpr uint8_t wpi::WebSocket::kOpClose = 0x08

staticconstexpr

◆ kOpCont

constexpr uint8_t wpi::WebSocket::kOpCont = 0x00

staticconstexpr

◆ kOpMask

constexpr uint8_t wpi::WebSocket::kOpMask = 0x0F

staticconstexpr

◆ kOpPing

constexpr uint8_t wpi::WebSocket::kOpPing = 0x09

staticconstexpr

◆ kOpPong

constexpr uint8_t wpi::WebSocket::kOpPong = 0x0A

staticconstexpr

◆ kOpText

constexpr uint8_t wpi::WebSocket::kOpText = 0x01

staticconstexpr

◆ open

sig::Signal<std::string_view> wpi::WebSocket::open

Open event.

Emitted when the connection is open and ready to communicate. The parameter is the selected subprotocol.

◆ ping

sig::Signal<std::span<const uint8_t> > wpi::WebSocket::ping

Ping event.

Emitted when a ping message is received. A pong message is automatically sent in response, so this is simply a notification.

◆ pong

sig::Signal<std::span<const uint8_t> > wpi::WebSocket::pong

Pong event.

Emitted when a pong message is received.

◆ text

sig::Signal<std::string_view, bool> wpi::WebSocket::text

Text message event.

Emitted when a text message is received. The first parameter is the data, the second parameter is true if the data is the last fragment of the message.

The documentation for this class was generated from the following file:

wpinet/WebSocket.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ WebSocket() [1/3]

◆ WebSocket() [2/3]

◆ WebSocket() [3/3]

◆ ~WebSocket()

Member Function Documentation

◆ Close()

◆ CreateClient() [1/2]

◆ CreateClient() [2/2]

◆ CreateServer()

◆ Fail()

◆ GetData()

◆ GetLastReceivedTime()

◆ GetProtocol()

◆ GetState()

◆ GetStream()

◆ IsOpen()

◆ IsWriteInProgress()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ SendBinary() [1/2]

◆ SendBinary() [2/2]

◆ SendBinaryFragment() [1/2]

◆ SendBinaryFragment() [2/2]

◆ SendFragment() [1/2]

◆ SendFragment() [2/2]

◆ SendFrames()

◆ SendPing() [1/3]

◆ SendPing() [2/3]

◆ SendPing() [3/3]

◆ SendPong() [1/3]

◆ SendPong() [2/3]

◆ SendPong() [3/3]

◆ SendText() [1/2]

◆ SendText() [2/2]

◆ SendTextFragment() [1/2]

◆ SendTextFragment() [2/2]

◆ SetCombineFragments()

◆ SetData()

◆ SetMaxMessageSize()

◆ Shutdown()

◆ Terminate()

◆ TrySendFrames()

Member Data Documentation

◆ binary

◆ closed

◆ kFlagControl

◆ kFlagFin

◆ kOpBinary

◆ kOpClose

◆ kOpCont

◆ kOpMask

◆ kOpPing

◆ kOpPong

◆ kOpText

◆ open

◆ ping

◆ pong

◆ text