A single connection to a WWebSocketResource. More...
#include <Wt/WWebSocketConnection.h>
Public Member Functions | |
| WWebSocketConnection (WWebSocketResource *resource, AsioWrapper::asio::io_service &ioService) | |
| Constructor, pointing to its resource and the IO service. | |
| virtual | ~WWebSocketConnection () |
| Destructor. | |
| virtual void | handleMessage (const std::string &text) |
| Handles an incoming text message. More... | |
| virtual void | handleMessage (const std::vector< char > &buffer) |
| Handles an incoming binary message. More... | |
| virtual bool | sendMessage (const std::string &text) |
| Sends out a text message. More... | |
| virtual bool | sendMessage (const std::vector< char > &buffer) |
| Sends out a binary message. More... | |
| virtual bool | close (CloseCode code, const std::string &reason="") |
| Send the close signal to the client. More... | |
| virtual void | acknowledgeClose (const std::string &reason="") |
| Acknowledges a received close frame. More... | |
| virtual bool | sendPing () |
| Sends out a ping message. More... | |
| virtual void | acknowledgePing () |
| Acknowlegdes a received ping message. More... | |
| virtual void | handlePong () |
| Handles an incoming pong message. More... | |
| virtual void | handleError () |
| Handles an incoming bad frame. More... | |
| void | setMaximumReceivedSize (std::size_t frameSize, std::size_t messageSize) |
| Sets the maximum received frame and message size. More... | |
| void | setTakesUpdateLock (bool takesUpdateLock) |
| Sets the application update lock needs to be taken on sending or receiving messages. More... | |
| void | setPingTimeout (int pingInterval, int pingTimeout) |
| Sets the ping-pong configuration. More... | |
| Signal< AsioWrapper::error_code > & | done () |
| Signal indicating a sending event has been completed. More... | |
| Signal< AsioWrapper::error_code, const std::string & > & | closed () |
| Signal indicating the connection has been closed. 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... | |
Detailed Description
A single connection to a WWebSocketResource.
When a connection is set-up to a WWebSocketResource, a new connection is created, which manages the underlying TCP or SSL stream.
Upon its creation, it will inherit the setting currently found on the WWebSocketResource. Like the maximum frame and message sizes, the settings for the ping-pong system and whether it takes the application update lock.
The connection can be used to listen to incoming requests, or send out messages after the WebSocket set-up has occurred. It also offers methods to manage the connection, like closing it gracefully.
Each of the methods that either read an incoming message, or respond to a message are made virtual so that developers can change the implementation slightly, if they desire. This will be limited to being able to log, track, or manipulate the data, but not change the way the framework will create frames or messages.
Most socket, and data management is still handled by the framework. That is, everything to do with any of the above mentioned methods, copied from WWebSocketResource, is handled by the framework. A developer will thus never be able to receive a message or frame greater than the imposed limit, unless they increase it, or disable it. If the setTakesUpdateLock() is set to true, this lock acquisition will always take place. These settings can always be changed after the connection has been set up.
Member Function Documentation
◆ acknowledgeClose()
|
virtual |
Acknowledges a received close frame.
A client has sent out a close frame, to which the server responds with an identical message. It sends out a frame with the same code and optionally the same reason.
Since this is a final response, it does not fall within the normal sending/done() logic. It does still write a frame to the client, but the response here is not important. The done() signal will be fired, and used internally, eventually firing the closed() signal. Which is used to indicate that the stream will be closed down and is to be considered unusable from now on.
◆ acknowledgePing()
|
virtual |
Acknowlegdes a received ping message.
The client has sent out a ping message. The server now needs to respond with a pong.
◆ close()
|
virtual |
Send the close signal to the client.
This will close the connection in a graceful manner. After the closing frame is sent out, the connection waits for it to be acknowledged by the client. Once this has been received, the connection will be actually terminated.
When sending this message, the code will indicate a generic cause for termination. Generally CloseCode::Normal will be most often used. An optional reason can be provided to the client as an additional specification to the generic code.
This method is also considered a sending event, meaning that it also blocks an additional writing events, until done() has been emitted.
◆ closed()
| Signal<AsioWrapper::error_code, const std::string&>& Wt::WWebSocketConnection::closed | ( | ) |
Signal indicating the connection has been closed.
The error code it returns either does not exists, indicating a successful close. Or it can exist, and will then have a value. The number of the value signifies which type of error has occurred. Even if an error occurs the underlying stream should never be used again, since it is very likely the client has already closed the stream from their end.
The string returned can hold an optional message, which specifies why the connection was closed.
◆ done()
| Signal<AsioWrapper::error_code>& Wt::WWebSocketConnection::done | ( | ) |
Signal indicating a sending event has been completed.
The error code it returns either does not exists, indicating a successful write. Or it can exist, and will then have a value. The number of the value signifies which type of error has occurred. This can leave the underlying stream useless.
◆ handleError()
|
virtual |
Handles an incoming bad frame.
A frame was received that was not expected. Currently this is only used for when a continuation frame is caught, but no initial frame to which the continuation should apply, was received first.
◆ handleMessage() [1/2]
|
virtual |
Handles an incoming text message.
A single message (which can consist of multiple frames) has been received, of the text type. The text parameter contains the data that was present in the message.
◆ handleMessage() [2/2]
|
virtual |
Handles an incoming binary message.
A single message (which can consist of multiple frames) has been received, of the binary type. The buffer parameter contains the data that was present in the message.
◆ handlePong()
|
virtual |
Handles an incoming pong message.
A pong message has been sent by the client, meaning that earlier the server has sent out a ping message with sendPing().
This ensures that the ping-pong mechanism is complete. When this method is called, this indicates a full cycle of the ping-pong logic. This will set up the timer (if it is enabled) again.
◆ sendMessage() [1/2]
|
virtual |
Sends out a text message.
This will create a single text message that is to be sent to the client. The text data will be added to the message. The message is sent out as a single frame. This method can only be called in a sequential manner. Meaning that after each send event, a done() will be called, and no other send can be executed before the done() signal has been emitted. If this is called before done() fired, and thus when the previous message is still being written, the function will return false, and a warning will be logged.
Upon success, this will return true. This does not indicate that the message has been actually sent, but that it has been successfully queued. When the message has been written to the stream, done() will be called. When done() is fired, the queued message has been handled. This can mean that is has been successfully written, or that and error has occurred. If an error is attached to the done() signal, an error has occurred during sending, and the stream is potentially useless, depending on the type of error.
◆ sendMessage() [2/2]
|
virtual |
Sends out a binary message.
This will create a single binary message that is to be sent to the client. The buffer data will be added to the message. The message is sent out as a single frame. This method can only be called in a sequantial manner. Meaning that after each send event, a done() will be called, and no other send can be executed before the done() signal has been emitted. If this is called before done() fired, and thus when the previous message is still being written, the function will return false, and a warning will be logged.
Upon success, this will return true. This does not indicate that the message has been actually sent, but that it has been successfully queued. When the message has been written to the stream, done() will be called. When done() is fired, the queued message has been handled. This can mean that is has been successfully written, or that and error has occurred. If an error is attached to the done() signal, an error has occurred during sending, and the stream is potentially useless, depending on the type of error.
◆ sendPing()
|
virtual |
Sends out a ping message.
This sends out a ping message to the connected client. This will happen every x seconds where x is set by setPingTimeout().
◆ setMaximumReceivedSize()
| void Wt::WWebSocketConnection::setMaximumReceivedSize | ( | std::size_t | frameSize, |
| std::size_t | messageSize | ||
| ) |
Sets the maximum received frame and message size.
◆ setPingTimeout()
| void Wt::WWebSocketConnection::setPingTimeout | ( | int | pingInterval, |
| int | pingTimeout | ||
| ) |
Sets the ping-pong configuration.
◆ setTakesUpdateLock()
| void Wt::WWebSocketConnection::setTakesUpdateLock | ( | bool | takesUpdateLock | ) |
Sets the application update lock needs to be taken on sending or receiving messages.
