Wt::WWebSocketResource Class Reference

A resource that manages a WebSocket endpoint. More...

#include <Wt/WWebSocketResource.h>

Inheritance diagram for Wt::WWebSocketResource:

Public Member Functions
	WWebSocketResource ()
	Default constructor.
virtual	~WWebSocketResource ()
	Destructor.
virtual std::unique_ptr< WWebSocketConnection >	handleConnect (const Http::Request &request)=0
	Handles a new connection to the resource.
virtual void	shutdown ()
	Shuts down the resource.
void	setInternalPath (const std::string &path)
	Configures the internal path used for the resource.
std::string	internalPath () const
	Retrieves the current internal path.
std::string	url () const
	Retrieves the current URL.
void	setMaximumReceivedSize (size_t frame, size_t message)
	Sets the maximum received frame and message sizes.
void	setTakesUpdateLock (bool canTake)
	Sets whether the resource takes the update lock on events.
void	setPingTimeout (int intervalSeconds, int timeoutSeconds)
	Sets the ping-pong configuration.
size_t	maximumReceivedFrameSize () const
	Returns the maximum size of a single received frame.
size_t	maximumReceivedMessageSize () const
	Returns the maximum received size of a single message.
bool	takesUpdateLock () const
	Returns whether the application update lock is used.
int	pingInterval () const
	Returns the interval (in seconds) between ping frames sent.
int	pingTimeout () const
	Returns the maximum duration (in second) between sent ping frames, and received pong frames.
Public Member Functions inherited from Wt::WObject
void	addChild (std::unique_ptr< WObject > child)
	Add a child WObject whose lifetime is determined by this WObject.
template<typename Child >
Child *	addChild (std::unique_ptr< Child > child)
	Add a child WObject, returning a raw pointer.
std::unique_ptr< WObject >	removeChild (WObject *child)
	Remove a child WObject, so its lifetime is no longer determined by this WObject.
template<typename Child >
std::unique_ptr< Child >	removeChild (Child *child)
	Remove a child WObject, so its lifetime is no longer determined by this WObject.
virtual const std::string	id () const
	Returns the (unique) identifier for this object.
virtual void	setObjectName (const std::string &name)
	Sets an object name.
virtual std::string	objectName () const
	Returns the object name.
void	resetLearnedSlots ()
	Resets learned stateless slot implementations.
template<class T >
void	resetLearnedSlot (void(T::*method)())
	Resets a learned stateless slot implementation.
template<class T >
WStatelessSlot *	implementStateless (void(T::*method)())
	Declares a slot to be stateless and learn client-side behaviour on first invocation.
template<class T >
WStatelessSlot *	implementStateless (void(T::*method)(), void(T::*undoMethod)())
	Declares a slot to be stateless and learn client-side behaviour in advance.
void	isNotStateless ()
	Marks the current function as not stateless.
template<class T >
WStatelessSlot *	implementJavaScript (void(T::*method)(), const std::string &jsCode)
	Provides a JavaScript implementation for a method.
Public Member Functions inherited from Wt::Core::observable
	observable () noexcept
	Default constructor.
virtual	~observable ()
	Destructor.
template<typename... Args, typename C >
auto	bindSafe (void(C::*method)(Args...)) noexcept
	Protects a method call against object destruction.
template<typename... Args, typename C >
auto	bindSafe (void(C::*method)(Args...) const) const noexcept
	Protects a const method call against object destruction.
template<typename Function >
auto	bindSafe (const Function &function) noexcept
	Protects a function against object destruction.

Additional Inherited Members
Public Types inherited from Wt::WObject
typedef void(WObject::*	Method) ()
	Typedef for a WObject method without arguments.
Protected Member Functions inherited from Wt::WObject
virtual WStatelessSlot *	getStateless (Method method)
	On-demand stateless slot implementation.

Detailed Description

A resource that manages a WebSocket endpoint.

This resource enables the creation of endpoints that can be accessed to set up WebSocket connections. This implementation adheres to RFC-6455. The implementation does not support Sec-WebSocket-Protocol or Sec-WebSocket-Extension.

Like WResource, a WWebSocketResource can be global (aka static) or session-private (aka dynamic). A global WWebSocketResource is deployed at a fixed URL by calling WServer::addResource(). It is accessible by anybody that has access to its URL. It is the responsibility of the developer to implement a suitable access control mechanism if needed.

The private version of this is an endpoint unique for a session. It is added to the widget tree of a WApplication instance (and WServer::addResource() is thus not used). The URL is generated by Wt and access is protected to the session by using a session-specific secret as configured by the 'tracking' configuration option in wt_config.xml. Its path can still be managed, and set to any valid name.

This class enables an endpoint to be created (and moved, using setInternalPath()).

While it has Resource in its name, it is not actually a WResource, and has no WResource::handleRequest() method.

When a new connection comes in to the WWebSocketResource, that is a valid WebSocket request, asking to be upgraded, handleConnect() will be called. This creates a new instance of a WWebSocketConnection. This connection can be used to send and receive data over. Upon creation, all state that is configured on the resource is also put on the connection, meaning the limits on frame and message size, the ping delay and timeout, and whether the update lock is taken on updates.

