LSLightstreamerClient Class Reference

Inherits from NSObject
Declared in LSLightstreamerClient.h

Overview

Façade 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.

  LIB_NAME

A constant string representing the name of the library.

@property (class, nonatomic, readonly, nonnull) NSString *LIB_NAME

Declared In

LSLightstreamerClient.h

  LIB_VERSION

A constant string representing the version of the library.

@property (class, nonatomic, readonly, nonnull) NSString *LIB_VERSION

Declared In

LSLightstreamerClient.h

– initWithServerAddress:adapterSet:

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

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

- (nonnull instancetype)initWithServerAddress:(nullable NSString *)serverAddress adapterSet:(nullable NSString *)adapterSet

Parameters

serverAddress

The address of the Lightstreamer Server to which this LightstreamerClient will connect to. It is possible to specify it later by using nil here. See [LSConnectionDetails serverAddress] 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 nil here. See [LSConnectionDetails adapterSet] for details.

Exceptions

NSException

if a not valid address is passed. See [LSConnectionDetails serverAddress] for details.

Declared In

LSLightstreamerClient.h

  connectionOptions

Object that contains options and policies for the connection to the server.

This instance is set up by the LSLightstreamerClient object at its own creation.

Properties of this object can be overwritten by values received from a Lightstreamer Server.

@property (nonatomic, readonly, nonnull) LSConnectionOptions *connectionOptions

Declared In

LSLightstreamerClient.h

  connectionDetails

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.

@property (nonatomic, readonly, nonnull) LSConnectionDetails *connectionDetails

Declared In

LSLightstreamerClient.h

– addDelegate:

Adds a delegate that will receive events from the LSLightstreamerClient instance.

The same delegate can be added to several different LSLightstreamerClient instances.

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

- (void)addDelegate:(nonnull id<LSClientDelegate>)delegate

Parameters

delegate

An object that will receive the events as documented in the LSClientDelegate interface. Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.

Declared In

LSLightstreamerClient.h

– connect

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

When connect is called, unless a single transport was forced through [LSConnectionOptions forcedTransport], 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 of status 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 CONNECTING, CONNECTED:* or STALLED, then nothing will be done.

- (void)connect

Exceptions

NSException

if no server address was configured.

NSException

if a [LSConnectionOptions maxConcurrentSessionsPerServerExceededPolicy] of BLOCKING was specified and the current number of HTTP sessions open to the configured server address is equal to or greater than [LSConnectionOptions maxConcurrentSessionsPerServer].

Declared In

LSLightstreamerClient.h

– disconnect

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 LSSubscription 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 of status 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.

- (void)disconnect

See Also

Declared In

LSLightstreamerClient.h

  delegates

List containing the LSClientDelegate instances that were added to this client.

@property (nonatomic, readonly, nonnull) NSArray<id<LSClientDelegate> > *delegates

See Also

Declared In

LSLightstreamerClient.h

  status

Current client status and transport (when applicable).

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

@property (nonatomic, readonly, nonnull) NSString *status

Declared In

LSLightstreamerClient.h

  subscriptions

List containing all the LSSubscription instances that are currently “active” on this LightstreamerClient.

Internal second-level LSSubscription are not included.

The list can be empty.

@property (nonatomic, readonly, nonnull) NSArray<LSSubscription*> *subscriptions

See Also

Declared In

LSLightstreamerClient.h

– removeDelegate:

Removes a delegate from the LSLightstreamerClient instance so that it will not receive events anymore.

Lifecycle: a delegate can be removed at any time.

- (void)removeDelegate:(nonnull id<LSClientDelegate>)delegate

Parameters

delegate

The delegate to be removed.

See Also

Declared In

LSLightstreamerClient.h

– sendMessage:

A simplified version of the sendMessage:withSequence:timeout:delegate:enqueueWhileDisconnected:.

The internal implementation will call [self sendMessage:message withSequence:nil timeout:-1.0 delegate:nil enqueWhileDisconnected:NO].

Note that this invocation involves no sequence and no listener, hence an optimized fire-and-forget behavior will be applied.

- (void)sendMessage:(nonnull NSString *)message

Parameters

message

A text message, whose interpretation is entirely demanded to the Metadata Adapter associated to the current connection.

