Lightstreamer OS X Client  2.0.1
Native OS X Client library for Lightstreamer
Instance Methods | Properties | List of all members
LSSubscription Class Reference

Class representing a Subscription to be submitted to a Lightstreamer Server. More...

#import <LSSubscription.h>

Inheritance diagram for LSSubscription:

Instance Methods

(nonnull instancetype) - initWithSubscriptionMode:
 Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server. More...
 
(nonnull instancetype) - initWithSubscriptionMode:item:fields:
 Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server. More...
 
(nonnull instancetype) - initWithSubscriptionMode:items:fields:
 Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server. More...
 
(void) - addDelegate:
 Adds a delegate that will receive events from the LSSubscription instance. More...
 
(nullable NSString *) - commandValueWithItemPos:key:fieldPos:
 Returns the latest value received for the specified item/key/field combination. More...
 
(nullable NSString *) - commandValueWithItemPos:key:fieldName:
 Returns the latest value received for the specified item/key/field combination. More...
 
(nullable NSString *) - commandValueWithItemName:key:fieldPos:
 Returns the latest value received for the specified item/key/field combination. More...
 
(nullable NSString *) - commandValueWithItemName:key:fieldName:
 Returns the latest value received for the specified item/key/field combination. More...
 
(nullable NSString *) - valueWithItemPos:fieldPos:
 Returns the latest value received for the specified item/field pair. More...
 
(nullable NSString *) - valueWithItemPos:fieldName:
 Returns the latest value received for the specified item/field pair. More...
 
(nullable NSString *) - valueWithItemName:fieldPos:
 Returns the latest value received for the specified item/field pair. More...
 
(nullable NSString *) - valueWithItemName:fieldName:
 Returns the latest value received for the specified item/field pair. More...
 
(void) - removeDelegate:
 Removes a delegate from the LSSubscription instance so that it will not receive events anymore. More...
 

Properties

NSUInteger commandPosition
 Position of the "command" field in a COMMAND Subscription. More...
 
NSString * commandSecondLevelDataAdapter
 Name of the second-level Data Adapter (within the Adapter Set used by the current session) that supplies all the second-level items. More...
 
NSArray * commandSecondLevelFields
 The "Field List" to be subscribed to through Lightstreamer Server for the second-level items. More...
 
NSString * commandSecondLevelFieldSchema
 The "Field Schema" to be subscribed to through Lightstreamer Server for the second-level items. More...
 
NSString * dataAdapter
 Name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this Subscription. More...
 
NSArray * fields
 The "Field List" to be subscribed to through Lightstreamer Server. More...
 
NSString * fieldSchema
 The "Field Schema" to be subscribed to through Lightstreamer Server. More...
 
NSString * itemGroup
 The "Item Group" to be subscribed to through Lightstreamer Server. More...
 
NSArray * items
 The "Item List" to be subscribed to through Lightstreamer Server. More...
 
NSUInteger keyPosition
 Position of the "key" field in a COMMAND Subscription. More...
 
NSArray * delegates
 List containing the LSSubscriptionDelegate instances that were added to this client. More...
 
NSString * mode
 The mode specified for this LSSubscription. More...
 
NSString * requestedBufferSize
 Length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the Subscription. More...
 
NSString * requestedMaxFrequency
 Maximum update frequency to be requested to Lightstreamer Server for all the items in the LSSubscription. More...
 
NSString * requestedSnapshot
 Enables/disables snapshot delivery request for the items in the LSSubscription. More...
 
NSString * selector
 The selector name for all the items in the LSSubscription. More...
 
BOOL active
 Checks if the Subscription is currently "active" or not. More...
 
BOOL subscribed
 Checks if the LSSubscription is currently subscribed to through the server or not. More...
 

Detailed Description

Class representing a Subscription to be submitted to a Lightstreamer Server.


It contains subscription details and the delegates needed to process the real-time data.
After the creation, an LSSubscription object is in the "inactive" state. When a Subscription object is subscribed to on a LSLightstreamerClient object, through the subscribe: (LSLightstreamerClient) method, its state becomes "active". This means that the client activates a subscription to the required items through Lightstreamer Server and the LSSubscription object begins to receive real-time events.
A Subscription can be configured to use either an Item Group or an Item List to specify the items to be subscribed to and using either a Field Schema or Field List to specify the fields.
"Item Group" and "Item List" are defined as follows:

