Wt  4.11.1
Public Member Functions | List of all members
Wt::WWebSocketResource Class Referenceabstract

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

#include <Wt/WWebSocketResource.h>

Inheritance diagram for Wt::WWebSocketResource:
[legend]

Public Member Functions

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

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. More...
 

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;
}
};
A resource request.
Definition: Request.h:131
static WServer * instance()
Returns the server instance.
Definition: WServer.h:215
A resource that manages a WebSocket endpoint.
Definition: WWebSocketResource.h:114
virtual std::unique_ptr< WWebSocketConnection > handleConnect(const Http::Request &request)=0
Handles a new connection to the resource.
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