Wt  4.11.0
Loading...
Searching...
No Matches
Public Member Functions | List of all members
Wt::WWebSocketConnection Class Reference

A single connection to a WWebSocketResource. More...

#include <Wt/WWebSocketConnection.h>

Inheritance diagram for Wt::WWebSocketConnection:
[legend]

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.
 
virtual void handleMessage (const std::vector< char > &buffer)
 Handles an incoming binary message.
 
virtual bool sendMessage (const std::string &text)
 Sends out a text message.
 
virtual bool sendMessage (const std::vector< char > &buffer)
 Sends out a binary message.
 
virtual bool close (CloseCode code, const std::string &reason="")
 Send the close signal to the client.
 
virtual void acknowledgeClose (const std::string &reason="")
 Acknowledges a received close frame.
 
virtual bool sendPing ()
 Sends out a ping message.
 
virtual void acknowledgePing ()
 Acknowlegdes a received ping message.
 
virtual void handlePong ()
 Handles an incoming pong message.
 
virtual void handleError ()
 Handles an incoming bad frame.
 
void setMaximumReceivedSize (std::size_t frameSize, std::size_t messageSize)
 Sets the maximum received frame and message size.
 
void setTakesUpdateLock (bool takesUpdateLock)
 Sets the application update lock needs to be taken on sending or receiving messages.
 
void setPingTimeout (int pingInterval, int pingTimeout)
 Sets the ping-pong configuration.
 
Signal< AsioWrapper::error_code > & done ()
 Signal indicating a sending event has been completed.
 
Signal< AsioWrapper::error_code, const std::string & > & closed ()
 Signal indicating the connection has been closed.
 
- 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 >
ChildaddChild (std::unique_ptr< Child > child)
 Add a child WObject, returning a raw pointer.
 
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< ChildremoveChild (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 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()

void Wt::WWebSocketConnection::acknowledgeClose ( const std::string &  reason = "")
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()

void Wt::WWebSocketConnection::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()

bool Wt::WWebSocketConnection::close ( CloseCode  code,
const std::string &  reason = "" 
)
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()

void Wt::WWebSocketConnection::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]

void Wt::WWebSocketConnection::handleMessage ( const std::string &  text)
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]

void Wt::WWebSocketConnection::handleMessage ( const std::vector< char > &  buffer)
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()

void Wt::WWebSocketConnection::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]

bool Wt::WWebSocketConnection::sendMessage ( const std::string &  text)
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]

bool Wt::WWebSocketConnection::sendMessage ( const std::vector< char > &  buffer)
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()

bool Wt::WWebSocketConnection::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.

See also
WWebSocketResource::setMaximumReceivedSize

◆ setPingTimeout()

void Wt::WWebSocketConnection::setPingTimeout ( int  pingInterval,
int  pingTimeout 
)

Sets the ping-pong configuration.

See also
WWebSocketResource::setPingTimeout

◆ setTakesUpdateLock()

void Wt::WWebSocketConnection::setTakesUpdateLock ( bool  takesUpdateLock)

Sets the application update lock needs to be taken on sending or receiving messages.

See also
WWebSocketResource::setTakesUpdateLock