"Field Schema" and "Field List" are defined as follows:

It is possible to configure the LSSubscription to use a "Field List" using the fields property or by specifying it in the constructor.

Method Documentation

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

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


The same delegate can be added to several different LSSubscription instances. A delegate can be added at any time. A call to add a delegate already present will be ignored.

Parameters
delegateAn object that will receive the events as documented in the LSSubscriptionDelegate interface.
Note: delegates are stored with weak references: make sure you keep a strong reference to your delegates or they may be released prematurely.
- (nullable NSString *) commandValueWithItemName: (nonnull NSString *)  itemName
key: (nonnull NSString *)  key
fieldName: (nonnull NSString *)  fieldName 

Returns the latest value received for the specified item/key/field combination.

This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
Note that internal data is cleared when the LSSubscription is unsubscribed from.

Parameters
itemNamean item in the configured "Item List"
keythe value of a key received on the COMMAND subscription.
fieldNamea item in the configured "Field List"
Exceptions
NSExceptionif an invalid item name or field name is specified.
NSExceptionif the LSSubscription mode is not COMMAND.
Returns
the current value for the specified field of the specified key within the specified item (possibly nil), or nil if the specified key has not been added yet (note that it might have been added and then deleted).
- (nullable NSString *) commandValueWithItemName: (nonnull NSString *)  itemName
key: (nonnull NSString *)  key
fieldPos: (NSUInteger)  fieldPos 

Returns the latest value received for the specified item/key/field combination.

This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
Note that internal data is cleared when the LSSubscription is unsubscribed from.

Parameters
itemNamean item in the configured "Item List"
keythe value of a key received on the COMMAND subscription.
fieldPosthe 1-based position of a field within the configured "Field Schema" or "Field List"
Exceptions
NSExceptionif an invalid item name is specified.
NSExceptionif the specified field position is out of bounds.
Returns
the current value for the specified field of the specified key within the specified item (possibly nil), or nil if the specified key has not been added yet (note that it might have been added and then deleted).
- (nullable NSString *) commandValueWithItemPos: (NSUInteger)  itemPos
key: (nonnull NSString *)  key
fieldName: (nonnull NSString *)  fieldName 

Returns the latest value received for the specified item/key/field combination.

This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
Note that internal data is cleared when the LSSubscription is unsubscribed from.

Parameters
itemPosthe 1-based position of an item within the configured "Item Group" or "Item List"
keythe value of a key received on the COMMAND subscription.
fieldNamea item in the configured "Field List"
Exceptions
NSExceptionif an invalid field name is specified.
NSExceptionif the specified item position is out of bounds.
NSExceptionif the KSSubscription mode is not COMMAND.
Returns
the current value for the specified field of the specified key within the specified item (possibly nil), or nil if the specified key has not been added yet (note that it might have been added and then deleted).
- (nullable NSString *) commandValueWithItemPos: (NSUInteger)  itemPos
key: (nonnull NSString *)  key
fieldPos: (NSUInteger)  fieldPos 

Returns the latest value received for the specified item/key/field combination.

This method can only be used if the Subscription mode is COMMAND. Subscriptions with two-level behavior are also supported, hence the specified field can be either a first-level or a second-level one.
It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
Note that internal data is cleared when the LSSubscription is unsubscribed from.

Parameters
itemPosthe 1-based position of an item within the configured "Item Group" or "Item List"
keythe value of a key received on the COMMAND subscription.
fieldPosthe 1-based position of a field within the configured "Field Schema" or "Field List"
Exceptions
NSExceptionif the specified item position or field position is out of bounds.
NSExceptionif the LSSubscription mode is not COMMAND.
Returns
the current value for the specified field of the specified key within the specified item (possibly nil), or nil if the specified key has not been added yet (note that it might have been added and then deleted).
- (nonnull instancetype) initWithSubscriptionMode: (nonnull NSString *)  subscriptionMode

Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server.