To use this resource, one has to implement the handleConnect() method, which should create a WWebSocketConnection. Or any specialized class that inherits from it.

class MyWebSocketResource final : public Wt::WWebSocketResource
{
public:
  std::unique_ptr<Wt::WWebSocketConnection> handleConnect(const Wt::Http::Request& request) final
  {
    auto connection = std::make_unique<Wt::WWebSocketConnection>(this, Wt::WServer::instance()->ioService());
    newConnectionMade_.emit(connection.get());
    return connection;
  }
};

Note

This class is only supported when using the wthttp frontend.

Member Function Documentation

handleConnect()

virtual std::unique_ptr< WWebSocketConnection > Wt::WWebSocketResource::handleConnect ( const Http::Request &  request )

pure virtual

Handles a new connection to the resource.

When a new connection is being made to the resource, this function is called, to create a new WWebSocketConnection.

The connection can be used to interact with the WebSocket stream. The request that is passed to it is purely indicative. It allows for inspection of the request and its headers, so that additional information from it may be used further.

internalPath()

std::string Wt::WWebSocketResource::internalPath

(

)

const

Retrieves the current internal path.

See also

setInternalPath

maximumReceivedFrameSize()

size_t Wt::WWebSocketResource::maximumReceivedFrameSize

(

)

const

Returns the maximum size of a single received frame.

See also

setMaximumReceivedSize

maximumReceivedMessageSize()

size_t Wt::WWebSocketResource::maximumReceivedMessageSize

(

)

const

Returns the maximum received size of a single message.

See also

setMaximumReceivedSize

Note

A single message can span multiple frames.

pingInterval()

int Wt::WWebSocketResource::pingInterval

(

)

const

Returns the interval (in seconds) between ping frames sent.

See also

setPingTimeout

pingTimeout()

int Wt::WWebSocketResource::pingTimeout

(

)

const

Returns the maximum duration (in second) between sent ping frames, and received pong frames.

See also

setPingTimeout

setInternalPath()

void Wt::WWebSocketResource::setInternalPath

(

const std::string &

path

)

Configures the internal path used for the resource.

This path is only useful for private resources. It defines the internal path portion of the URL of the resource.

If no path is configured, a URL will be generated by the library.

setMaximumReceivedSize()

void Wt::WWebSocketResource::setMaximumReceivedSize	(	size_t	frame,
		size_t	message
	)

Sets the maximum received frame and message sizes.

A WebSocket frame is a single transaction unit. It contains a header and data. The header itself will contain information on the frame, and specify how long it is. If this exceeds the limit, the received frame is discarded.

Likewise, when a received message consists of multiple frames, the message as a whole is discarded if it exceeds the message limit.

By default the maximum frame size is 10MB (1024 * 1024 * 10), and the maxmimum message size is 5 times as big (50MB). This can be increased to any arbitrary value, but the absolute maximum frame size of a WebSocket is still enforced, which is 2 ^ 63 bytes.

setPingTimeout()

void Wt::WWebSocketResource::setPingTimeout	(	int	intervalSeconds,
		int	timeoutSeconds
	)

Sets the ping-pong configuration.

The ping-pong system is a way to ensure that a connection remains active, and that both parties are still committed to the interaction. Any of both parties can send a ping frame, to which the other has to respond with a pong as soon as reasonable. They do not have to drop current pending frames, but need to ensure that the pong is sent out within a reasonable small amount of time.

This function allows the managing of this functionality. The first parameter intervalSeconds will set every how often a ping frame is sent out from the server to a connected client. The second parameter timeoutSeconds indicates how long the client has to respond. If they do not respond within the set limit, the connection will be considered dropped, and will be terminated. Both of these parameters are in seconds.

By default the used values are 30 seconds for the ping interval, and 60 seconds for the timeout.

This system can be disabled by setting intervalSeconds to 0.

setTakesUpdateLock()

void Wt::WWebSocketResource::setTakesUpdateLock

(

bool

canTake

)

Sets whether the resource takes the update lock on events.

Setting this to true will only affect private resources. By default it is enabled.

If enabled, handleConnect(), WWebSocketResource::handleMessage(), WWebSocketResource::handleError(), WWebSocketResource::closed(), and WWebSocketResource::done() are all called while holding the WApplication::UpdateLock. The widget tree can thus safely be accessed and modified from these functions.

shutdown()

void Wt::WWebSocketResource::shutdown ( )

virtual

Shuts down the resource.

The resource is closed down, meaning that all its active connections are immediately closed. This is not a completely graceful shutdown, in that clients (on the other side of the connection) are not notified of the closing with a close frame. This could potentially lead to the resource having to wait a while for an actual shutdown.

Since this function is called in WServer::stop(), in case the Wt http library is used, we want an immediate shutdown here.

takesUpdateLock()

bool Wt::WWebSocketResource::takesUpdateLock

(

)

const

Returns whether the application update lock is used.

See also

setTakesUpdateLock

url()

std::string Wt::WWebSocketResource::url

(

)

const

Retrieves the current URL.

This method returns the full URL to be used to connect to this resource.

For global resources, this is the last URL at which the resource is added to WServer. For private resources, this URL is influenced by setInternalPath() and additional query parameters to provide session secrecy.

See also

setInternalPath