tufao  1.3.0
An asynchronous web framework for C++ built on top of Qt
Tufao::WebSocket Class Reference

This class represents a WebSocket connection. More...

+ Inheritance diagram for Tufao::WebSocket:
+ Collaboration diagram for Tufao::WebSocket:

Public Slots

void close () override
 
bool sendMessage (const QByteArray &msg) override
 
bool sendBinaryMessage (const QByteArray &msg)
 Sends a binary message over the connection. More...
 
bool sendUtf8Message (const QByteArray &msg)
 Sends a UTF-8 text message over the connection. More...
 
bool ping (const QByteArray &data)
 Sends a ping frame over the connection. More...
 
- Public Slots inherited from Tufao::AbstractMessageSocket
virtual void close ()=0
 This method should close the connection.
 
virtual bool sendMessage (const QByteArray &msg)=0
 This method should send a new message if the connection is open. More...
 

Signals

void pong (QByteArray data)
 This signal is emitted when a pong frame is received. More...
 
- Signals inherited from Tufao::AbstractMessageSocket
void connected ()
 This signal should be emitted when the connection is open. More...
 
void disconnected ()
 This signal should be emitted when the connection is closed or when fails to connect. More...
 
void newMessage (QByteArray msg)
 This signal should be emitted each time a new message is available. More...
 

Public Member Functions

 WebSocket (QObject *parent=0)
 Constructs a Tufao::WebSocket object. More...
 
 ~WebSocket ()
 Destroys the object.
 
bool connectToHost (const QHostAddress &address, quint16 port, const QByteArray &resource, const Headers &headers=Headers())
 Execute the steps to establish a WebSocket connection with the server represented by address and port on the given resource. More...
 
