Facade class for the management of the communication to Lightstreamer Server. More...

#include <LightstreamerClient.h>

Public Member Functions
	LightstreamerClient (const LightstreamerClient &)=delete

LightstreamerClient &	operator= (const LightstreamerClient &)=delete

	LightstreamerClient (const std::string &serverAddress="", const std::string &adapterSet="")
	Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it.

void	addListener (ClientListener *listener)
	Adds a listener that will receive events from the LightstreamerClient instance.

void	removeListener (ClientListener *listener)
	Removes a listener from the LightstreamerClient instance so that it will not receive events anymore.

std::vector< ClientListener * >	getListeners ()
	Returns a list containing the `ClientListener` instances that were added to this client.

void	connect ()
	Operation method that requests to open a Session against the configured Lightstreamer Server.

void	disconnect ()
	Operation method that requests to close the Session opened against the configured Lightstreamer Server (if any).

std::string	getStatus ()
	Inquiry method that gets the current client status and transport (when applicable).

void	subscribe (Subscription *subscription)
	Operation method that adds a Subscription to the list of "active" Subscriptions.

void	unsubscribe (Subscription *subscription)
	Operation method that removes a Subscription that is currently in the "active" state.

std::vector< Subscription * >	getSubscriptions ()
	Inquiry method that returns a list containing all the Subscription instances that are currently "active" on this LightstreamerClient.

void	sendMessage (const std::string &message, const std::string &sequence="", int delayTimeout=-1, ClientMessageListener *listener=nullptr, bool enqueueWhileDisconnected=false)
	Operation method that sends a message to the Server.

Static Public Member Functions
static const char *	initialize (void(unhandledExceptionCallback)(const char exceptionInfo)=nullptr)
	Initializes a thread that executes the Lightstreamer functions.

static void	stop ()
	Stops the Lightstreamer thread, blocking until the thread has completed.

static std::string	libName ()
	The name of the library.

static std::string	libVersion ()
	The version of the library.

static void	setLoggerProvider (LoggerProvider *provider)
	Static method that permits to configure the logging system used by the library.

static void	addCookies (const std::string &uri, const std::vector< std::string > &cookies)
	Static method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application.

static std::vector< std::string >	getCookies (const std::string &uri)
	Static inquiry method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application.

static void	setTrustManagerFactory (const std::string &caFile, const std::string &certificateFile, const std::string &privateKeyFile="", const std::string &password="", bool verifyCert=true)
	Provides a mean to control the way TLS certificates are evaluated, with the possibility to accept untrusted ones.

Public Attributes
ConnectionOptions	connectionOptions
	Data object that contains options and policies for the connection to the server.

ConnectionDetails	connectionDetails
	Data object that contains the details needed to open a connection to a Lightstreamer Server.

Detailed Description

Facade class for the management of the communication to Lightstreamer Server.

Used to provide configuration settings, event handlers, operations for the control of the connection lifecycle, Subscription handling and to send messages.
An instance of LightstreamerClient handles the communication with Lightstreamer Server on a specified endpoint. Hence, it hosts one "Session"; or, more precisely, a sequence of Sessions, since any Session may fail and be recovered, or it can be interrupted on purpose. So, normally, a single instance of LightstreamerClient is needed.
However, multiple instances of LightstreamerClient can be used, toward the same or multiple endpoints.

You can listen to the events generated by a session by registering an event listener, such as ClientListener or SubscriptionListener. These listeners allow you to handle various events, such as session creation, connection status, subscription updates, and server messages. However, you should be aware that the event notifications are dispatched by a single thread, the so-called event thread. This means that if the operations of a listener are slow or blocking, they will delay the processing of the other listeners and affect the performance of your application. Therefore, you should delegate any slow or blocking operations to a dedicated thread, and keep the listener methods as fast and simple as possible. Note that even if you create multiple instances of LightstreamerClient, they will all use a single event thread, that is shared among them.

Constructor & Destructor Documentation

◆ LightstreamerClient()

Lightstreamer::LightstreamerClient::LightstreamerClient	(	const std::string &	serverAddress = "",
		const std::string &	adapterSet = "" )

inlineexplicit

Creates an object to be configured to connect to a Lightstreamer server and to handle all the communications with it.

Each LightstreamerClient is the entry point to connect to a Lightstreamer server, subscribe to as many items as needed and to send messages.

Parameters

serverAddress	the address of the Lightstreamer Server to which this LightstreamerClient will connect to. It is possible to specify it later by using an empty string here. See `ConnectionDetails#setServerAddress()` for details.
adapterSet	the name of the Adapter Set mounted on Lightstreamer Server to be used to handle all requests in the Session associated with this LightstreamerClient. It is possible not to specify it at all or to specify it later by using an empty string here. See `ConnectionDetails#setAdapterSet()` for details.

Exceptions

LightstreamerError if a not valid address is passed. See ConnectionDetails#setServerAddress() for details.

Member Function Documentation

◆ addCookies()

static void Lightstreamer::LightstreamerClient::addCookies	(	const std::string &	uri,
		const std::vector< std::string > &	cookies )

inlinestatic

Static method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application.

With this method, cookies received by the application can be added (or replaced if already present) to the cookie set used by the library to access the Server. Obviously, only cookies whose domain is compatible with the Server domain will be used internally.

Lifecycle This method should be invoked before calling the LightstreamerClient#connect method. However it can be invoked at any time; it will affect the internal cookie set immediately and the sending of cookies on the next HTTP request or WebSocket establishment.

Parameters

uri	the URI from which the supplied cookies were received.
cookies	a list of cookie declarations in the Set-Cookie header format. Notice that the cookie attributes may be stored in a normalized form.

See also: getCookies

◆ addListener()

void Lightstreamer::LightstreamerClient::addListener ( ClientListener * listener )

inline

Adds a listener that will receive events from the LightstreamerClient instance.

Warning: A listener is exclusive to a single LightstreamerClient instance and cannot be shared with other instances.

Lifecycle A listener can be added at any time. A call to add a listener already present will be ignored.

Parameters

listener An object that will receive the events as documented in the ClientListener interface.

See also: removeListener()

◆ connect()

void Lightstreamer::LightstreamerClient::connect ( )

inline

Operation method that requests to open a Session against the configured Lightstreamer Server.

When connect() is called, unless a single transport was forced through ConnectionOptions#setForcedTransport(), the so called "Stream-Sense" mechanism is started: if the client does not receive any answer for some seconds from the streaming connection, then it will automatically open a polling connection.
A polling connection may also be opened if the environment is not suitable for a streaming connection.
Note that as "polling connection" we mean a loop of polling requests, each of which requires opening a synchronous (i.e. not streaming) connection to Lightstreamer Server.

Lifecycle Note that the request to connect is accomplished by the client in a separate thread; this means that an invocation to getStatus right after connect() might not reflect the change yet.
When the request to connect is finally being executed, if the current status of the client is not DISCONNECTED, then nothing will be done.

Exceptions

LightstreamerError if no server address was configured.

See also: getStatus; disconnect; ClientListener::onStatusChange(); ConnectionDetails::setServerAddress()

◆ disconnect()

void Lightstreamer::LightstreamerClient::disconnect ( )

inline

Operation method that requests to close the Session opened against the configured Lightstreamer Server (if any).

When disconnect() is called, the "Stream-Sense" mechanism is stopped.
Note that active Subscription instances, associated with this LightstreamerClient instance, are preserved to be re-subscribed to on future Sessions.

Lifecycle Note that the request to disconnect is accomplished by the client in a separate thread; this means that an invocation to getStatus right after disconnect() might not reflect the change yet.
When the request to disconnect is finally being executed, if the status of the client is "DISCONNECTED", then nothing will be done.

See also: connect

◆ getCookies()

static std::vector< std::string > Lightstreamer::LightstreamerClient::getCookies ( const std::string & uri )

inlinestatic

Static inquiry method that can be used to share cookies between connections to the Server (performed by this library) and connections to other sites that are performed by the application.

With this method, cookies received from the Server can be extracted for sending through other connections, according with the URI to be accessed.

Parameters

uri	the URI to which the cookies should be sent.

Returns: a list of cookies (in the Set-Cookie header format) that can be sent in a HTTP request for the specified URI.

◆ getListeners()

std::vector< ClientListener * > Lightstreamer::LightstreamerClient::getListeners ( )

inline

Returns a list containing the ClientListener instances that were added to this client.

Returns: a list containing the listeners that were added to this client.

See also: addListener()

◆ getStatus()

std::string Lightstreamer::LightstreamerClient::getStatus ( )

inline

Inquiry method that gets the current client status and transport (when applicable).

Returns

The current client status. It can be one of the following values:

"CONNECTING" the client is waiting for a Server's response in order to establish a connection;
"CONNECTED:STREAM-SENSING" the client has received a preliminary response from the server and is currently verifying if a streaming connection is possible;
"CONNECTED:WS-STREAMING" a streaming connection over WebSocket is active;
"CONNECTED:HTTP-STREAMING" a streaming connection over HTTP is active;
"CONNECTED:WS-POLLING" a polling connection over WebSocket is in progress;
"CONNECTED:HTTP-POLLING" a polling connection over HTTP is in progress;
"STALLED" the Server has not been sending data on an active streaming connection for longer than a configured time;
"DISCONNECTED:WILL-RETRY" no connection is currently active but one will be opened (possibly after a timeout);
"DISCONNECTED:TRYING-RECOVERY" no connection is currently active, but one will be opened as soon as possible, as an attempt to recover the current session after a connection issue;
"DISCONNECTED" no connection is currently active.

See also: ClientListener::onStatusChange()

◆ getSubscriptions()

std::vector< Subscription * > Lightstreamer::LightstreamerClient::getSubscriptions ( )

inline

Inquiry method that returns a list containing all the Subscription instances that are currently "active" on this LightstreamerClient.

Internal second-level Subscription are not included.

Returns: A list, containing all the Subscription currently "active" on this LightstreamerClient.
The list can be empty.

See also: subscribe()

◆ initialize()

static const char * Lightstreamer::LightstreamerClient::initialize ( void(* unhandledExceptionCallback )(const char *exceptionInfo) = nullptr )

inlinestatic

Initializes a thread that executes the Lightstreamer functions.

The thread remains alive indefinitely until told to stop.

This must be first before calling any Lightstreamer functions (otherwise those calls will hang waiting for a response from the Lightstreamer thread).

Parameters

unhandledExceptionCallback a callback to execute if an unhandled exception occurs on the Lightstreamer thread. The Lightstreamer thread will continue processing events after an unhandled exception and you may want to stop it after receiving this callback. Use nullptr for no callback

Returns: nullptr if the thread initializes successfully or a null-terminated C string if an error occurs during initialization

See also: LightstreamerClient::stop()

◆ removeListener()

void Lightstreamer::LightstreamerClient::removeListener ( ClientListener * listener )

inline

Removes a listener from the LightstreamerClient instance so that it will not receive events anymore.

Warning: Once removed, a listener becomes unusable and should not be employed further. The internal garbage collector will subsequently release the allocated memory.

Lifecycle a listener can be removed at any time.

Parameters

listener The listener to be removed.

See also: addListener()

◆ sendMessage()

void Lightstreamer::LightstreamerClient::sendMessage	(	const std::string &	message,
		const std::string &	sequence = "",
		int	delayTimeout = -1,
		ClientMessageListener *	listener = nullptr,
		bool	enqueueWhileDisconnected = false )

inline

Operation method that sends a message to the Server.

The message is interpreted and handled by the Metadata Adapter associated to the current Session. This operation supports in-order guaranteed message delivery with automatic batching. In other words, messages are guaranteed to arrive exactly once and respecting the original order, whatever is the underlying transport (HTTP or WebSockets). Furthermore, high frequency messages are automatically batched, if necessary, to reduce network round trips.
Upon subsequent calls to the method, the sequential management of the involved messages is guaranteed. The ordering is determined by the order in which the calls to sendMessage are issued.
If a message, for any reason, doesn't reach the Server (this is possible with the HTTP transport), it will be resent; however, this may cause the subsequent messages to be delayed. For this reason, each message can specify a "delayTimeout", which is the longest time the message, after reaching the Server, can be kept waiting if one of more preceding messages haven't been received yet. If the "delayTimeout" expires, these preceding messages will be discarded; any discarded message will be notified to the listener through ClientMessageListener#onDiscarded(). Note that, because of the parallel transport of the messages, if a zero or very low timeout is set for a message and the previous message was sent immediately before, it is possible that the latter gets discarded even if no communication issues occur. The Server may also enforce its own timeout on missing messages, to prevent keeping the subsequent messages for long time.
Sequence identifiers can also be associated with the messages. In this case, the sequential management is restricted to all subsets of messages with the same sequence identifier associated.
Notifications of the operation outcome can be received by supplying a suitable listener. The supplied listener is guaranteed to be eventually invoked; listeners associated with a sequence are guaranteed to be invoked sequentially.
The "UNORDERED_MESSAGES" sequence name has a special meaning. For such a sequence, immediate processing is guaranteed, while strict ordering and even sequentialization of the processing is not enforced. Likewise, strict ordering of the notifications is not enforced. However, messages that, for any reason, should fail to reach the Server whereas subsequent messages had succeeded, might still be discarded after a server-side timeout, in order to ensure that the listener eventually gets a notification.
Moreover, if "UNORDERED_MESSAGES" is used and no listener is supplied, a "fire and forget" scenario is assumed. In this case, no checks on missing, duplicated or overtaken messages are performed at all, so as to optimize the processing and allow the highest possible throughput.

Lifecycle Since a message is handled by the Metadata Adapter associated to the current connection, a message can be sent only if a connection is currently active. If the special enqueueWhileDisconnected flag is specified it is possible to call the method at any time and the client will take care of sending the message as soon as a connection is available, otherwise, if the current status is "DISCONNECTED*", the message will be abandoned and the ClientMessageListener#onAbort event will be fired.
Note that, in any case, as soon as the status switches again to "DISCONNECTED*", any message still pending is aborted, including messages that were queued with the enqueueWhileDisconnected flag set to true.
Also note that forwarding of the message to the server is made in a separate thread, hence, if a message is sent while the connection is active, it could be aborted because of a subsequent disconnection. In the same way a message sent while the connection is not active might be sent because of a subsequent connection.

Parameters

message	a text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.
sequence	an alphanumeric identifier, used to identify a subset of messages to be managed in sequence; underscore characters are also allowed. If the "UNORDERED_MESSAGES" identifier is supplied, the message will be processed in the special way described above. The parameter is optional; if set to an empty string, "UNORDERED_MESSAGES" is used as the sequence name.
delayTimeout	a timeout, expressed in milliseconds. If higher than the Server configured timeout on missing messages, the latter will be used instead. The parameter is optional; if a negative value is supplied, the Server configured timeout on missing messages will be applied. This timeout is ignored for the special "UNORDERED_MESSAGES" sequence, although a server-side timeout on missing messages still applies.
listener	an object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available.
enqueueWhileDisconnected	if this flag is set to true, and the client is in a disconnected status when the provided message is handled, then the message is not aborted right away but is queued waiting for a new session. Note that the message can still be aborted later when a new session is established.

Warning: A listener is exclusive to a single method invocation and should not be employed further. Following the listener's activation, the internal garbage collector will release the allocated memory.

◆ setLoggerProvider()

static void Lightstreamer::LightstreamerClient::setLoggerProvider ( LoggerProvider * provider )

inlinestatic

Static method that permits to configure the logging system used by the library.

The logging system must respect the LoggerProvider interface. A custom class can be used to wrap any third-party logging system.
If no logging system is specified, all the generated log is discarded.
The following categories are available to be consumed:

lightstreamer.stream:
logs socket activity on Lightstreamer Server connections;
at INFO level, socket operations are logged;
at DEBUG level, read/write data exchange is logged.
lightstreamer.protocol:
logs requests to Lightstreamer Server and Server answers;
at INFO level, requests are logged;
at DEBUG level, request details and events from the Server are logged.
lightstreamer.session:
logs Server Session lifecycle events;
at INFO level, lifecycle events are logged;
at DEBUG level, lifecycle event details are logged.
lightstreamer.subscriptions:
logs subscription requests received by the clients and the related updates;
at WARN level, alert events from the Server are logged;
at INFO level, subscriptions and unsubscriptions are logged;
at DEBUG level, requests batching and update details are logged.
lightstreamer.actions:
logs settings / API calls.

Parameters

provider A LoggerProvider instance that will be used to generate log messages by the library classes.

◆ setTrustManagerFactory()

