SDK for Generic Clients CHANGELOG
2.5.0 build 3372
Compatible with Server since 7.4.0.
Released on 9 Jul 2024

Fixed the protocol documentation, as the suggested parsing algorithm for real-time updates contained an indentation error.

Revised some compatibility notes in this changelog, as they might have been deceiving,

2.5.0 build 3343
Compatible with Server since 7.4.0.
Released on 14 Dec 2023

Restored the correct build number, as in the previous version it was 2326 instead of 3326 due to a typo.

2.5.0 build 2326
Compatible with Server since 7.4.0.
May not be compatible with custom clients based on the previous version; see compatibility notes below.
Compatible with custom clients sticking to the previous version.
Released on 3 Jul 2023

Extended the MSGDONE notification of the streaming channel by adding a third argument carrying a response message that can be received from the Metadata Adapter. COMPATIBILITY NOTE: Existing clients using version 2.4.0, in order to upgrade to 2.5.0, should introduce the handling of the new syntax. Obviously, the client is free to discard the received response argument. However, 2.4.0 clients that never issue "msg" requests (hence never expect MSGDONE notifications) could also claim version 2.5.0 without issues.

Improved the description of the TLCP-diff format in the protocol document, with examples.

2.4.0 build 3006
Compatible with Server since 7.3.0.
Not compatible with custom clients based on the previous version; see compatibility notes below.
Compatible with custom clients sticking to the previous version.
Released on 19 Sep 2022

Introduced the possibility to receive update values in form of differences between the previous and the new value for the same item and field. Two "diff" formats are currently available:

  • JSON Patch, which the Server can use when the involved values are valid JSON representations.
  • TLCP-diff, a custom encoding which is a compact and reduced variant of the "unified diff" format.
See the "Real-Time Updates" paragraph in the TLCP documentation for details.
Added the LS_supported_diffs parameter to the create_session request to allow the client to restrict the set of available "diff" formats. COMPATIBILITY NOTE: Existing clients using version 2.3.0, in order to upgrade to 2.4.0, should introduce the handling of the new syntax and the support of the two new "diff" formats. Alternatively, clients may leverage the LS_supported_diffs argument in create_session requests to enable no "diff" format and still claim TLCP 2.4.0.

Fixed the protocol document, in which all descriptions and practical examples still reported the previous version number.

Clarified in the protocol document what race conditions are possible due to the asynchronous semantics of some messages.

2.3.0 build 2338
Compatible with Server since 7.2.0.
Released on 20 Dec 2021

Fixed the protocol document, in which all descriptions and practical examples still reported the previous version number.

Clarified in the protocol document what race conditions are possible due to the asynchronous semantics of some messages.

2.3.0
Compatible with Server since 7.2.0.
May not be compatible with custom clients based on the previous version; see compatibility notes below.
Compatible with custom clients sticking to the previous version.
Released on 15 Jul 2021

Introduced an alternative request syntax to modify an existing MPN subscription, as a control request variant similar to LS_op=activate, with the new parameter LS_op=pn_reconf. This variant does not modify the subscription-related parameters, but only the notification-related parameters, hence it is safer to use if multiple sessions may act on behalf of the same device.
The extension also introduces the new MPNCONF notification of the streaming channel. COMPATIBILITY NOTE: Existing clients using version 2.2.0 or earlier, in order to upgrade to 2.3.0, should ensure that the new notification is handled (although it will be received only when LS_op=pn_reconf is leveraged). The extension also introduces the new error code 56 for control requests, only used in response to LS_op=pn_reconf requests.

Introduced the new error code 3 for control requests, that can be issued when the request refers to a session with a different protocol, which doesn't support the request. COMPATIBILITY NOTE: Existing clients using version 2.2.0 or earlier, in order to upgrade to 2.3.0, should ensure that the new error code is accepted for all control requests.

Added the optional LS_ack parameter to subscription and unsubscription requests on WebSocket transport, to save the REQOK response when successful.

2.2.0 build 1968
Compatible with Server since 7.1.1.
May not be compatible with custom clients based on the previous version; see compatibility notes below.
Compatible with custom clients sticking to the previous version.
Released on 27 May 2020

Introduced the WSOK request message, available on websockets to test the correct working of the connection in a fast way.

Extended the possibility to issue control requests on a websocket by omitting the session ID, to refer to the session related with the last create_session or bind_session request. Now such a control request can follow a create/bind immediately, regardless that the processing of the latter has even started.

Added new error codes on create_session requests. Namely:

  • Code 5, to mean that the Server has refused the request because it is temporarily overloaded. The client should reissue the request later.
  • Code 6, to mean that the Metadata Adapter could not authenticate the request because of a temporary issue. The client should reissue the request later.
  • Code 70, to mean that the request has been refused because it was issued to a Server's CONTROL_ONLY port. Hence the client should not retry the request until it is notified of the correct port.
COMPATIBILITY NOTE: Existing clients using version 2.1.0 or earlier, in order to upgrade to 2.2.0, should ensure that the new error codes are handled as suggested.

Introduced an optional LS_ttl_millis parameter on create_session requests, to notify the Server of the "time to live" assigned to a request by the Client.

Introduced an optional LS_reduce_head parameter on create_session and bind_session requests, to instruct the Server to omit some notifications on the response. The lack of such notifications is not critical and may be traded for shorter responses, especially when polling is needed.

Fixed unclear response error messages upon wrong protocol versions.

2.1.0 build 1946
Compatible with Lightstreamer Server since 7.0.
Released on 24 Jan 2020

Extended the scope of error code 32 upon END messages. Previously, the code specified that a session had been closed via the JMX interface, whereas now other mechanisms that allow enforcing of session closure from the Server side may be the originating cause.

Extended the scope of error code 48 upon END messages. Previously, the code specified that a session had been closed because of expiration of the maximum duration configured, whereas now other mechanisms that allow enforcing of session expiration from the Server side are admitted.

2.1.0 build 1859
Compatible with Lightstreamer Server since 7.0.
May not be compatible with custom clients based on the previous version; see compatibility notes below.
May not be compatible with custom clients sticking to the previous version; see compatibility notes below.
Released on 28 Feb 2018

Added session error code 21 and control error code 11, that can be received instead of, respectively, session error code 20 and control error code 20, to inform that not only a specified session was not found but it is also likely that the request was routed to the wrong Server instance. COMPATIBILITY NOTE: Existing clients using version 2.0.0 and handling error code 20, in order to upgrade to 2.1.0, should ensure that the new error codes are also handled properly. COMPATIBILITY NOTE: Existing clients using version 2.1.0 build 1851 and handling error code 20 should ensure that the new error codes are also handled properly.

Extended the scope of REQERR code 41 on the various MPN requests to all issues related with resource unavailability in the Server preventing the operation. Previously, such issues could have caused a ERROR response with code 68.

Clarified in the documentation the use of percent encoding.

Clarified in the documentation how to distinguish notifications that carry snapshot information from real-time updates.

Added clarifications on licensing matters in the documentation.

2.1.0 build 1851
Compatible with Lightstreamer Server since 7.0 b2.
May not be compatible with custom clients based on the previous version; see compatibility notes below.
May not be compatible with custom clients sticking to the previous version; see compatibility notes below.
Released on 20 Dec 2017

Introduced the support for Mobile Push Notifications. It consists in:

  • New available requests to the Server to register a target device and activate special MPN subscriptions that will be delivered via mobile push notifications to the device. The device identification is in charge to the application.
  • New real-time notifications in the current session, which confirm the fulfilment of the requests.
  • A special Data Adapter, available in all Adapter Sets, that supplies items carrying the current state of the MPN subscriptions for the currently registered device.
An MPN subscription is backed by a real-time subscription, from which it may take any field value. Unlike the usual real-time subscriptions, MPN subscriptions are persistent: they survive the session and are identified by a permanent, global, unique key provided by the Server at time of activation.
The notifications are managed by third-party services supported by the Server, which determine the notification characteristics and the supported devices. See the protocol documentation for details.

Added the support for recovery of sessions upon unexpected socket interruption during streaming or long polling. This involves an extension of the bind_session command (see LS_recovery_from), with a new error code (4) for CONERR, and a new Server notification (PROG). See the revised "Session Life Cycle" paragraph and the related "Session Recovery" example in chapter 6 for details.

Introduced the "heartbeat" pseudo-request to probe sockets and keep them alive.
Added the "LS_inactivity_millis" request parameter to create_session and bind_session to leverage Server-side checks of client activity and heartbeats.

Removed redundant uses of the SERVNAME and CLIENTIP notifications, by allowing them to be omitted on Session rebinds when unchanged with respect to the previous time. COMPATIBILITY NOTE: Existing clients using version 2.0.0 and managing SERVNAME and/or CLIENTIP, in order to upgrade to 2.1.0, should ensure that they keep the previous value upon each rebind; in particular, they cannot expect SERVNAME and/or CLIENTIP to be always received on rebind.

Added the new Server error code 71 to the session error codes.

Clarified the syntax documentation to detail how requests can be mapped onto the various transports (HTTP POST, WS messages, and the added case of HTTP GET).
Also clarified the requirements in terms of percent-encoding in the various cases, by specifying for which characters the encoding is mandatory (whereas for all other characters it is optional). Improved the provided examples accordingly, by removing unnecessary encoding.

Restricted various syntax checks on the requests to become case-sensitive. This is not meant as a change of the TLCP protocol specifications, which always specify the correct case for the keywords. However, some examples in the protocol documentation reported the LS_reqId parameter with a wrong case and have now been fixed. COMPATIBILITY NOTE: Existing clients using version 2.0.0 in which incorrect case is used, perhaps because inspired by some of the provided examples, have to be fixed.

2.0.0 build 1809
Compatible with Lightstreamer Server since 6.1.
Not compatible with custom clients based on the previous version.
Compatible with custom clients sticking to the previous version.
Released on 23 Jan 2017

Thoroughly redesigned the protocol, mainly on the response side. The new protocol, named TLCP, helps achieving various improvements, such as the following:

  • full support for WebSockets, as transport for both streaming and control requests;
  • protocol versioning;
  • notification of successful subscriptions and unsubscriptions within the update flow;
  • detailed error messages also for syntax errors;
  • support for independent execution of the requests in a batch;
  • notification of the bandwidth and frequency constraints applied by the Server;
  • notification of subscription metadata determined by the Server;
  • full support for Adapter's ClearSnapshot requests;
  • discontinuation of the use of zero values to carry special meanings, in both requests and responses;
  • notification of server-side timestamps, to allow for detection of data transport delays;
  • notification of server-side client IP, to allow for detection of changes in connection routing;
  • support for subscription requests embedded in session opening requests;
  • injection of custom cause messages in session destroy requests.
See the included documentation for any details.
Any custom clients based on the previous versions of the protocol are still supported by Lightstreamer Server.

Redefined the SDK version, which is now 2.0.0 and also represents the version of the underlying TLCP protocol. It is meant that any explicit or implicit reference to the "previous" versions of the SDK may include version 6.0.3 or earlier. The supplied build number is still increasing and can be used to disambiguate.

6.0.3 build 1803
Compatible with Lightstreamer Server since 6.0.3.
Compatible with custom clients for the previous version.
Released on 5 Sep 2016

Restricted the syntax checks on the requests, so that some illegal cases that used to be accepted are now refused. For instance, negative numeric values were, in some cases, treated like missing values and replaced with defaults. COMPATIBILITY NOTE: No client is expected to fall into the above illegal cases.

6.0.2 build 1794
Compatible with Lightstreamer Server since 6.0.2.
Compatible with custom clients for the previous version.
Released on 10 May 2016

Added the LS_cause_code parameter to LS_op=destroy requests. The supplied codes will now be possible cause codes of the "END" message. COMPATIBILITY NOTE: The newly available codes are not to be expected from the "END" message, unless extended invocations of LS_op=destroy requests are introduced.

Clarified the use of the Control Link in the protocol documentation.

6.0.1 build 1747
Compatible with Lightstreamer Server since 6.0.
Released on 16 Jul 2015
6.0.1 build 1738
Compatible with Lightstreamer Server since 6.0.
Compatible with custom clients for the previous version.
Released on 13 Feb 2015

Added the cause code 48 upon the "END" message (asynchronous close). COMPATIBILITY NOTE: The code can be issued only if the new <max_session_duration_minutes> setting (introduced with Lightstreamer Server build 1741) is used, hence custom clients don't have to be updated to take the code into account, as long as the Server configuration is not changed.