Declared In

LSLightstreamerClient.h

– sendMessage:withSequence:timeout:delegate:enqueueWhileDisconnected:

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. However, any message that, for any reason, doesn’t reach the Server can be discarded by the Server if this causes the subsequent message to be kept waiting for longer than a configurable timeout. Note that, because of the asynchronous transport of the requests, if a zero or very low timeout is set for a message, it is not guaranteed that the previous message can be processed, even if no communication issues occur.

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 delegate. The supplied delegate is guaranteed to be eventually invoked; delegates 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.

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 [LSClientMessageDelegate client:didAbortMessage:sentOnNetwork:] 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 YES.

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.

- (void)sendMessage:(nonnull NSString *)message withSequence:(nullable NSString *)sequence timeout:(NSTimeInterval)delayTimeout delegate:(nullable id<LSClientMessageDelegate>)delegate enqueueWhileDisconnected:(BOOL)enqueueWhileDisconnected

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 nil, UNORDERED_MESSAGES is used as the sequence name.

delayTimeout

A timeout, expressed in seconds. If higher than the Server default timeout, the latter will be used instead. The parameter is optional; if a negative value is supplied, the Server default timeout will be applied. This timeout is ignored for the special UNORDERED_MESSAGES sequence, for which a custom server-side timeout applies.

delegate

An object suitable for receiving notifications about the processing outcome. The parameter is optional; if not supplied, no notification will be available. Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.

enqueueWhileDisconnected

If this flag is set to YES, 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.

Declared In

LSLightstreamerClient.h

+ setLoggerProvider:

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

The logging system must respect the LSLoggerProvider 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.

  • lightstreamer.transport: logs lower-level transport operations (HTTP and WebSocket).

  • lightstreamer.reachability: logs network reachability status.

+ (void)setLoggerProvider:(nullable id<LSLoggerProvider>)provider

Parameters

provider

An LSLoggerProvider instance that will be used to generate log messages by the library classes.

Declared In

LSLightstreamerClient.h

– subscribe:

Operation method that adds a LSSubscription to the list of “active” subscriptions.

The LSSubscription 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 LSSubscription are automatically reissued across subsequent sessions as long as a related unsubscribe: call is not issued.

Lifecycle: an LSSubscription can be given to the LSLightstreamerClient at any time. Once done the LSSubscription immediately enters the “active” state.

Once “active”, a LSSubscription instance cannot be provided again to a LSLightstreamerClient 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 [LSSubscriptionDelegate subscriptionDidSubscribe:] event.

- (void)subscribe:(nonnull LSSubscription *)subscription

Parameters

subscription

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

See Also

Declared In

LSLightstreamerClient.h

– unsubscribe:

Operation method that removes a LSSubscription that is currently in the “active” state.

By bringing back a LSSubscription to the “inactive” state, the unsubscription from all its items is requested to Lightstreamer Server.

Lifecycle: an LSSubscription can be unsubscribed from at any time. Once done the 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 [LSSubscriptionDelegate subscriptionDidUnsubscribe:] event.

- (void)unsubscribe:(nonnull LSSubscription *)subscription

Parameters

subscription

An “active” LSSubscription object that was activated by this LSLightstreamerClient instance.

Declared In

LSLightstreamerClient.h

– registerForMPN:

Operation method that registers the MPN device on the server’s MPN Module.

By registering an MPN device, the client enables MPN functionalities such as subscribeMPN:coalescing: and resetMPNBadge.

Note: MPN is an optional feature, available depending on Edition and License Type.

Lifecycle: an LSMPNDevice can be registered at any time. The registration will be notified through a [LSMPNDeviceDelegate mpnDeviceDidRegister:] event.

Note that forwarding of the registration to the server is made in a separate thread.

- (void)registerForMPN:(nonnull LSMPNDevice *)mpnDevice

Parameters

mpnDevice

An LSMPNDevice object, carrying all the information about the MPN device.

Exceptions

NSException

if the specified device is nil.

Declared In

LSLightstreamerClient.h

– subscribeMPN:coalescing:

Operation method that subscribes an LSMPNSubscription on server’s MPN Module.

This operation adds the LSMPNSubscription to the list of “active” subscriptions. MPN subscriptions are activated on the server as soon as possible (i.e. as soon as there is a session available and subsequently as soon as the MPN device registration succeeds). Differently than real-time subscriptions, MPN subscriptions are persisted on the server’s MPN Module database and survive the session they were created on.

If the coalescing flag is set, the activation of two MPN subscriptions with the same Adapter Set, Data Adapter, Group, Schema and trigger expression will be considered the same MPN subscription. Activating two such subscriptions will result in the second activation modifying the first LSMPNSubscription (that could have been issued within a previous session). If the coalescing flag is not set, two activations are always considered different MPN subscriptions, whatever the Adapter Set, Data Adapter, Group, Schema and trigger expression are set.

The rationale behind the coalescing flag is to allow simple apps to always activate their MPN subscriptions when the app starts, without worrying if the same subscriptions have been activated before or not. In fact, since MPN subscriptions are persistent, if they are activated every time the app starts and the coalescing flag is not set, every activation is a new MPN subscription, leading to multiple push notifications for the same event.

Note: MPN is an optional feature, available depending on Edition and License Type.

Lifecycle: an LSMPNSubscription can be given to the LSLightstreamerClient once an LSMPNDevice registration has been requested. The LSMPNSubscription immediately enters the “active” state.

Once “active”, an LSMPNSubscription instance cannot be provided again to an LSLightstreamerClient unless it is first removed from the “active” state through a call to unsubscribeMPN:.

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 an [LSMPNSubscriptionDelegate mpnSubscriptionDidSubscribe:] event.

- (void)subscribeMPN:(nonnull LSMPNSubscription *)mpnSubscription coalescing:(BOOL)coalescing

Parameters

mpnSubscription

An LSMPNSubscription object, carrying all the information to route real-time data via push notifications.

coalescing

A flag that specifies if the MPN subscription must coalesce with any pre-existing MPN subscription with the same Adapter Set, Data Adapter, Group, Schema and trigger expression.

Exceptions

NSException

if the given MPN subscription does not contain a field list/field schema.

NSException

if the given MPN subscription does not contain a item list/item group.

NSException

if there is no MPN device registered.

NSException

if the given MPN subscription is already active.

Declared In

LSLightstreamerClient.h

– unsubscribeMPN:

Operation method that unsubscribes an LSMPNSubscription from the server’s MPN Module.

This operation removes the LSMPNSubscription from the list of “active” subscriptions.

Note: MPN is an optional feature, available depending on Edition and License Type.

Lifecycle: an LSMPNSubscription can be unsubscribed from at any time. Once done the 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 an [LSMPNSubscriptionDelegate mpnSubscriptionDidUnsubscribe:] event.

- (void)unsubscribeMPN:(nonnull LSMPNSubscription *)mpnSubscription

Parameters

mpnSubscription

An “active” LSMPNSubscription object.

Exceptions

NSException

if the given MPN subscription is not active.

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

– unsubscribeMultipleMPN:

Operation method that subscribes all the MPN subscriptions with a specified status from the server’s MPN Module.

By specifying a status filter it is possible to unsubscribe multiple MPN subscriptions at once. E.g. by passing TRIGGERED it is possible to unsubscribe all triggered MPN subscriptions. This operation removes the involved MPN subscriptions from the list of “active” subscriptions.

Possible filter values are:

  • ALL or nil

  • TRIGGERED

  • SUBSCRIBED

Note: MPN is an optional feature, available depending on Edition and License Type.

Lifecycle: multiple unsubscription can be requested at any time. Once done the involved MPN subscriptions immediately exit the “active” state.

Note that forwarding of the unsubscription to the server is made in a separate thread.

The unsubscription will be notified through an [LSMPNSubscriptionDelegate mpnSubscriptionDidUnsubscribe:] event to all involved MPN subscriptions.

- (void)unsubscribeMultipleMPN:(nullable NSString *)filter

Parameters

filter

An [LSMPNSubscription status] name to be used to select the MPN subscriptions to unsubscribe. If nil all existing MPN subscriptions are unsubscribed.

Exceptions

NSException

if the given filter is not valid.

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

  MPNSubscriptions

Collection of the existing MPN subscriptions.

Objects present in this collection are of type LSMPNSubscription. It contains both objects created by the user, via constructors, and objects created by the client, to represent pre-existing MPN subscriptions.