static void Lightstreamer::LightstreamerClient::setTrustManagerFactory	(	const std::string &	caFile,
		const std::string &	certificateFile,
		const std::string &	privateKeyFile = "",
		const std::string &	password = "",
		bool	verifyCert = true )

inlinestatic

Provides a mean to control the way TLS certificates are evaluated, with the possibility to accept untrusted ones.

Lifecycle May be called only once before creating any LightstreamerClient instance.

Parameters

caFile	the path to the file containing the CA/root certificates. Can be empty if the default certificates are used or `verifyCert` is false.
certificateFile	the path to the certificate file (in PEM format). Can be empty if `verifyCert` is false.
privateKeyFile	the path to the private key file used for encryption. Can be empty if no private key file is used or `verifyCert` is false.
password	password for decrypting the private key. Can be emtpy if the private key is not used or the private key is not encrypted or `verifyCert` is false.
verifyCert	If false, the server certificate is not verified.

◆ stop()

static void Lightstreamer::LightstreamerClient::stop ( )

inlinestatic

Stops the Lightstreamer thread, blocking until the thread has completed.

Once ended, it cannot be restarted (this is because static variable state will be retained from the last run).

Other threads spawned from the Lightstreamer thread may still be running (you must arrange to stop these yourself for safe app shutdown).

It can be safely called any number of times – if the Lightstreamer thread is not running this function will just return.

After executing no more calls to Lightstreamer functions can be made (as these will hang waiting for a response from the Lightstreamer thread).

Thread-safety: Can be called safely called on any thread. If called on the Lightstreamer thread it will trigger the thread to stop but it cannot then block until stopped.

See also: LightstreamerClient::initialize()

◆ subscribe()

void Lightstreamer::LightstreamerClient::subscribe ( Subscription * subscription )

inline

Operation method that adds a Subscription to the list of "active" Subscriptions.

The Subscription cannot already be in the "active" state.
Active subscriptions are subscribed to through the server as soon as possible (i.e. as soon as there is a session available). Active Subscription are automatically persisted across different sessions as long as a related unsubscribe call is not issued.

Lifecycle Subscriptions can be given to the LightstreamerClient at any time. Once done the Subscription immediately enters the "active" state.
Once "active", a Subscription instance cannot be provided again to a LightstreamerClient unless it is first removed from the "active" state through a call to unsubscribe().
Also note that forwarding of the subscription to the server is made in a separate thread.
A successful subscription to the server will be notified through a SubscriptionListener#onSubscription event.

Parameters

subscription A Subscription object, carrying all the information needed to process real-time values.

See also: unsubscribe()

◆ unsubscribe()

void Lightstreamer::LightstreamerClient::unsubscribe ( Subscription * subscription )

inline

Operation method that removes a Subscription that is currently in the "active" state.

By bringing back a Subscription to the "inactive" state, the unsubscription from all its items is requested to Lightstreamer Server.

Lifecycle Subscription can be unsubscribed from at any time. Once done the Subscription immediately exits the "active" state.
Note that forwarding of the unsubscription to the server is made in a separate thread.
The unsubscription will be notified through a SubscriptionListener#onUnsubscription event.

Parameters

subscription An "active" Subscription object that was activated by this LightstreamerClient instance.

Member Data Documentation

◆ connectionDetails

ConnectionDetails Lightstreamer::LightstreamerClient::connectionDetails

Data object that contains the details needed to open a connection to a Lightstreamer Server.

This instance is set up by the LightstreamerClient object at its own creation.
Properties of this object can be overwritten by values received from a Lightstreamer Server.

◆ connectionOptions

ConnectionOptions Lightstreamer::LightstreamerClient::connectionOptions

Data object that contains options and policies for the connection to the server.

This instance is set up by the LightstreamerClient object at its own creation.
Properties of this object can be overwritten by values received from a Lightstreamer Server.

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

LightstreamerClient.h

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ LightstreamerClient()

Member Function Documentation

◆ addCookies()

◆ addListener()

◆ connect()

◆ disconnect()

◆ getCookies()

◆ getListeners()

◆ getStatus()

◆ getSubscriptions()

◆ initialize()

◆ removeListener()

◆ sendMessage()

◆ setLoggerProvider()

◆ setTrustManagerFactory()

◆ stop()

◆ subscribe()

◆ unsubscribe()

Member Data Documentation

◆ connectionDetails

◆ connectionOptions