This class represents a WebSocket connection. More...

Inheritance diagram for Tufao::WebSocket:

Collaboration diagram for Tufao::WebSocket:

Public Types
enum	Error { NO_ERROR = 0, CONNECTION_REFUSED, REMOTE_HOST_CLOSED, HOST_NOT_FOUND, ACCESS_ERROR, OUT_OF_RESOURCES, SOCKET_TIMEOUT, NETWORK_ERROR, UNSUPPORTED_SOCKET_OPERATION, PROXY_AUTHENTICATION_REQUIRED, SSL_HANDSHAKE_FAILED, PROXY_CONNECTION_REFUSED, PROXY_CONNECTION_CLOSED, PROXY_CONNECTION_TIMEOUT, PROXY_NOT_FOUND, PROXY_PROTOCOL_ERROR, WEBSOCKET_HANDSHAKE_FAILED, WEBSOCKET_PROTOCOL_ERROR, UNKNOWN_ERROR }
	This enum describes the possible erros tha can occur. More...

enum	MessageType { TEXT_MESSAGE, BINARY_MESSAGE }
	This enum represents the possible message's types that WebSocket supports. More...

Public Slots
void	close ()

bool	sendMessage (const QByteArray &msg)

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

void	setMessagesType (MessageType type)
	Set the type of messages sent through WebSocket::sendMessage method. More...

MessageType	messagesType () const
	Return the current type of messages what will be sent through WebSocket::sendMessage method. More...

Error	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

Member Enumeration Documentation

enum Tufao::WebSocket::Error

This enum describes the possible erros tha can occur.

Note: Avoid to directly test against NO_ERROR, because Windows API defines the NO_ERROR macro and your code might fail to build under this plataform. You can safely make a test using code like the following:; if (ws.error())

/* ... */;

Enumerator
NO_ERROR	No error.
CONNECTION_REFUSED	See QAbstractSocket::ConnectionRefusedError. It can happen during the opening handshake (only when acting as client).
REMOTE_HOST_CLOSED	See QAbstractSocket::RemoteHostClosedError. It can happen during the opening handshake (only when acting as client).
HOST_NOT_FOUND	See QAbstractSocket::HostNotFoundError. It can happen during the opening handshake (only when acting as client).
ACCESS_ERROR	See QAbstractSocket::SocketAccessError. It can happen during the opening handshake (only when acting as client).
OUT_OF_RESOURCES	See QAbstractSocket::SocketResourceError. It can happen during the opening handshake (only when acting as client).
SOCKET_TIMEOUT	See QAbstractSocket::SocketTimeoutError. It can happen during the opening handshake (only when acting as client).
NETWORK_ERROR	See QAbstractSocket::NetworkError. It can happen during the opening handshake (only when acting as client).
UNSUPPORTED_SOCKET_OPERATION	See QAbstractSocket::UnsupportedSocketOperationError. It can happen during the opening handshake (only when acting as client).
PROXY_AUTHENTICATION_REQUIRED	See QAbstractSocket::ProxyAuthenticationRequiredError. It can happen during the opening handshake (only when acting as client).
SSL_HANDSHAKE_FAILED	See QAbstractSocket::SslHandshakeFailedError. It can happen during the opening handshake (only when acting as client).
PROXY_CONNECTION_REFUSED	See QAbstractSocket::ProxyConnectionRefusedError. It can happen during the opening handshake (only when acting as client).
PROXY_CONNECTION_CLOSED	See QAbstractSocket::ProxyConnectionClosedError. It can happen during the opening handshake (only when acting as client).
PROXY_CONNECTION_TIMEOUT	See QAbstractSocket::ProxyConnectionTimeoutError. It can happen during the opening handshake (only when acting as client).
PROXY_NOT_FOUND	See QAbstractSocket::ProxyNotFoundError. It can happen during the opening handshake (only when acting as client).
PROXY_PROTOCOL_ERROR	See QAbstractSocket::ProxyProtocolError. It can happen during the opening handshake (only when acting as client).
WEBSOCKET_HANDSHAKE_FAILED	It occurs when the server doesn't support WebSocket for the resource asked for (or for any resource at all). It can happen during the opening handshake (only when acting as client).
WEBSOCKET_PROTOCOL_ERROR	It occurs when the remote peer (or an intermediary) violates the WebSocket protocol.
UNKNOWN_ERROR	Uknown error. You found the chaos.

enum Tufao::WebSocket::MessageType

This enum represents the possible message's types that WebSocket supports.

Enumerator
TEXT_MESSAGE	UTF8 messages.
BINARY_MESSAGE	Binary messages.

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: 0.7

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

MessageType 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::Null if the socket is not in ConnectedState.

Since: 0.5

quint16 Tufao::WebSocket::peerPort ( ) const

Returns the port of the connected peer.

Return values

0	if 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 ( MessageType 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.

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

websocket.h

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

WebSocket server

WebSocket client

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation