<LSSubscriptionDelegate > Protocol Reference

Interface to be implemented to receive LSSubscription events comprehending notifications of subscription/unsubscription, updates, errors and others. More...

#import <LSSubscriptionDelegate.h>

Inheritance diagram for <LSSubscriptionDelegate >:

Instance Methods
(void)	- subscription:didClearSnapshotForItemName:itemPos:
	Event handler that is called by Lightstreamer each time a request to clear the snapshot pertaining to an item in the LSSubscription has been received from the Server. More...
(void)	- subscription:didLoseUpdates:forCommandSecondLevelItemWithKey:
	Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item that was subscribed to as a second-level subscription. More...
(void)	- subscription:didFailWithErrorCode:message:forCommandSecondLevelItemWithKey:
	Event handler that is called when the Server notifies an error on a second-level subscription. More...
(void)	- subscription:didEndSnapshotForItemName:itemPos:
	Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the LSSubscription have been received, so that real time events are now going to be received. More...
(void)	- subscription:didLoseUpdates:forItemName:itemPos:
	Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription. More...
(void)	- subscription:didUpdateItem:
	Event handler that is called by Lightstreamer each time an update pertaining to an item in the LSSubscription has been received from the Server. More...
(void)	- subscriptionDidRemoveDelegate:
	Event handler that receives a notification when the LSSubscriptionDelegate instance is removed from a LSSubscription through removeDelegate: (LSSubscription). More...
(void)	- subscriptionDidAddDelegate:
	Event handler that receives a notification when the LSSubscriptionDelegate instance is added to a LSSubscription through addDelegate: (LSSubscription). More...
(void)	- subscriptionDidSubscribe:
	Event handler that is called by Lightstreamer to notify that a LSSubscription has been successfully subscribed to through the Server. More...
(void)	- subscription:didFailWithErrorCode:message:
	Event handler that is called when the Server notifies an error on a LSSubscription. More...
(void)	- subscriptionDidUnsubscribe:
	Event handler that is called by Lightstreamer to notify that a LSSubscription has been successfully unsubscribed from. More...

Detailed Description

Interface to be implemented to receive LSSubscription events comprehending notifications of subscription/unsubscription, updates, errors and others.

Events for these delegates are dispatched by a different thread than the one that generates them. This means that, upon reception of an event, it is possible that the internal state of the client has changed. On the other hand, all the notifications for a single LSLightstreamerClient, including notifications to LSClientDelegate s, LSSubscriptionDelegate s and LSClientMessageDelegate s will be dispatched by the same thread.

Method Documentation

subscription:didClearSnapshotForItemName:itemPos:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didClearSnapshotForItemName: (nullable NSString *)  itemName itemPos: (NSUInteger)  itemPos

optional

Event handler that is called by Lightstreamer each time a request to clear the snapshot pertaining to an item in the LSSubscription has been received from the Server.

More precisely, this kind of request can occur in two cases:

• For an item delivered in COMMAND mode, to notify that the state of the item becomes empty; this is equivalent to receiving an update carrying a DELETE command once for each key that is currently active.
• For an item delivered in DISTINCT mode, to notify that all the previous updates received for the item should be considered as obsolete; hence, if the delegate were showing a list of recent updates for the item, it should clear the list in order to keep a coherent view.

Note that, if the involved Subscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). This kind of notification is not possible for second-level items (which are in MERGE mode). This event can be sent by the Lightstreamer Server since version 6.0.
NOTE: This method is only predisposed for forthcoming extensions. In the current version, when a snapshot clearing is requested on the Server side, nothing is received for items delivered in DISTINCT mode, whereas, for COMMAND mode, the Server sends all DELETE events needed to clear the snapshot.

Parameters

subscription	the LSSubscription involved.
itemName	name of the involved item. If the LSSubscription was initialized using an "Item Group" then a nil value is supplied.
itemPos	1-based position of the item within the "Item List" or "Item Group".

subscription:didEndSnapshotForItemName:itemPos:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didEndSnapshotForItemName: (nullable NSString *)  itemName itemPos: (NSUInteger)  itemPos

optional

Event handler that is called by Lightstreamer to notify that all snapshot events for an item in the LSSubscription have been received, so that real time events are now going to be received.

The received snapshot could be empty. Such notifications are sent only if the items are delivered in DISTINCT or COMMAND subscription mode and snapshot information was indeed requested for the items. By implementing this method it is possible to perform actions which require that all the initial values have been received.
Note that, if the involved LSSubscription has a two-level behavior enabled, the notification refers to the first-level item (which is in COMMAND mode). Snapshot-related updates for the second-level items (which are in MERGE mode) can be received both before and after this notification.

Parameters

subscription	the LSSubscription involved.
itemName	name of the involved item. If the Subscription was initialized using an "Item Group" then a nil value is supplied.
itemPos	1-based position of the item within the "Item List" or "Item Group".

subscription:didFailWithErrorCode:message:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didFailWithErrorCode: (NSInteger)  code message: (nullable NSString *)  message

optional

Event handler that is called when the Server notifies an error on a LSSubscription.

By implementing this method it is possible to perform recovery actions.
Note that, in order to perform a new subscription attempt, unsubscribe: (LSLightstreamerClient) and subscribe: (LSLightstreamerClient) should be issued again, even if no change to the LSSubscription attributes has been applied.

Parameters

subscription	the LSSubscription involved.
code	The error code sent by the Server. It can be one of the following: 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set 20 - session interrupted 21 - bad Group name 22 - bad Group name for this Schema 23 - bad Schema name 24 - mode not allowed for an Item 25 - bad Selector name 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only) 29 - RAW mode is not allowed by the current license terms (for special licenses only) 30 - subscriptions are not allowed by the current license terms (for special licenses only) <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation
message	The description of the error sent by the Server; it can be nil.

subscription:didFailWithErrorCode:message:forCommandSecondLevelItemWithKey:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didFailWithErrorCode: (NSInteger)  code message: (nullable NSString *)  message forCommandSecondLevelItemWithKey: (nonnull NSString *)  key

optional

Event handler that is called when the Server notifies an error on a second-level subscription.

By implementing this method it is possible to perform recovery actions.

Parameters

code	The error code sent by the Server. It can be one of the following: 14 - the key value is not a valid name for the Item to be subscribed; only in this case, the error is detected directly by the library before issuing the actual request to the Server 17 - bad Data Adapter name or default Data Adapter not defined for the current Adapter Set 20 - session interrupted 21 - bad Group name 22 - bad Group name for this Schema 23 - bad Schema name 24 - mode not allowed for an Item 25 - bad Selector name 26 - unfiltered dispatching not allowed for an Item, because a frequency limit is associated to the item 27 - unfiltered dispatching not supported for an Item, because a frequency prefiltering is applied for the item 28 - unfiltered dispatching is not allowed by the current license terms (for special licenses only) 29 - RAW mode is not allowed by the current license terms (for special licenses only) <= 0 - the Metadata Adapter has refused the subscription or unsubscription request; the code value is dependent on the specific Metadata Adapter implementation
subscription	the LSSubscription involved.
message	The description of the error sent by the Server; it can be nil.
key	The value of the key that identifies the second-level item.

subscription:didLoseUpdates:forCommandSecondLevelItemWithKey:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didLoseUpdates: (NSUInteger)  lostUpdates forCommandSecondLevelItemWithKey: (nonnull NSString *)  key

optional

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item that was subscribed to as a second-level subscription.

Such notifications are sent only if the LSSubscription was configured in unfiltered mode (second-level items are always in "MERGE" mode and inherit the frequency configuration from the first-level Subscription).
By implementing this method it is possible to perform recovery actions.

Parameters

subscription	the LSSubscription involved.
lostUpdates	the number of consecutive updates dropped for the item.
key	the value of the key that identifies the second-level item.

subscription:didLoseUpdates:forItemName:itemPos:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didLoseUpdates: (NSUInteger)  lostUpdates forItemName: (nullable NSString *)  itemName itemPos: (NSUInteger)  itemPos