The object can be supplied to subscribe: (LSLightstreamerClient) and unsubscribe: (LSLightstreamerClient), in order to bring the LSSubscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is requestedMaxFrequency.

Parameters
subscriptionModethe subscription mode for the items, required by Lightstreamer Server. Permitted values are:
  • MERGE
  • DISTINCT
  • RAW
  • COMMAND
- (nonnull instancetype) initWithSubscriptionMode: (nonnull NSString *)  subscriptionMode
item: (nonnull NSString *)  item
fields: (nonnull NSArray *)  fields 

Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server.


The object can be supplied to subscribe: (LSLightstreamerClient) and unsubscribe: (LSLightstreamerClient), in order to bring the LSSubscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is requestedMaxFrequency.

Parameters
subscriptionModethe subscription mode for the items, required by Lightstreamer Server. Permitted values are:
  • MERGE
  • DISTINCT
  • RAW
  • COMMAND
itemthe item name to be subscribed to through Lightstreamer Server.
fieldsan array of fields for the items to be subscribed to through Lightstreamer Server.
It is also possible to specify the "Field List" or "Field Schema" later through fields and fieldSchema.
Exceptions
NSExceptionIf no or invalid subscription mode is passed.
NSExceptionIf either the item or the fields array is left nil.
NSExceptionIf the specified "Field List" is not valid; see fields for details..
- (nonnull instancetype) initWithSubscriptionMode: (nonnull NSString *)  subscriptionMode
items: (nonnull NSArray *)  items
fields: (nonnull NSArray *)  fields 

Creates an object to be used to describe an LSSubscription that is going to be subscribed to through Lightstreamer Server.


The object can be supplied to subscribe: (LSLightstreamerClient) and unsubscribe: (LSLightstreamerClient), in order to bring the LSSubscription to "active" or back to "inactive" state.
Note that all of the methods used to describe the subscription to the server can only be called while the instance is in the "inactive" state; the only exception is requestedMaxFrequency.

Parameters
subscriptionModethe subscription mode for the items, required by Lightstreamer Server. Permitted values are:
  • MERGE
  • DISTINCT
  • RAW
  • COMMAND
itemsan array of items to be subscribed to through Lightstreamer server.
It is also possible specify the "Item List" or "Item Group" later through items and itemGroup.
fieldsan array of fields for the items to be subscribed to through Lightstreamer Server.
It is also possible to specify the "Field List" or "Field Schema" later through fields and fieldSchema.
Exceptions
NSExceptionIf no or invalid subscription mode is passed.
NSExceptionIf either the items or the fields array is left nil.
NSExceptionIf the specified "Item List" or "Field List" is not valid; see items and fields for details.
- (void) removeDelegate: (nonnull id< LSSubscriptionDelegate >)  delegate

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


A delegate can be removed at any time.

Parameters
delegatethe delegate to be removed.
- (nullable NSString *) valueWithItemName: (nonnull NSString *)  itemName
fieldName: (nonnull NSString *)  fieldName 

Returns the latest value received for the specified item/field pair.


It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND Subscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND LSSubscriptions, use commandValueWithItemName:key:fieldName: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.

Exceptions
NSExceptionif an invalid item name or field name is specified.
Parameters
itemNamean item in the configured "Item List"
fieldNamea item in the configured "Field List"
Returns
the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
- (nullable NSString *) valueWithItemName: (nonnull NSString *)  itemName
fieldPos: (NSUInteger)  fieldPos 

Returns the latest value received for the specified item/field pair.


It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use commandValueWithItemName:key:fieldPos: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.

Exceptions
NSExceptionif an invalid item name is specified.
NSExceptionif the specified field position is out of bounds.
Parameters
itemNamean item in the configured "Item List"
fieldPosthe 1-based position of a field within the configured "Field Schema" or "Field List"
Returns
the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
- (nullable NSString *) valueWithItemPos: (NSUInteger)  itemPos
fieldName: (nonnull NSString *)  fieldName 

Returns the latest value received for the specified item/field pair.


It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND Subscriptions, use commandValueWithItemPos:key:fieldName: instead.
Note that internal data is cleared when the Subscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.

