Wt
4.11.1
|
A resource that manages a WebSocket endpoint. More...
#include <Wt/WWebSocketResource.h>
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. 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< 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. 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... | |
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.
|
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.
std::string Wt::WWebSocketResource::internalPath | ( | ) | const |
Retrieves the current internal path.
size_t Wt::WWebSocketResource::maximumReceivedFrameSize | ( | ) | const |
Returns the maximum size of a single received frame.
size_t Wt::WWebSocketResource::maximumReceivedMessageSize | ( | ) | const |
Returns the maximum received size of a single message.
int Wt::WWebSocketResource::pingInterval | ( | ) | const |
Returns the interval (in seconds) between ping frames sent.
int Wt::WWebSocketResource::pingTimeout | ( | ) | const |
Returns the maximum duration (in second) between sent ping frames, and received pong frames.
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.
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.
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.
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.
|
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.
bool Wt::WWebSocketResource::takesUpdateLock | ( | ) | const |
Returns whether the application update lock is used.
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.