optional

Event handler that is called by Lightstreamer to notify that, due to internal resource limitations, Lightstreamer Server dropped one or more updates for an item in the Subscription.

Such notifications are sent only if the items are delivered in an unfiltered mode; this occurs if the subscription mode is:

• RAW
• MERGE or DISTINCT, with unfiltered dispatching specified
• COMMAND, with unfiltered dispatching specified
• COMMAND, without unfiltered dispatching specified (in this case, notifications apply to ADD and DELETE events only)

By implementing this method it is possible to perform recovery actions.

Parameters

subscription	the LSSubscription involved.
lostUpdates	The number of consecutive updates dropped for the item.
itemName	name of the involved item. If the Subscription was initialized using an "Item Group" then a nil value is supplied.
itemPos	1-based position of the item within the "Item List" or "Item Group".

subscription:didUpdateItem:()

- (void LSSubscriptionDelegate) subscription: (nonnull LSSubscription *)  subscription didUpdateItem: (nonnull LSItemUpdate *)  itemUpdate

optional

Event handler that is called by Lightstreamer each time an update pertaining to an item in the LSSubscription has been received from the Server.

Parameters

subscription	the LSSubscription involved.
itemUpdate	a value object containing the updated values for all the fields, together with meta-information about the update itself and some helper methods that can be used to iterate through all or new values.

subscriptionDidAddDelegate:()

- (void LSSubscriptionDelegate) subscriptionDidAddDelegate: (nonnull LSSubscription *)  subscription

optional

Event handler that receives a notification when the LSSubscriptionDelegate instance is added to a LSSubscription through addDelegate: (LSSubscription).

This is the first event to be fired on the delegate.

Parameters

subscription

the LSSubscription this instance was added to.

subscriptionDidRemoveDelegate:()

- (void LSSubscriptionDelegate) subscriptionDidRemoveDelegate: (nonnull LSSubscription *)  subscription

optional

Event handler that receives a notification when the LSSubscriptionDelegate instance is removed from a LSSubscription through removeDelegate: (LSSubscription).

This is the last event to be fired on the delegate.

Parameters

subscription

the LSSubscription this instance was removed from.

subscriptionDidSubscribe:()

- (void LSSubscriptionDelegate) subscriptionDidSubscribe: (nonnull LSSubscription *)  subscription

optional

Event handler that is called by Lightstreamer to notify that a LSSubscription has been successfully subscribed to through the Server.

This can happen multiple times in the life of a LSSubscription instance, in case the Subscription is performed multiple times through unsubscribe: (LSLightstreamerClient) and subscribe: (LSLightstreamerClient). This can also happen multiple times in case of automatic recovery after a connection restart.
This notification is always issued before the other ones related to the same subscription. It invalidates all data that has been received previously.
Note that two consecutive calls to this method are not possible, as before a second subscriptionDidSubscribe: event is fired an subscriptionDidUnsubscribe: event is eventually fired.
If the involved LSSubscription has a two-level behavior enabled, second-level subscriptions are not notified.

Parameters

subscription

the LSSubscription involved.

subscriptionDidUnsubscribe:()

- (void LSSubscriptionDelegate) subscriptionDidUnsubscribe: (nonnull LSSubscription *)  subscription

optional

Event handler that is called by Lightstreamer to notify that a LSSubscription has been successfully unsubscribed from.

This can happen multiple times in the life of a LSSubscription instance, in case the LSSubscription is performed multiple times through unsubscribe: (LSLightstreamerClient) and subscribe: (LSLightstreamerClient). This can also happen multiple times in case of automatic recovery after a connection restart.
After this notification no more events can be received until a new #onSubscription event.
Note that two consecutive calls to this method are not possible, as before a second subscriptionDidUnsubscribe: event is fired an subscriptionDidSubscribe: event is eventually fired.
If the involved LSSubscription has a two-level behavior enabled, second-level unsubscriptions are not notified.

---

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

• LSSubscriptionDelegate.h