Note that objects in the collection may be substitutued at any time with equivalent ones: do not rely on pointer matching, instead rely on the [LSMPNSubscription subscriptionId] property to verify the equivalence of two LSMPNSubscription objects. Substitutions may happen when an MPN subscription is modified, or when it is coalesced with a pre-existing subscription.

Note: MPN is an optional feature, available depending on Edition and License Type.

Lifecycle: the collection is available once an LSMPNDevice registration has been requested, but reflects the actual server’s collection only after an [LSMPNDeviceDelegate mpnDeviceDidUpdateSubscriptions:] event has been notified.

@property (nonatomic, readonly, nonnull) NSArray<LSMPNSubscription*> *MPNSubscriptions

Exceptions

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

– filterMPNSubscriptions:

Inquiry method that returns a collection of the existing MPN subscription with a specified status.

Objects returned by this method are of type LSMPNSubscription. Can return both objects created by the user, via constructors, and objects created by the client, to represent pre-existing MPN subscriptions.

Note that objects returned by this method may be substitutued at any time with equivalent ones: do not rely on pointer matching, instead rely on the [LSMPNSubscription subscriptionId] property to verify the equivalence of two LSMPNSubscription objects. Substitutions may happen when an MPN subscription is modified, or when it is coalesced with a pre-existing subscription.

Possible filter values are:

  • ALL or nil

  • TRIGGERED

  • SUBSCRIBED

Note: MPN is an optional feature, available depending on Edition and License Type.

- (nonnull NSArray<LSMPNSubscription*> *)filterMPNSubscriptions:(nullable NSString *)filter

Parameters

filter

An [LSMPNSubscription status] name to be used to select the MPN subscriptions to return. If nil all existing MPN subscriptions are returned.

Exceptions

NSException

if the given filter is not valid.

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

– findMPNSubscription:

Inquiry method that returns the LSMPNSubscription with the specified subscription ID, or nil if not found.

The object returned by this method can be an object created by the user, via constructors, or an object created by the client, to represent pre-existing MPN subscriptions.

Note that objects returned by this method may be substitutued at any time with equivalent ones: do not rely on pointer matching, instead rely on the [LSMPNSubscription subscriptionId] property to verify the equivalence of two LSMPNSubscription objects. Substitutions may happen when an MPN subscription is modified, or when it is coalesced with a pre-existing subscription.

Note: MPN is an optional feature, available depending on Edition and License Type.

- (nullable LSMPNSubscription *)findMPNSubscription:(nonnull NSString *)subscriptionId

Parameters

subscriptionId

The subscription ID to search for.

Exceptions

NSException

if the given subscription ID is nil.

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

– resetMPNBadge

Operation method that resets the counter for the app badge.

If the AUTO value has been used for the app badge in the [LSMPNSubscription notificationFormat] of one or more MPN subscriptions, this operation resets the counter so that the next push notification will have badge “1”.

Note: MPN is an optional feature, available depending on Edition and License Type.

- (void)resetMPNBadge

Exceptions

NSException

if there is no MPN device registered.

Declared In

LSLightstreamerClient.h

+ addCookies:forURL:

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.

Specified cookies are actually added to the system’s shared cookie storage, which is used by both HTTP and WebSocket connections.

Lifecycle: this method can be called at any time; it will affect the internal cookie set immediately and the sending of cookies on future requests.

+ (void)addCookies:(nonnull NSArray<NSHTTPCookie*> *)cookies forURL:(nonnull NSURL *)url

Parameters

cookies

A list of cookies, represented by the system’s standard cookie object NSHTTPCookie.

url

The URL from which the supplied cookies were received.

Declared In

LSLightstreamerClient.h

+ getCookiesForURL:

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 URL to be accessed.

+ (nonnull NSArray<NSHTTPCookie*> *)getCookiesForURL:(nullable NSURL *)url

Parameters

url

The URL to which the cookies should be sent, or null.

Return Value

An immutable list with the various cookies that can be sent in a HTTP request for the specified URL. If a null URI was supplied, all available non-expired cookies will be returned. The cookies are represented by the system’s standard cookie object NSHTTPCookie.

Declared In

LSLightstreamerClient.h