bool connectToHost (const QHostAddress &address, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool connectToHost (const QString &hostname, quint16 port, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool connectToHost (const QString &hostname, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool connectToHostEncrypted (const QString &hostname, quint16 port, const QByteArray &resource, const Headers &headers, const QList< QSslError > &ignoredSslErrors)
 The same as WebSocket::connectToHost, but uses a TLS connection. More...
 
bool connectToHostEncrypted (const QString &hostname, quint16 port, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function.
 
bool connectToHostEncrypted (const QString &hostname, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool connectToHostEncrypted (const QHostAddress &address, quint16 port, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool connectToHostEncrypted (const QHostAddress &address, const QByteArray &resource, const Headers &headers=Headers())
 This is an overloaded function. More...
 
bool startServerHandshake (const HttpServerRequest &request, const QByteArray &head, const Headers &headers=Headers())
 It establish a WebSocket connection initiated by request with head data. More...
 
bool startServerHandshake (HttpServerRequest &request, const Headers &headers=Headers())
 This is an overloaded function. More...
 
void setMessagesType (WebSocketMessageType type)
 Set the type of messages sent through WebSocket::sendMessage method. More...
 
WebSocketMessageType messagesType () const
 Return the current type of messages what will be sent through WebSocket::sendMessage method. More...
 
WebSocketError error () const
 Returns the type of last error that occurred.
 
QString errorString () const
 Returns a human-readable description of the last error that occurred.
 
QHostAddress peerAddress () const
 Returns the address of the connected peer. More...
 
quint16 peerPort () const
 Returns the port of the connected peer. More...
 
- Public Member Functions inherited from Tufao::AbstractMessageSocket
 AbstractMessageSocket (QObject *parent=0)
 Constructs a Tufao::AbstractMessageSocket object. More...
 
bool isConnected () const
 Returns true if the connection is open.
 

Static Public Member Functions

static QList< QByteArray > supportedProtocols (const Headers &headers)
 It reads the supported sub-protocols from the appropriate fields and return them.
 

Additional Inherited Members

- Properties inherited from Tufao::AbstractMessageSocket
bool connected
 

Detailed Description

This class represents a WebSocket connection.

WebSocket is a protocol designed to allow HTTP user agents and servers communicates using a two-way protocol. It's possible to upgrade an established HTTP connection to a WebSocket connection.

WebSocket server

If you intend to create a server able to accept WebSocket connections, you must create a HTTP server and create a handler to upgrade events.

In the handler for the upgrade event, you must create a new WebSocket object and call the method startServerHandshake. This method will send the initial WebSocket server payload and check if it's a valid WebSocket connection request.

WebSocket client

If you intend to connect to a WebSocket server, you must call one of the connectToHost methods. If the connection should be encrypted, then call one of the connectToHostEncrypted methods. The connected signal will emitted when the socket is ready.

See also
Tufao::AbstractMessageSocket
Since
0.2

Constructor & Destructor Documentation

Tufao::WebSocket::WebSocket ( QObject *  parent = 0)
explicit

Constructs a Tufao::WebSocket object.

parent is passed to the QObject constructor.

Member Function Documentation

bool Tufao::WebSocket::connectToHost ( const QHostAddress &  address,
quint16  port,
const QByteArray &  resource,
const Headers headers = Headers() 
)

Execute the steps to establish a WebSocket connection with the server represented by address and port on the given resource.

You can send extra headers in the WebSocket opening handshake request using the headers argument.

Note
Optional headers such as Origin aren't added by default. If you want to use one of the headers, you should add them explicitly. The list of common optional headers is the following:
  • Origin: RFC 6454. If your software is a browser client, this field is mandatory, not optional.
  • Sec-WebSocket-Protocol: If present, this value indicates one or more comma-separated subprotocol the client wishes to speak, ordered by preference.
If the object fail to establish a connection, it will emit disconnected signal. If it procceds, it will emit the connected signal.
bool Tufao::WebSocket::connectToHost ( const QHostAddress &  address,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

It uses port 80 to establish the connection.

bool Tufao::WebSocket::connectToHost ( const QString &  hostname,
quint16  port,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

Since
0.3
bool Tufao::WebSocket::connectToHost ( const QString &  hostname,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

It uses port 80 to establish the connection.

Since
0.3
bool Tufao::WebSocket::connectToHostEncrypted ( const QString &  hostname,
quint16  port,
const QByteArray &  resource,
const Headers headers,
const QList< QSslError > &  ignoredSslErrors 
)

The same as WebSocket::connectToHost, but uses a TLS connection.

ignoredSslErrors is passed to QSslSocket::ignoreSslErrors.

See also
Tufao::WebSocket::connectToHost
Since
1.1
bool Tufao::WebSocket::connectToHostEncrypted ( const QString &  hostname,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

It uses port 443 to establish the connection.

bool Tufao::WebSocket::connectToHostEncrypted ( const QHostAddress &  address,
quint16  port,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

See also
Tufao::WebSocket::connectToHost
Since
0.3
bool Tufao::WebSocket::connectToHostEncrypted ( const QHostAddress &  address,
const QByteArray &  resource,
const Headers headers = Headers() 
)

This is an overloaded function.

It uses port 443 to establish the connection.

Since
0.3
WebSocketMessageType Tufao::WebSocket::messagesType ( ) const

Return the current type of messages what will be sent through WebSocket::sendMessage method.

See also
Tufao::WebSocket::setMessagesType
QHostAddress Tufao::WebSocket::peerAddress ( ) const

Returns the address of the connected peer.

Return values
QHostAddress::Nullif the socket is not in ConnectedState.
Since
0.5
quint16 Tufao::WebSocket::peerPort ( ) const

Returns the port of the connected peer.

Return values
0if the socket is not in ConnectedState.
Since
0.5
bool Tufao::WebSocket::ping ( const QByteArray &  data)
slot

Sends a ping frame over the connection.

A WebSocket peer that receives a ping frame must respond with a pong frame as soon as pratical.

You can use a ping frame to measure the connection lag, to test the connectivity availability, among other.

void Tufao::WebSocket::pong ( QByteArray  data)
signal

This signal is emitted when a pong frame is received.

Pong frames are sent in response to ping frames.

Note
This signal is unsafe (read this: Safe signals)!
See also
WebSocket::ping
bool Tufao::WebSocket::sendBinaryMessage ( const QByteArray &  msg)
slot

Sends a binary message over the connection.

See also
WebSocket::sendMessage WebSocket::messagesType
bool Tufao::WebSocket::sendUtf8Message ( const QByteArray &  msg)
slot

Sends a UTF-8 text message over the connection.

See also
WebSocket::sendMessage WebSocket::messagesType
void Tufao::WebSocket::setMessagesType ( WebSocketMessageType  type)

Set the type of messages sent through WebSocket::sendMessage method.

Note
Another way of choose the type of sent messages is through WebSocket::sendBinaryMessage and WebSocket::sendUtf8Message methods.
The default value is BINARY_MESSAGE
bool Tufao::WebSocket::startServerHandshake ( const HttpServerRequest request,
const QByteArray &  head,
const Headers headers = Headers() 
)

It establish a WebSocket connection initiated by request with head data.

The method send the initial WebSocket server payload and check if it's a valid WebSocket connection request.

Note
You should call this function only after request emitts the Tufao::HttpServerRequest::upgrade signal.
Note
Tufao::WebSocket won't treat optional headers found in request. If you want to respond to these headers in the opening handshake response, just put the headers you want to send in the response in the headers argument. Some headers you may want to treat are:
  • Origin: Compare the Origin to the Host to block malicious scripts coming from web browsers.
  • Cookie
  • Sec-WebSocket-Protocol: The subprotocol the client wishes to speak.
Note
If you want to perform additional client authentication, you should start the handshake only after the authentication occurs. You can use the 401 status code with "WWW-Authenticate" header to perform the authentication, among other methods.
Note
You can use a 3xx status code to redirect the client.
Note
If the handshake fail, the method will write the appropriate message to the socket and return false.
Since
1.0
bool Tufao::WebSocket::startServerHandshake ( HttpServerRequest request,
const Headers headers = Headers() 
)

This is an overloaded function.

It uses HttpServerRequest::readBody to figure out the head argument.

Since
1.0

The documentation for this class was generated from the following file: