LSSubscription Class Reference

Inherits from NSObject
Declared in LSSubscription.h

Overview

Class representing a real-time 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 an LSSubscription object is subscribed to on a LSLightstreamerClient object, through the [LSLightstreamerClient subscribe:] 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.

An LSSubscription 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:

  • “Item Group”: an Item Group is a String identifier representing a list of items. Such Item Group has to be expanded into a list of items by the getItems method of the MetadataProvider of the associated Adapter Set. When using an Item Group, items in the subscription are identified by their 1-based index within the group. It is possible to configure the LSSubscription to use an “Item Group” using the itemGroup property.

  • “Item List”: an Item List is an array of Strings each one representing an item. For the Item List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getItems has to be configured in the associated Adapter Set. Note that no item in the list can be empty, can contain spaces or can be a number. When using an Item List, items in the subscription are identified by their name or by their 1-based index within the list. It is possible to configure the subscription to use an “Item List” using the items property or by specifying it in the constructor.

“Field Schema” and “Field List” are defined as follows:

  • “Field Schema”: a Field Schema is a String identifier representing a list of fields. Such Field Schema has to be expanded into a list of fields by the getFields method of the MetadataProvider of the associated Adapter Set. When using a Field Schema, fields in the subscription are identified by their 1-based index within the schema. It is possible to configure the LSSubscription to use a “Field Schema” using the fieldSchema property.

  • “Field List”: a Field List is an array of Strings each one representing a field. For the Field List to be correctly interpreted a LiteralBasedProvider or a MetadataProvider with a compatible implementation of getFields has to be configured in the associated Adapter Set. Note that no field in the list can be empty, or can contain spaces. When using a Field List, fields in the subscription are identified by their name or by their 1-based index within the list. It is possible to configure the LSSubscription to use a “Field List” using the fields property or by specifying it in the constructor.

– initWithSubscriptionMode:

Creates an object to be used to describe a real-time subscription that is going to be subscribed to through Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribe:] and <[LSLightstreamerClient unsubscribe:]>, 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.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

  • RAW

  • COMMAND

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

Exceptions

NSException

If no or invalid subscription mode is passed.

Declared In

LSSubscription.h

– initWithSubscriptionMode:item:fields:

Creates an object to be used to describe a real-time subscription that is going to be subscribed to through Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribe:] and <[LSLightstreamerClient unsubscribe:]>, 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.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

  • RAW

  • COMMAND

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode item:(nonnull NSString *)item fields:(nonnull NSArray<NSString*> *)fields

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

item

The item name to be subscribed to through Lightstreamer Server.

fields

An 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

NSException

If no or invalid subscription mode is passed.

NSException

If either the item or the fields array is left nil.

NSException

If the specified “Field List” is not valid; see fields for details.

Declared In

LSSubscription.h

– initWithSubscriptionMode:items:fields:

Creates an object to be used to describe a real-time subscription that is going to be subscribed to through Lightstreamer Server.

The object can be supplied to [LSLightstreamerClient subscribe:] and <[LSLightstreamerClient unsubscribe:]>, 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.

Permitted values for subscription mode are:

  • MERGE

  • DISTINCT

  • RAW

  • COMMAND

- (nonnull instancetype)initWithSubscriptionMode:(nonnull NSString *)subscriptionMode items:(nonnull NSArray<NSString*> *)items fields:(nonnull NSArray<NSString*> *)fields

Parameters

subscriptionMode

The subscription mode for the items, required by Lightstreamer Server.

items

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

fields

An 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

NSException

If no or invalid subscription mode is passed.

NSException

If either the items or the fields array is left nil.

NSException

If the specified “Item List” or “Field List” is not valid; see items and fields for details.

Declared In

LSSubscription.h

– addDelegate:

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

The same delegate can be added to several different LSSubscription 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<LSSubscriptionDelegate>)delegate

Parameters

delegate

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

Declared In

LSSubscription.h

  commandPosition

Position of the “command” field in a COMMAND LSSubscription.

This property can only be used if the LSSubscription mode is COMMAND and the LSSubscription was initialized using a “Field Schema”.

Lifecycle: this property can be read at any time after the first [LSSubscriptionDelegate subscriptionDidSubscribe:] event.

@property (nonatomic, readonly) NSUInteger commandPosition

Exceptions

NSException