Exceptions
NSExceptionif an invalid field name is specified.
NSExceptionif the specified item position is out of bounds.
Parameters
itemPosthe 1-based position of an item within the configured "Item Group" or "Item List"
fieldNamea item in the configured "Field List"
Returns
the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.
- (nullable NSString *) valueWithItemPos: (NSUInteger)  itemPos
fieldPos: (NSUInteger)  fieldPos 

Returns the latest value received for the specified item/field pair.


It is suggested to consume real-time data by implementing and adding a proper LSSubscriptionDelegate rather than probing this method.
In case of COMMAND LSSubscriptions, the value returned by this method may be misleading, as in COMMAND mode all the keys received, being part of the same item, will overwrite each other; for COMMAND LSSubscriptions, use commandValueWithItemPos:key:fieldPos: instead.
Note that internal data is cleared when the LSSubscription is unsubscribed from.
This method can be called at any time; if called to retrieve a value that has not been received yet, then it will return nil.

Exceptions
NSExceptionif the specified item position or field position is out of bounds.
Parameters
itemPosthe 1-based position of an item within the configured "Item Group" or "Item List"
fieldPosthe 1-based position of a field within the configured "Field Schema" or "Field List"
Returns
the current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet.

Property Documentation

- (BOOL) active
readnonatomicassign

Checks if the Subscription is currently "active" or not.


Most of the Subscription properties cannot be modified if a LSSubscription is "active".
The status of a Subscription is changed to "active" through the subscribe: (LSLightstreamerClient) method and back to "inactive" through the unsubscribe: (LSLightstreamerClient) one.
This property can be accessed at any time.

Returns
YES/NO if the Subscription is "active" or not.
- (NSUInteger) commandPosition
readnonatomicassign

Position of the "command" field in a COMMAND Subscription.


This property can only be used if the Subscription mode is COMMAND and the LSSubscription was initialized using a "Field Schema".
This property can be called at any time after the first LSSubscriptionDelegate::subscriptionDidSubscribe event.

Exceptions
NSExceptionif the LSSubscription mode is not COMMAND or if the LSSubscriptionDelegate::subscriptionDidSubscribe event for this LSSubscription was not yet fired.
NSExceptionif a "Field List" was specified.
- (NSString*) commandSecondLevelDataAdapter
readwritenonatomiccopy

Name of the second-level Data Adapter (within the Adapter Set used by the current session) that supplies all the second-level items.


All the possible second-level items should be supplied in "MERGE" mode with snapshot available.
The Data Adapter name is configured on the server side through the "name" attribute of the <data_provider> element, in the "adapters.xml" file that defines the Adapter Set (a missing attribute configures the "DEFAULT" name).
Default: the default Data Adapter for the Adapter Set, configured as "DEFAULT" on the Server.
This property can only be changed while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription mode is not "COMMAND".
- (NSArray*) commandSecondLevelFields
readwritenonatomiccopy

The "Field List" to be subscribed to through Lightstreamer Server for the second-level items.

It can only be used on COMMAND Subscriptions.
Any change to this property will override any "Field List" or "Field Schema" previously specified for the second-level.
Setting this property enables the two-level behavior: in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying LSSubscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item LSSubscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other LSSubscription properties are left as the default. When the key is deleted by a DELETE command on the first-level LSSubscription, the associated second-level LSSubscription is also unsubscribed from.
Specifying nil as parameter will disable the two-level behavior.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif any of the field names in the "Field List" contains a space or is a number or is empty/nil.
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription mode is not "COMMAND".
- (NSString*) commandSecondLevelFieldSchema
readwritenonatomiccopy

The "Field Schema" to be subscribed to through Lightstreamer Server for the second-level items.

