APIWebSocketServer Class Reference

#include <apiwebsocketserver.h>

Public Member Functions
	APIWebSocketServer (APIWebSocketService &service)
bool	send (nap::APIEventPtr apiEvent, const WebSocketConnection &connection, utility::ErrorState &error)
bool	broadcast (nap::APIEventPtr apiEvent, nap::utility::ErrorState &error)
Public Member Functions inherited from IWebSocketServer
	IWebSocketServer (WebSocketService &service)
virtual bool	init (utility::ErrorState &errorState) override
virtual void	onDestroy () override
Public Member Functions inherited from WebSocketInterface
	WebSocketInterface (WebSocketService &service)
virtual	~WebSocketInterface ()
template<typename T >
T &	as ()
template<typename T >
const T &	as () const
Public Member Functions inherited from Resource
	Resource ()
Public Member Functions inherited from Object
	Object ()
virtual	~Object ()
	Object (Object &)=delete
Object &	operator= (const Object &)=delete
	Object (Object &&)=delete
Object &	operator= (Object &&)=delete

Public Attributes
bool	mSendWebSocketEvents = true
	Property: 'SendWebSocketEvents' send events to WebSocket service as well as API service. More...
bool	mVerbose = true
	Property: 'Verbose' log server message to api-event conversion failures. More...
Public Attributes inherited from IWebSocketServer
ResourcePtr< IWebSocketServerEndPoint >	mEndPoint
	Property: 'EndPoint' the server endpoint that manages all client connections. More...
Public Attributes inherited from Object
std::string	mID
	Property: 'mID' unique name of the object. Used as an identifier by the system. More...

Additional Inherited Members
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)
Protected Member Functions inherited from WebSocketInterface
void	addEvent (WebSocketEventPtr newEvent)
Protected Attributes inherited from WebSocketInterface
std::queue< WebSocketEventPtr >	mEvents
std::mutex	mEventMutex
WebSocketService *	mService = nullptr

Description

Allows for receiving and responding to nap api messages over a web-socket. Implements the IWebSocketServer interface.

When a client sends a JSON formatted text message to the server, the server tries to convert the message into a nap api event. When the api event is accepted by your application, it is forwarded to the API service. This allows you to use the NAP API system to send and respond to client requests. With this server you can also send replies to a client in the form of a nap api event.

A client request is accepted when your application exposes a signature (method) that matches the signature of the received message. When accepted, the right callback in your application is automatically triggered by a nap::APIComponentInstance. Look at the documentation of the nap::APIComponentInstance and nap::APICallBack for more information.

The message sent by the client must contain at least one JSON formatted nap::APIMessage object, for example:

{
    "Objects":
    [
        {
            "Type": "nap::APIMessage",
            "mID": "01",
            "Name": "getMotorSpeed",
            "Arguments":
            [
                {
                    "Type": "nap::APIInt",
                    "Name": "number",
                    "mID": "02",
                    "Value": 1
                }
            ]
        }
    ]
}

You can combine multiple nap::APIMessage objects into a single message. Every nap::APIMessage object is converted into a separate nap api event, before handed over to the running application.

Example of a server reply in response to the client request:

// Create response, copy over client query uuid.
APIWebSocketEventPtr reply = std::make_unique<APIEvent>("motorSpeed", client_request->getID());
 
// Add current motor speed value.
reply->addArgument<APIFloat>("speed", mMotorSpeed);
 
// Send response to client.
if (!server->send(std::move(reply), client_connection, error))
{
    nap::Logger::error(error.toString());
}

When replying to a nap api message it is advised to copy the unique id of the request. This allows the client to match the request to a server reply. The client can manually parse the json formatted text or, when making use of a nap::APIWebSocketClient, automatically parse the reply without inspection. See nap::APIWebSocketConnection for more information.

You can control what the server does when it a receives a connection update or message from a client. By default the server tries to convert every message from a client into an api event. The api event is forwarded to your application (if the system accepts it). By changing the 'Mode' to 'Both' every message is converted into both an api and web-socket event. Both are forwarded to your application. If the message can't be converted into an api event only the web-socket event is forwarded. When 'WebSocketEvent' is selected, only web-socket events are created. In this mode the server is a regular nap::WebSocketServer. To catch api-events use a nap::APIComponentInstance, to catch web-socket events use a nap::WebSocketComponent.

NOTE: When the 'Mode' is set to 'APIEvent' NO connection updates (open, close and failed) are created. When 'Verbose' is turned on the server will issue warnings if a message can't be converted into an api event. When conversion fails the server always sends an error reply to the client. Every server error reply starts with: "ERROR:", together with the reason for failure, for example: "ERROR: MyServer: unable to parse json".

Inheritance diagram for APIWebSocketServer:

Collaboration diagram for APIWebSocketServer:

Constructor & Destructor Documentation

APIWebSocketServer()

APIWebSocketServer

(

APIWebSocketService &

service

)

Constructor

Parameters

service

handle to the api web-socket service.

Member Function Documentation

broadcast()

bool broadcast	(	nap::APIEventPtr	apiEvent,
		nap::utility::ErrorState &	error
	)

Broadcasts a message in the form of an api event to all connected clients

Parameters

apiEvent	api event to broadcast as a text message to the clients
error	contains the error if broadcasting fails

Returns

if message was broadcast successfully

send()

bool send	(	nap::APIEventPtr	apiEvent,
		const WebSocketConnection &	connection,
		utility::ErrorState &	error
	)

Sends a message in the form of an api event to a client.

For example:

// Create response, copy over client query uuid.
APIWebSocketEventPtr reply = std::make_unique<APIEvent>("motorSpeed", client_request->getID());

// Add current motor speed value.
reply->addArgument<APIFloat>("speed", mMotorSpeed);

// Send response to client.
if (!server->send(std::move(reply), client_connection, error))
{
    nap::Logger::error(error.toString());
}

When replying to a nap api message it is advised to copy the unique id of the request. This allows the client to match the request to a server reply.

Parameters

apiEvent	api event to send as a text message to the client.
connection	client connection handle.
error	contains the error if sending fails.

Returns

if message was sent successfully.

Member Data Documentation

mSendWebSocketEvents

bool mSendWebSocketEvents = true

Property: 'SendWebSocketEvents' send events to WebSocket service as well as API service.

mVerbose

bool mVerbose = true

Property: 'Verbose' log server message to api-event conversion failures.