#include <iwebsocketserverendpoint.h>

Public Types
enum	EAccessMode : int { EveryOne = 0, Ticket = 1, Reserved = 2 }

Public Member Functions
virtual bool	isOpen () const =0

virtual bool	send (const WebSocketConnection &connection, const std::string &message, EWebSocketOPCode code, nap::utility::ErrorState &error)=0

virtual bool	send (const WebSocketConnection &connection, void const *payload, int length, EWebSocketOPCode code, nap::utility::ErrorState &error)=0

virtual bool	broadcast (const std::string &message, EWebSocketOPCode code, nap::utility::ErrorState &error)=0

virtual bool	broadcast (void const *payload, int length, EWebSocketOPCode code, nap::utility::ErrorState &error)=0

virtual std::string	getHostName (const WebSocketConnection &connection)=0

virtual void	getHostNames (std::vector< std::string > &outHosts)=0

virtual int	getConnectionCount ()=0

virtual bool	acceptsNewConnections ()=0

Public Member Functions inherited from Device
virtual bool	start (utility::ErrorState &errorState)

virtual void	stop ()

Public Member Functions inherited from Resource
	Resource ()

Public Member Functions inherited from Object
	Object ()

virtual	~Object ()

virtual bool	init (utility::ErrorState &errorState)

virtual void	onDestroy ()

	Object (Object &)=delete

Object &	operator= (const Object &)=delete

	Object (Object &&)=delete

Object &	operator= (Object &&)=delete

Public Attributes
EAccessMode	mMode = EAccessMode::EveryOne
	Property: "AccessMode" client connection access mode. More...

int	mConnectionLimit = -1
	Property: "ConnectionLimit" number of allowed client connections at once, -1 = no limit. More...

int	mPort = 80
	Property: "Port" to open and listen to for client requests. More...

bool	mLogConnectionUpdates = true
	Property: "LogConnectionUpdates" if client / server connect information is logged to the console. More...

bool	mAllowPortReuse = false
	Property: "AllowPortReuse" if the server connection can be re-used by other processes. More...

EWebSocketLogLevel	mLibraryLogLevel = EWebSocketLogLevel::Warning
	Property: "LibraryLogLevel" library messages equal to or higher than requested are logged. More...

std::vector< ResourcePtr< WebSocketTicket > >	mClients
	Property: "Clients" All authorized clients when mode is set to 'Reserved'". More...

std::string	mAccessAllowControlOrigin = "*"
	Property: "AllowControlOrigin" Access-Control-Allow-Origin response header value. Indicates if the server response can be shared with request code from the given origin. More...

std::string	mIPAddress = ""
	Property: 'IPAddress' this server IP Address, when left empty the first available ethernet adapter is chosen. More...

Public Attributes inherited from Object
std::string	mID
	Property: 'mID' unique name of the object. Used as an identifier by the system. More...

Protected Member Functions
virtual void	registerListener (IWebSocketServer &server)=0

virtual void	unregisterListener (IWebSocketServer &server)=0

Additional Inherited Members
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)

Description

Server endpoint interface. Manages all client connections.

On start the web-socket endpoint starts listening to connection requests, updates and messages on a background thread. The endpoint is a device that can be started and stopped. When stopped all active client-server connections are closed. This occurs when file changes are detected and the content of the application is hot-reloaded. A call to open is non blocking. Messages are forwarded to all clients that implement the nap::IWebSocketClient interface. Clients must register themselves to the various signals to receive connection updates and messages. Note that depending on your operating system you might have to run the application as administrator to open a web-socket.

By default the server accepts all client connection requests. Change the 'AccessMode' property to 'Ticket' or 'Reserved' to add a client identification scheme. When set to 'Ticket' the server accepts every client connection with a ticket. When set to 'Reserved' the server only accepts the connection if it has a matching ticket. Tickets that are accepted by the server can be added to the 'Clients' property.

A good analogy is that of attending a concert. When the mode is set to 'Everyone' you don't need to pick up a ticket in order to enter the venue. You can just walk in. When the mode is set to 'Ticket' you need to buy a ticket and show it at the front door. Everyone can buy a ticket. When the mode is set to 'Reserved' you need to be on the guest list. If you're not on the guest-list you are not allowed to buy a ticket, let alone enter the venue.

For both modes (Ticket and Reserved) you need to acquire a ticket by sending a HTTP 'POST' request to the server. The body of the post should contain a JSON formatted string that contains 2 fields: 'user' and 'pass'. Both fields are always required. For example:

{
   "user": "napuser"       
   "pass": "letmein"       
}

The server generates a new ticket based on the provided information and sends it back to the client that made the request. The received ticket should be specified as the first SUB-PROTOCOL argument when creating the web-socket. The server extracts the ticket on authorization and checks if it is valid. After validation the connection is accepted or rejected. Note that when the mode is set to 'Everyone' the server will not serve any tickets and you should not provide the system with one when connecting to the server. In that case: connect without specifying a sub-protocol.

The reason for having the 'Ticket' validation mode (next to 'Reserved') is to prevent any user or bot to log in automatically but allow 'interested' users free access. Every nap::WebSocketClient can make it's own ticket and therefore doesn't require the http post request. The NAP client still needs to have a correct username and password if required by the server.