It can only be used on COMMAND Subscriptions.
Any change to this property will override any "Field List" or "Field Schema" previously specified for the second-level.
Setting this property enables the two-level behavior: in synthesis, each time a new key is received on the COMMAND Subscription, the key value is treated as an Item name and an underlying Subscription for this Item is created and subscribed to automatically, to feed fields specified by this method. This mono-item LSSubscription is specified through an "Item List" containing only the Item name received. As a consequence, all the conditions provided for subscriptions through Item Lists have to be satisfied. The item is subscribed to in "MERGE" mode, with snapshot request and with the same maximum frequency setting as for the first-level items (including the "unfiltered" case). All other LSSubscription properties are left as the default. When the key is deleted by a DELETE command on the first-level LSSubscription, the associated second-level LSSubscription is also unsubscribed from.
Specifying nil as parameter will disable the two-level behavior.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription mode is not "COMMAND".
- (NSString*) dataAdapter
readwritenonatomiccopy

Name of the Data Adapter (within the Adapter Set used by the current session) that supplies all the items for this Subscription.


The Data Adapter name is configured on the server side through the "name" attribute of the "data_provider" element, in the "adapters.xml" file that defines the Adapter Set (a missing attribute configures the "DEFAULT" name).
Note that if more than one Data Adapter is needed to supply all the items in a set of items, then it is not possible to group all the items of the set in a single Subscription. Multiple LSSubscriptions have to be defined.
Default: the default Data Adapter for the Adapter Set, configured as "DEFAULT" on the Server.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the LSSubscription is currently "active".
- (NSArray*) delegates
readnonatomicassign

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

- (NSArray*) fields
readwritenonatomiccopy

The "Field List" to be subscribed to through Lightstreamer Server.


Any change to this property will override any "Field List" or "Field Schema" previously specified.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif any of the field names in the list contains a space or is a number or is empty/nil.
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription was initialized with a "Field Schema" or was not initialized at all.
- (NSString*) fieldSchema
readwritenonatomiccopy

The "Field Schema" to be subscribed to through Lightstreamer Server.


Any change to this property will override any "Field List" or "Field Schema" previously specified.
This property can only be set while the LSSubscription instance is in its "inactive" state.
NOTE: In the current version, the implementation is incomplete. If the subscription is in COMMAND mode changing this property will result in a LSSubscriptionDelegate::subscription:didFailWithError:message: with code 23.

Exceptions
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription was initialized with a "Field List" or was not initialized at all.
- (NSString*) itemGroup
readwritenonatomiccopy

The "Item Group" to be subscribed to through Lightstreamer Server.


Any change to this property will override any "Item List" or "Item Group" previously specified.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the Subscription is currently "active".
NSExceptionif the Subscription was initialized with an "Item List" or was not initialized at all.
- (NSArray*) items
readwritenonatomiccopy

The "Item List" to be subscribed to through Lightstreamer Server.


Any change to this property will override any "Item List" or "Item Group" previously specified.
This property can only be set while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif any of the item names in the "Item List" contains a space or is a number or is empty/nil.
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the LSSubscription was initialized with an "Item Group" or was not initialized at all.
- (NSUInteger) keyPosition
readnonatomicassign

Position of the "key" field in a COMMAND Subscription.


This property can only be accessed if the LSSubscription mode is COMMAND and the LSSubscription was initialized using a "Field Schema".
This method can be called at any time.

Exceptions
NSExceptionif the LSSubscription mode is not COMMAND or if the subscriptionDidSubscribe: (LSSubscriptionDelegate-p) event for this LSSubscription was not yet fired.
- (NSString*) mode
readnonatomicassign

The mode specified for this LSSubscription.


This property can be accessed at any time.

- (NSString*) requestedBufferSize
readwritenonatomiccopy

Length to be requested to Lightstreamer Server for the internal queuing buffers for the items in the Subscription.


A Queuing buffer is used by the Server to accumulate a burst of updates for an item, so that they can all be sent to the client, despite of bandwidth or frequency limits. It can be used only when the subscription mode is MERGE or DISTINCT and unfiltered dispatching has not been requested. If the string "unlimited" is supplied, then the buffer length is decided by the Server (the check is case insensitive). Note that the Server may pose an upper limit on the size of its internal buffers.
Default: nil, meaning to not request a buffer size to the server; this means that the buffer size will be 1 for MERGE subscriptions and "unlimited" for DISTINCT subscriptions. See the "General Concepts" document for further details.
This property can only be changed while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the specified value is not nil nor "unlimited" nor a valid positive integer number.
- (NSString*) requestedMaxFrequency
readwritenonatomiccopy