if the LSSubscription mode is not COMMAND or if the [LSSubscriptionDelegate subscriptionDidSubscribe:] event for this LSSubscription was not yet fired.

NSException

if a “Field List” was specified.

Declared In

LSSubscription.h

  commandSecondLevelDataAdapter

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.

Lifecycle: this property can only be change while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nullable) NSString *commandSecondLevelDataAdapter

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

if the LSSubscription mode is not COMMAND.

Declared In

LSSubscription.h

  commandSecondLevelFields

The “Field List” to be subscribed to through Lightstreamer Server for the second-level items. It can only be used on COMMAND LSSubscriptions.

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 LSSubscription, 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 property. 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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSArray<NSString*> *commandSecondLevelFields

Exceptions

NSException

if any of the field names in the “Field List” contains a space or is empty/nil.

NSException

if the LSSubscription is currently “active”.

NSException

if the LSSubscription mode is not COMMAND.

NSException

if the LSSubscription was initialized with a “Field Schema” or was not initialized at all.

Declared In

LSSubscription.h

  commandSecondLevelFieldSchema

The “Field Schema” to be subscribed to through Lightstreamer Server for the second-level items. It can only be used on COMMAND LSSubscriptions.

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 LSSubscription, 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 property. 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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSString *commandSecondLevelFieldSchema

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

if the LSSubscription mode is not COMMAND.

NSException

if the LSSubscription was initialized with a “Field List” or was not initialized at all.

Declared In

LSSubscription.h

– commandValueWithItemPos:key:fieldPos:

Returns the latest value received for the specified item/key/field combination. This method can only be used if the LSSubscription mode is COMMAND. LSSubscriptions with two-level behavior (see commandSecondLevelFields and commandSecondLevelFieldSchema) 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.

- (nullable NSString *)commandValueWithItemPos:(NSUInteger)itemPos key:(nonnull NSString *)key fieldPos:(NSUInteger)fieldPos

Parameters

itemPos

The 1-based position of an item within the configured “Item Group” or “Item List”

key

The value of a key received on the COMMAND LSSubscription.

fieldPos

The 1-based position of a field within the configured “Field Schema” or “Field List”

Return Value

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). Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and the specified item position or field position is out of bounds, or the LSSubscription mode is not COMMAND.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified item position or field position is out of bounds.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the LSSubscription mode is not COMMAND.

Declared In

LSSubscription.h

– commandValueWithItemPos:key:fieldName:

Returns the latest value received for the specified item/key/field combination. This method can only be used if the LSSubscription mode is COMMAND. LSSubscriptions with two-level behavior (see commandSecondLevelFields and commandSecondLevelFieldSchema) 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.

- (nullable NSString *)commandValueWithItemPos:(NSUInteger)itemPos key:(nonnull NSString *)key fieldName:(nonnull NSString *)fieldName

Parameters

itemPos

The 1-based position of an item within the configured “Item Group” or “Item List”

key

The value of a key received on the COMMAND LSSubscription.

fieldName

A item in the configured “Field List”

Return Value

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). Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid field name is specified, the specified item position is out of bounds or the LSSubscription mode is not COMMAND.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid field name is specified.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified item position is out of bounds.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the LSSubscription mode is not COMMAND.

Declared In

LSSubscription.h

– commandValueWithItemName:key:fieldPos:

Returns the latest value received for the specified item/key/field combination. This method can only be used if the LSSubscription mode is COMMAND. LSSubscriptions with two-level behavior (see commandSecondLevelFields and commandSecondLevelFieldSchema) 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.

- (nullable NSString *)commandValueWithItemName:(nonnull NSString *)itemName key:(nonnull NSString *)key fieldPos:(NSUInteger)fieldPos

Parameters

itemName

An item in the configured “Item List”

key

The value of a key received on the COMMAND LSSubscription.

fieldPos

The 1-based position of a field within the configured “Field Schema” or “Field List”

Return Value

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). Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid item name is specified, the specified field position is out of bounds or the LSSubscription mode is not COMMAND.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid item name is specified.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified field position is out of bounds.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the LSSubscription mode is not COMMAND.

Declared In

LSSubscription.h

– commandValueWithItemName:key:fieldName:

Returns the latest value received for the specified item/key/field combination. This method can only be used if the LSSubscription mode is COMMAND. LSSubscriptions with two-level behavior (see commandSecondLevelFields and commandSecondLevelFieldSchema) 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.