Inheritance diagram for IWebSocketServerEndPoint:

[legend]

Collaboration diagram for IWebSocketServerEndPoint:

[legend]

Member Enumeration Documentation

◆ EAccessMode

enum EAccessMode : int

strong

Various client access modes

Enumerator
EveryOne	Every client connection is allowed.
Ticket	Every client connection with a ticket is allowed.
Reserved	Only clients that have a matching ticket are allowed.

Member Function Documentation

◆ acceptsNewConnections()

virtual bool acceptsNewConnections ( )

pure virtual

Returns: if the server end point accepts new connections

◆ broadcast() [1/2]

virtual bool broadcast	(	const std::string &	message,
		EWebSocketOPCode	code,
		nap::utility::ErrorState &	error
	)

pure virtual

Sends a message to a all connected clients.

Parameters

message	the message to send
code	message type
error	contains the error if sending fails

Returns: if the message is broadcast

◆ broadcast() [2/2]

virtual bool broadcast	(	void const *	payload,
		int	length,
		EWebSocketOPCode	code,
		nap::utility::ErrorState &	error
	)

pure virtual

Broadcasts a message to all connected clients using the given payload and opcode.

Parameters

payload	the message buffer
length	size of the buffer in bytes
code	message type
error	contains the error if sending fails

Returns: if message was send successfully

◆ getConnectionCount()

virtual int getConnectionCount ( )

pure virtual

Returns: total number of active client connections

◆ getHostName()

virtual std::string getHostName ( const WebSocketConnection & connection )

pure virtual

Returns: a client connection host-name, empty string if the connection is not managed by this end-point.

◆ getHostNames()

virtual void getHostNames ( std::vector< std::string > & outHosts )

pure virtual

Returns a list of all currently connected client host-names.

Parameters

outHosts the list of connected client host-names.

◆ isOpen()

virtual bool isOpen ( ) const

pure virtual

Returns: if the current end point is open and running

◆ registerListener()

virtual void registerListener ( IWebSocketServer & server )

protectedpure virtual

Register a server for this endpoint so that it receives notifications from the endpoint.

Parameters

server server to register as listener

◆ send() [1/2]

virtual bool send	(	const WebSocketConnection &	connection,
		const std::string &	message,
		EWebSocketOPCode	code,
		nap::utility::ErrorState &	error
	)

pure virtual

Sends a message to a client.

Parameters

connection	the client connection
message	the message to send
code	message type
error	contains the error if sending fails

Returns: if message was send successfully

◆ send() [2/2]

virtual bool send	(	const WebSocketConnection &	connection,
		void const *	payload,
		int	length,
		EWebSocketOPCode	code,
		nap::utility::ErrorState &	error
	)

pure virtual

Sends a message to a client using the given payload and opcode.

Parameters

connection	the client connection
payload	the message buffer
length	size of the buffer in bytes
code	message type
error	contains the error if sending fails

Returns: if message was send successfully

◆ unregisterListener()

virtual void unregisterListener ( IWebSocketServer & server )

protectedpure virtual

Unregister a server for this endpoint so that it stops receiving notifications from the endpoint.

Parameters

server the server to unregister as listener

Member Data Documentation

◆ mAccessAllowControlOrigin

std::string mAccessAllowControlOrigin = "*"

Property: "AllowControlOrigin" Access-Control-Allow-Origin response header value. Indicates if the server response can be shared with request code from the given origin.

◆ mAllowPortReuse

bool mAllowPortReuse = false

Property: "AllowPortReuse" if the server connection can be re-used by other processes.

◆ mClients

std::vector<ResourcePtr<WebSocketTicket> > mClients

Property: "Clients" All authorized clients when mode is set to 'Reserved'".

◆ mConnectionLimit

int mConnectionLimit = -1

Property: "ConnectionLimit" number of allowed client connections at once, -1 = no limit.

◆ mIPAddress

std::string mIPAddress = ""

Property: 'IPAddress' this server IP Address, when left empty the first available ethernet adapter is chosen.

◆ mLibraryLogLevel

EWebSocketLogLevel mLibraryLogLevel = EWebSocketLogLevel::Warning

Property: "LibraryLogLevel" library messages equal to or higher than requested are logged.

◆ mLogConnectionUpdates

bool mLogConnectionUpdates = true

Property: "LogConnectionUpdates" if client / server connect information is logged to the console.

◆ mMode

EAccessMode mMode = EAccessMode::EveryOne

Property: "AccessMode" client connection access mode.

◆ mPort

int mPort = 80

Property: "Port" to open and listen to for client requests.

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Additional Inherited Members

Description

Member Enumeration Documentation

◆ EAccessMode

Member Function Documentation

◆ acceptsNewConnections()

◆ broadcast() [1/2]

◆ broadcast() [2/2]

◆ getConnectionCount()

◆ getHostName()

◆ getHostNames()

◆ isOpen()

◆ registerListener()

◆ send() [1/2]

◆ send() [2/2]

◆ unregisterListener()

Member Data Documentation

◆ mAccessAllowControlOrigin

◆ mAllowPortReuse

◆ mClients

◆ mConnectionLimit

◆ mIPAddress

◆ mLibraryLogLevel

◆ mLogConnectionUpdates

◆ mMode

◆ mPort