Maximum update frequency to be requested to Lightstreamer Server for all the items in the LSSubscription.


The maximum update frequency is expressed in updates per second and applies for each item in the LSSubscription; for instance, with a setting of 0.5, for each single item, no more than one update every 2 seconds will be received. If the string "unlimited" is supplied, then the maximum frequency is decided by the Server. It is also possible to supply the string "unfiltered", to ask for unfiltered dispatching, if it is allowed for the items, or a nil value to avoid sending any frequency request to the server. The check for the string constants is case insensitive.
It can be used only if the Subscription mode is MERGE, DISTINCT or COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key).
Note that frequency limits on the items can also be set on the server side and this request can only be issued in order to furtherly reduce the frequency, not to rise it beyond these limits.
This property can also be set to request unfiltered dispatching for the items in the Subscription. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item.
A further global frequency limit is also imposed by the Server, if it is running in Presto edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
A further global frequency limit is also imposed by the Server, if it is running in Allegro edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
A further global frequency limit is also imposed by the Server, if it is running in Moderato edition; this specific limit also applies to RAW mode and to unfiltered dispatching.
Default: nil, meaning to not request any frequency limit to the server. As a consequence the server will try to not apply any frequency limit to the subscription (i.e.: "unlimited", see the "General Concepts" document for further details)
This method can can be called at any time with some differences based on the LSSubscription status:

  • If the LSSubscription instance is in its "inactive" state then this property can be changed at will.
  • If the LSSubscription instance is in its "active" state then this property can still be changed unless its current or target value is "unfiltered" or nil. Also if the Subscription instance is in its "active" state and the connection to the server is currently open, then a request to change the frequency of the LSSubscription on the fly is sent to the server.
Exceptions
NSExceptionif the LSSubscription is currently "active" and the current value of this property is nil or "unfiltered".
NSExceptionif the LSSubscription is currently "active" and the given parameter is nil or "unfiltered".
NSExceptionif the specified value is not nil nor one of the special "unlimited" and "unfiltered" values nor a valid positive number.
- (NSString*) requestedSnapshot
readwritenonatomiccopy

Enables/disables snapshot delivery request for the items in the LSSubscription.


The snapshot delivery is expressed as "yes"/"no" to request/not request snapshot delivery (the check is case insensitive). If the LSSubscription mode is DISTINCT, instead of "yes", it is also possible to supply a number, to specify the requested length of the snapshot (though the length of the received snapshot may be less than requested, because of insufficient data or server side limits); passing "yes" means that the snapshot length should be determined only by the Server. Nil is also a valid value; if specified no snapshot preference will be sent to the server that will decide itself whether or not to send any snapshot.
The snapshot can be requested only if the LSSubscription mode is MERGE, DISTINCT or COMMAND.
Default: "yes" if the LSSubscription mode is not "RAW", nil otherwise.
This property can only be changed while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the LSSubscription is currently "active".
NSExceptionif the specified value is not "yes" nor "no" nor nil nor a valid integer positive number.
NSExceptionif the specified value is not compatible with the mode of the Subscription:
  • In case of a RAW LSSubscription only nil is a valid value;
  • In case of a non-DISTINCT LSSubscription only nil, "yes" and "no" are valid values.
- (NSString*) selector
readwritenonatomiccopy

The selector name for all the items in the LSSubscription.


The selector is a filter on the updates received. It is executed on the Server and implemented by the Metadata Adapter.
Default: nil (no selector).
This property can only be changed while the LSSubscription instance is in its "inactive" state.

Exceptions
NSExceptionif the Subscription is currently "active".
- (BOOL) subscribed
readnonatomicassign

Checks if the LSSubscription is currently subscribed to through the server or not.


This flag is switched to YES by server sent LSSubscription events, and back to NO in case of client disconnection, unsubscribe: (LSLightstreamerClient) calls and server sent unsubscription events.
This property can be accessed at any time.

Returns
YES/NO if the LSSubscription is subscribed to through the server or not.

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