- (nullable NSString *)commandValueWithItemName:(nonnull NSString *)itemName key:(nonnull NSString *)key fieldName:(nonnull NSString *)fieldName

Parameters

itemName

An item in the configured “Item List”

key

The value of a key received on the COMMAND LSSubscription.

fieldName

An item in the configured “Field List”

Return Value

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). Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid item name or field name is specified, or the LSSubscription mode is not COMMAND.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid item name or field name is specified.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the LSSubscription mode is not COMMAND.

Declared In

LSSubscription.h

  dataAdapter

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

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 LSSubscription. Multiple LSSubscriptions have to be defined.

Default: the default Data Adapter for the Adapter Set, configured as DEFAULT on the Server.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nullable) NSString *dataAdapter

Exceptions

NSException

if the LSSubscription is currently “active”.

Declared In

LSSubscription.h

  fields

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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSArray<NSString*> *fields

Exceptions

NSException

if any of the field names in the list contains a space or is empty/nil.

NSException

if the LSSubscription is currently “active”.

NSException

when reading, if the LSSubscription was initialized with a “Field Schema” or was not initialized at all.

Declared In

LSSubscription.h

  fieldSchema

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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSString *fieldSchema

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

when reading, if the LSSubscription was initialized with a “Field List” or was not initialized at all.

Declared In

LSSubscription.h

  itemGroup

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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSString *itemGroup

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

when reading, if the LSSubscription was initialized with an “Item List” or was not initialized at all.

Declared In

LSSubscription.h

  items

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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nonnull) NSArray<NSString*> *items

Exceptions

NSException

if any of the item names in the “Item List” contains a space or is a number or is empty/nil.

NSException

if the LSSubscription is currently “active”.

NSException

when reading, if the LSSubscription was initialized with an “Item Group” or was not initialized at all.

Declared In

LSSubscription.h

  keyPosition

Position of the “key” field in a COMMAND LSSubscription.

This property can only be accessed if the LSSubscription mode is COMMAND and the LSSubscription was initialized using a “Field Schema”.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly) NSUInteger keyPosition

Exceptions

NSException

if the LSSubscription mode is not COMMAND or if the [LSSubscriptionDelegate subscriptionDidSubscribe:] event for this LSSubscription was not yet fired.

Declared In

LSSubscription.h

  delegates

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

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

See Also

Declared In

LSSubscription.h

  mode

The mode specified for this LSSubscription.

Lifecycle: this property can be read at any time.

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

Declared In

LSSubscription.h

  requestedBufferSize

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

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

Format: an integer number (e.g. 10), or unlimited, or nil.

Default: nil, meaning to lean on the Server default based on the LSSubscription mode. 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.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nullable) NSString *requestedBufferSize

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

if the specified value is not nil nor unlimited nor a valid positive integer number.

Declared In

LSSubscription.h

  requestedMaxFrequency

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 no frequency limit is requested. 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 stick to the Server default (which currently corresponds to unlimited). The check for the string constants is case insensitive.

It can be used only if the LSSubscription mode is MERGE, DISTINCT or COMMAND (in the latter case, the frequency limitation applies to the UPDATE events for each single key). For LSSubscriptions with two-level behavior (see commandSecondLevelFields and commandSecondLevelFieldSchema), the specified frequency limit applies to both first-level and second-level items.

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 LSSubscription. However, unfiltered dispatching requests may be refused if any frequency limit is posed on the server side for some item.

Edition note: a further global frequency limit could also be imposed by the Server, depending on Edition and License Type; this specific limit also applies to RAW mode and to unfiltered dispatching. To know what features are enabled by your license, please see the License tab of the Monitoring Dashboard (by default, available at /dashboard).

Format: a decimal number (e.g. 2.0), or unlimited, or unfiltered, or nil.

Default: nil, meaning to lean on the Server default based on the LSSubscription mode. This consists, for all modes, in not applying any frequency limit to the subscription (the same as unlimited); see the “General Concepts” document for further details.

Lifecycle: this property can be changed at any time with some differences based on the LSSubscription status:

  • If the LSSubscription instance is in its “inactive” state then the value can be changed at will.

  • If the LSSubscription instance is in its “active” state then he value can still be changed unless the current value is unfiltered or the supplied value is unfiltered or nil. If the LSSubscription 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.

@property (nonatomic, copy, nullable) NSString *requestedMaxFrequency

Exceptions

NSException