6.0 build 1734
Compatible with Lightstreamer Server since 6.0.
Not compatible with custom clients for the previous version; see compatibility notes below.
Released on 21 Jan 2015

Extended the protocol to support the new client identification mechanism. See the added parameters for the "create_session.txt" request. COMPATIBILITY NOTE: Existing clients have to be extended with the new parameters in order to comply with the current and future versions of the protocol; however, Lightstreamer Server always guarantees the support for old clients.

Added the error code 30 upon control.txt; the case is only predisposed for future special licenses.COMPATIBILITY NOTE: custom clients which check the possible error outcomes don't have to be updated, as long as there is no change in license terms.

Removed the error code 14 upon create_session/bind_session, as it is no longer issued. The check was related with the use in custom clients of the Adapter Set used by the Monitor Console/Dashboard, which is an undocumented (and unneeded) option.

Fixed a clarification comment on the protocol documentation: the single quote is expected to be escaped in field values, not the double quote.

Updated the included examples, to reflect changes in Lightstreamer Server default configuration and predeployed Adapters.

5.1.2 build 1623.14
Compatible with Lightstreamer Server since 5.0.
May not be compatible with custom clients for the previous version; see compatibility notes below.
Released on 22 Jul 2014

Extended the syntax with the "Preamble" element in the response header, which may be used in specific cases for padding purpose only. COMPATIBILITY NOTE: existing custom clients that perform strict checks on the response headers may refuse the response and eventually fail to establish a session, hence they should be extended. Backward compatibility can be enforced by removing the new <use_enriched_content_type> configuration setting.

5.1.1 build 1623.2
Compatible with Lightstreamer Server since 5.0.
Released on 5 Mar 2013

Clarified the requirements on the URL encoding of the request attributes.

5.1.1 build 1623.2
Compatible with Lightstreamer Server since 5.0.
Released on 31 Jan 2013
5.1.1 build 1623
Compatible with Lightstreamer Server since 5.0.
Compatible with custom clients for the previous version.
Released on 10 Jan 2013

Clarified the encoding of values in regard to UTF-16 surrogate pairs.

5.1 build 1622
Compatible with Lightstreamer Server since 5.0.
Compatible with custom clients for the previous version.
Released on 20 Dec 2012
5.0 build 1576
Compatible with Lightstreamer Server since 5.0.
May not be compatible with custom clients for the previous version; see compatibility notes below.
Released on 3 Aug 2012

Added new possible error codes, namely 7 and 8, pertaining to both the bind_session.txt request and the END push message. COMPATIBILITY NOTE: custom clients which check the possible error outcomes may have to be revised. However, the new errors are only possible when limits on the maximum number of sessions are set, either through the <max_sessions> settings or through the JMX service or by special licenses.

Introduced a 3-decimal approximation for the reported bandwidth limit values.

Slightly revised the checks for wrong requests and the related log messages issued by Lightstreamer Server.

Revised the documentation, in regard to the names of the main concepts.

4.1 build 1513.1.14
Compatible with Lightstreamer Server since 4.1.
Released on 9 Aug 2012
4.1 build 1513.1.12
Compatible with Lightstreamer Server since 4.1.
Compatible with custom clients for the previous version.

Introduced the "reconf" operation, which allows for dinamically reconfiguring the maximum frequency of currently subscribed items; see the Network Protocol Tutorial document for details.

4.0.3 build 1513.1.11
Compatible with Lightstreamer Server since 4.0.
Compatible with custom clients for the previous version.
Released on 6 Apr 2012
4.0.2 build 1513.1.8
Compatible with Lightstreamer Server since 4.0.
Compatible with custom clients for the previous version.
Released on 6 Dec 2011
4.0.1 build 1513.1.3
Compatible with Lightstreamer Server since 4.0.
Compatible with custom clients for the previous version.
Released on 20 Jul 2011
4.0 build 1513.1.1
Compatible with Lightstreamer Server since 4.0.
Released on 8 Jul 2011
4.0 build 1513
Compatible with Lightstreamer Server since 4.0.
Released on 7 Jun 2011

Introduction of Lightstreamer "Duomo" release (Server 4.0).