The WebSocket connection class represents a connection that is built on top of an HTTP connection. More...

#include <http.h>

Inheritance diagram for mi::http::IWeb_socket:

Public Types
enum	State : Uint32 { WS_STATE_INIT , WS_STATE_CONNECTING , WS_STATE_CONNECTED , WS_STATE_CLOSING , WS_STATE_CLOSED , WS_STATE_ERROR }
	This class represents different states that a WebSocket can be in. More...

Public Types inherited from mi::base::Interface_declare< 0x52fd1beb, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Public Member Functions
virtual const char *	get_peer_address () const =0
	Returns the peer's address of the connection. More...

virtual const char *	get_local_address () const =0
	Returns the local address of the connection. More...

virtual const char *	get_url_path () const =0
	Returns the URL path that the WebSocket request is sent to. More...

virtual State	get_state () const =0
	Returns the state of the connection. More...

virtual void	set_state_handler (IWeb_socket_state_handler *handler)=0
	Sets a state handler to the WebSocket connection. More...

virtual void	set_data_handler (IWeb_socket_data_handler *handler)=0
	Sets a data handler to the WebSocket connection. More...

virtual Difference	write (neuraylib::IBuffer *buffer, bool binary_frame=false)=0
	Writes data from a buffer to the connection. More...

virtual bool	print (const char *string, bool binary_frame=false)=0
	Prints a string to the connection. More...

bool	printf (const char *string,...) __attribute__((format(printf
	Prints a string to the connection. More...

virtual void	close ()=0
	Closes the connection. More...

virtual IConnection *	get_http_connection ()=0
	Returns the HTTP connection associated with this WebSocket connection. More...

virtual void	set_max_payload (Uint64 bytes)=0
	Set the maximum payload that web socket messages can have. More...

virtual Uint64	get_max_payload ()=0
	Get the maximum payload. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Static Public Member Functions inherited from mi::base::Interface_declare< 0x52fd1beb, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed Description

The WebSocket connection class represents a connection that is built on top of an HTTP connection.

Note: For sending data, the function mi::http::IWeb_socket::write() can be used.; For receiving data, an mi::http::IWeb_socket_data_handler needs to be installed. This handler is called when new data arrives.; For handling state changes, an mi::http::IWeb_socket_state_handler needs to be installed. This handler is called whenever the WebSocket changes its state.

Member Enumeration Documentation

^◆ State

enum mi::http::IWeb_socket::State : Uint32

This class represents different states that a WebSocket can be in.

Enumerator
WS_STATE_INIT	The initial state.
WS_STATE_CONNECTING	The client has sent a request and awaits a response.
WS_STATE_CONNECTED	A connection has been established.
WS_STATE_CLOSING	The closing handshake has been started.
WS_STATE_CLOSED	The closing handshake has been completed or the or the underlying TCP connection has been closed.
WS_STATE_ERROR	An error has occurred.

Member Function Documentation

^◆ close()

virtual void mi::http::IWeb_socket::close ( )

pure virtual

Closes the connection.

^◆ get_http_connection()

virtual IConnection * mi::http::IWeb_socket::get_http_connection ( )

pure virtual

Returns the HTTP connection associated with this WebSocket connection.

^◆ get_local_address()

virtual const char * mi::http::IWeb_socket::get_local_address ( ) const

pure virtual

Returns the local address of the connection.

Returns: The local address of the connection.

^◆ get_max_payload()

virtual Uint64 mi::http::IWeb_socket::get_max_payload ( )

pure virtual

Get the maximum payload.

Returns: The maximum payload.

^◆ get_peer_address()

virtual const char * mi::http::IWeb_socket::get_peer_address ( ) const

pure virtual

Returns the peer's address of the connection.

Returns: The peer's address of the connection.

^◆ get_state()

virtual State mi::http::IWeb_socket::get_state ( ) const

pure virtual

Returns the state of the connection.

Returns: The state of the WebSocket connection.

^◆ get_url_path()

virtual const char * mi::http::IWeb_socket::get_url_path ( ) const

pure virtual

Returns the URL path that the WebSocket request is sent to.

Returns: The URL path that the WebSocket request is sent to.

^◆ print()

virtual bool mi::http::IWeb_socket::print	(	const char *	string,
		bool	binary_frame = `false`
	)

pure virtual

Prints a string to the connection.

Parameters

string	The string to be written.
binary_frame	This flag indicates whether the data will be transmitted as binary frame or as text frame. For example, HTML 5 video data needs to be transmitted as binary frames.

Returns: true, in case of success, and false in case of failure.

^◆ printf()

bool mi::http::IWeb_socket::printf	(	const char *	string,
			...
	)

Prints a string to the connection.

Parameters

string The string to be written using printf()-like format specifiers, followed by matching arguments. The formatted message is limited to 16383 characters. The string will always be transmitted as text frame (see also print()).

Returns: true, in case of success, and false in case of failure.

^◆ set_data_handler()

virtual void mi::http::IWeb_socket::set_data_handler ( IWeb_socket_data_handler * handler )

pure virtual

Sets a data handler to the WebSocket connection.

The data handler is called whenever new data arrives at the WebSocket. The data handler is a deferred callback, i.e., if data is available for reading at the WebSocket, the data handler is called after the set_data_handler() method has been executed.

The handler is removed when the connection is closed.

Parameters

handler The data handler.

^◆ set_max_payload()

virtual void mi::http::IWeb_socket::set_max_payload ( Uint64 bytes )

pure virtual

Set the maximum payload that web socket messages can have.

Defaults to 2 GB.

Parameters

bytes The maximum payload in bytes

^◆ set_state_handler()

virtual void mi::http::IWeb_socket::set_state_handler ( IWeb_socket_state_handler * handler )

pure virtual

Sets a state handler to the WebSocket connection.

The state handler is called whenever the WebSocket changes its state. The state handler is a deferred callback, i.e., it is called after the set_state_handler() method has been executed.

Note: When this method is called and the WebSocket is in the state CONNECTED, the state handler is also called back although there is no state change in this case.

The handler is removed when the connection is closed.

Parameters

handler The data handler.

^◆ write()

virtual Difference mi::http::IWeb_socket::write	(	neuraylib::IBuffer *	buffer,
		bool	binary_frame = `false`
	)

pure virtual

Writes data from a buffer to the connection.

There is no limit on the buffer size on the sender's side. However, a WebSocket receiver currently limits the size of a receive buffer to 50 000 000 bytes. Thus, applications should keep the size of their transmitted data buffers below this limit. Otherwise, the transmitted data buffers will be truncated.

Parameters

buffer	The buffer containing data to be written to the socket.
binary_frame	This flag indicates whether the data will be transmitted as binary frame or as text frame. For example, HTML 5 video data needs to be transmitted as binary frames.

Returns: The number of bytes written or -1 in case of errors in which case errno contains further information.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ State

Member Function Documentation

◆ close()

◆ get_http_connection()

◆ get_local_address()

◆ get_max_payload()

◆ get_peer_address()

◆ get_state()

◆ get_url_path()

◆ print()

◆ printf()

◆ set_data_handler()

◆ set_max_payload()

◆ set_state_handler()

◆ write()

^◆ State

^◆ close()

^◆ get_http_connection()

^◆ get_local_address()

^◆ get_max_payload()

^◆ get_peer_address()

^◆ get_state()

^◆ get_url_path()

^◆ print()

^◆ printf()

^◆ set_data_handler()

^◆ set_max_payload()

^◆ set_state_handler()

^◆ write()