if the LSSubscription is currently “active” and the current value of this property is nil or unfiltered.

NSException

if the LSSubscription is currently “active” and the given parameter is nil or unfiltered.

NSException

if the specified value is not nil nor one of the special unlimited and unfiltered values nor a valid positive number.

Declared In

LSSubscription.h

  requestedSnapshot

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 an integer 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:

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

Format: yes, no, an integer number (e.g. 10), or nil.

Default: yes if the LSSubscription mode is not RAW, nil otherwise.

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nullable) NSString *requestedSnapshot

Exceptions

NSException

if the LSSubscription is currently “active”.

NSException

if the specified value is not yes nor no nor nil nor a valid integer positive number.

NSException

if the specified value is not compatible with the mode of the LSSubscription.

Declared In

LSSubscription.h

  selector

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

Lifecycle: this property can only be set while the LSSubscription instance is in its “inactive” state.

@property (nonatomic, copy, nullable) NSString *selector

Exceptions

NSException

if the LSSubscription is currently “active”.

Declared In

LSSubscription.h

– valueWithItemPos: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.

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

- (nullable NSString *)valueWithItemPos:(NSUInteger)itemPos fieldPos:(NSUInteger)fieldPos

Parameters

itemPos

The 1-based position of an item within the configured “Item Group” or “Item List”

fieldPos

The 1-based position of a field within the configured “Field Schema” or “Field List”

Return Value

The current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet. Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and the specified item position or field position is out of bounds.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified item position or field position is out of bounds.

Declared In

LSSubscription.h

– valueWithItemPos: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 LSSubscriptions, use commandValueWithItemPos:key:fieldName: instead.

Note that internal data is cleared when the LSSubscription is unsubscribed from.

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

- (nullable NSString *)valueWithItemPos:(NSUInteger)itemPos fieldName:(nonnull NSString *)fieldName

Parameters

itemPos

The 1-based position of an item within the configured “Item Group” or “Item List”

fieldName

An item in the configured “Field List”

Return Value

The current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet. Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid field name is specified or the specified item position is out of bounds.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid field name is specified.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified item position is out of bounds.

Declared In

LSSubscription.h

– valueWithItemName: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 commandValueWithItemName:key:fieldPos: instead.

Note that internal data is cleared when the LSSubscription is unsubscribed from.

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

- (nullable NSString *)valueWithItemName:(nonnull NSString *)itemName fieldPos:(NSUInteger)fieldPos

Parameters

itemName

An item in the configured “Item List”

fieldPos

The 1-based position of a field within the configured “Field Schema” or “Field List”

Return Value

The current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet. Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid item name is specified or the specified field position is out of bounds.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid item name is specified.

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and the specified field position is out of bounds.

Declared In

LSSubscription.h

– valueWithItemName: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 LSSubscriptions, use commandValueWithItemName:key:fieldName: instead.

Note that internal data is cleared when the LSSubscription is unsubscribed from.

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

- (nullable NSString *)valueWithItemName:(nonnull NSString *)itemName fieldName:(nonnull NSString *)fieldName

Parameters

itemName

An item in the configured “Item List”

fieldName

An item in the configured “Field List”

Return Value

The current value for the specified field of the specified item (possibly nil), or nil if no value has been received yet. Returns nil also if [LSLightstreamerClient limitExceptionsUse] is YES and an invalid item name or field name is specified.

Exceptions

NSException

if [LSLightstreamerClient limitExceptionsUse] is NO and an invalid item name or field name is specified.

Declared In

LSSubscription.h

  active

Checks if the LSSubscription is currently “active” or not.

Most of the LSSubscription properties cannot be modified if a LSSubscription is “active”.

The status of an LSSubscription is changed to “active” through the [LSLightstreamerClient subscribe:] method and back to “inactive” through the [LSLightstreamerClient unsubscribe:] one.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, getter=isActive) BOOL active

Declared In

LSSubscription.h

  subscribed

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

This flag is switched to YES by server sent subscription events, and back to NO in case of client disconnection, [LSLightstreamerClient unsubscribe:] calls and server sent unsubscription events.

Lifecycle: this property can be read at any time.

@property (nonatomic, readonly, getter=isSubscribed) BOOL subscribed

Declared In

LSSubscription.h

– removeDelegate:

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

Lifecycle: a delegate can be removed at any time.

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

Parameters

delegate

The delegate to be removed.

See Also

Declared In

LSSubscription.h