WPILibC++ 2024.3.2
wpi::WebSocket Class Reference

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
 
WebSocketoperator= (const WebSocket &)=delete
 
WebSocketoperator= (WebSocket &&)=delete
 
 ~WebSocket ()
 
State GetState () const
 Get connection state. More...
 
bool IsOpen () const
 Return if the connection is open. More...
 
uv::StreamGetStream () 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 FrameTrySendFrames (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< WebSocketCreateClient (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< WebSocketCreateClient (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< WebSocketCreateServer (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_viewopen
 Open event. More...
 
sig::Signal< uint16_t, std::string_viewclosed
 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

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
codeA numeric status code (defaults to 1005, no status code)
reasonA 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
streamConnection stream
uriThe Request-URI to send
hostThe host or host:port to send
protocolsThe list of subprotocols
optionsHandshake 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
streamConnection stream
uriThe Request-URI to send
hostThe host or host:port to send
protocolsThe list of subprotocols
optionsHandshake 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
streamConnection stream
keyThe value of the Sec-WebSocket-Key header field in the client request
versionThe value of the Sec-WebSocket-Version header field in the client request
protocolThe 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
dataData to send
callbackCallback 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
dataData to send
callbackCallback 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
dataData to send
callbackCallback 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
dataData to send
callbackCallback 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
dataData to send
finSet to true if this is the final fragment of the message
callbackCallback 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
dataData to send
finSet to true if this is the final fragment of the message
callbackCallback 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
framesFrame type/data pairs
callbackCallback 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
callbackOptional 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
dataData to send in the ping frame
callbackCallback 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
dataData to send in the ping frame
callbackCallback 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
callbackOptional 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
dataData to send in the pong frame
callbackCallback 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
dataData to send in the pong frame
callbackCallback 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
dataUTF-8 encoded data to send
callbackCallback 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
dataUTF-8 encoded data to send
callbackCallback 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
dataUTF-8 encoded data to send
callbackCallback 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
dataUTF-8 encoded data to send
callbackCallback 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
combineTrue if fragmented frames should be combined.

◆ SetData()

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

Sets user-defined data.

Parameters
dataUser-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
sizeMaximum 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
framesFrame type/data pairs
callbackCallback 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: