APIWebSocketClient Class Reference

#include <apiwebsocketclient.h>

Public Member Functions
	APIWebSocketClient (APIWebSocketService &service)
bool	send (APIEventPtr apiEvent, utility::ErrorState &error)
Public Member Functions inherited from IWebSocketClient
	IWebSocketClient (WebSocketService &service)
virtual bool	init (utility::ErrorState &errorState) override
virtual void	onDestroy () override
bool	isConnected () const
bool	reconnect (utility::ErrorState &error)
const WebSocketConnection &	getConnection () const
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 IWebSocketClient
ResourcePtr< IWebSocketClientEndPoint >	mEndPoint
	Property: 'EndPoint' the client endpoint that manages all connections. More...
ResourcePtr< WebSocketTicket >	mTicket = nullptr
	Property: 'Ticket' optional identification token. More...
std::string	mURI
	Property: "URI" Server URI to open connection to. 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	onConnectionOpened () override
virtual void	onConnectionClosed (int code, const std::string &reason) override
virtual void	onConnectionFailed (int code, const std::string &reason) override
virtual void	onMessageReceived (const WebSocketMessage &message) override
Protected Member Functions inherited from WebSocketInterface
void	addEvent (WebSocketEventPtr newEvent)

Additional Inherited Members
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)
Protected Attributes inherited from IWebSocketClient
WebSocketConnection	mConnection
	Web-socket connection. More...
Protected Attributes inherited from WebSocketInterface
std::queue< WebSocketEventPtr >	mEvents
std::mutex	mEventMutex
WebSocketService *	mService = nullptr

Description

With this client you can send nap api events in the form of a JSON formatted text message to a server. When the server issues a reply the message can be interpreted as a nap api event and is, when accepted, forwarded to the API service. This allows you to use the NAP API system to send and respond to server requests.

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

For example, to send a message in the form of an api request to a server:

// Create request
nap::APIEventPtr server_request = std::make_unique<nap::APIEvent>("getMotorSpeed");
 
// Add argument
server_request->addArgument<APIInt>("number", 1);
 
// Send
nap::utility::ErrorState error;
if (!client->send(std::move(server_request), error))
{
    nap::Logger::error(error.toString());
}

You can control what the client does when it a receives a connection update or message from the server. By default messages are NOT converted into api events, only into web-socket events. By changing the 'Mode' to 'APIEvent' or 'Both' the client will try to convert every message from the server into an API event. The api event is forwarded to your application (if the system accepts it). When only 'APIEvent' is selected, no web-socket events are created. When 'Both' is selected, the client will create both api and web-socket events. If the message can't be converted into an api event only the web-socket event is forwarded. 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 client will issue warnings if a message can't be converted into an api event.

A 'ticket' can be added to specify additional authorization information (username / password). This information is automatically given to the server when the client tries to establish a connection. The server can accept or reject the connection based on that information. When no ticket is provided the client will try to connect without any authorization.

Inheritance diagram for APIWebSocketClient:

Collaboration diagram for APIWebSocketClient:

Constructor & Destructor Documentation

APIWebSocketClient()

APIWebSocketClient

(

APIWebSocketService &

service

)

Constructor

Parameters

service

handle to the api web-socket service.

Member Function Documentation

onConnectionClosed()

virtual void onConnectionClosed ( int  code, const std::string &  reason  )

overrideprotectedvirtual

Occurs when the connection to the server is closed.

Parameters

code	the closing code
reason	the reason for closing the connection.

Implements IWebSocketClient.

onConnectionFailed()

virtual void onConnectionFailed ( int  code, const std::string &  reason  )

overrideprotectedvirtual

Occurs when connecting to the server fails.

Parameters

code	the closing code
reason	the reason why the connection failed.

Implements IWebSocketClient.

onConnectionOpened()

virtual void onConnectionOpened ( )

overrideprotectedvirtual

Occurs when a new connection to the server is opened.

Implements IWebSocketClient.

onMessageReceived()

virtual void onMessageReceived ( const WebSocketMessage &  msg )

overrideprotectedvirtual

Occurs when a new message from the server to this client is received.

Parameters

msg	the received message

Implements IWebSocketClient.

send()

bool send	(	APIEventPtr	apiEvent,
		utility::ErrorState &	error
	)

Sends a message in the form of an API event to the server.

For example:

// Create request
nap::APIEventPtr server_request = std::make_unique<nap::APIEvent>("getMotorSpeed");
 
// Add argument
server_request->addArgument<APIInt>("number", 1);
 
// Send
nap::utility::ErrorState error;
if (client->send(std::move(server_request), error))
{
    nap::Logger::error(error.toString());
}

Parameters

apiEvent	event that contains the message to send.
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.