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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

The mode specified for this LSSubscription.

Lifecycle: this property can be read at any time.

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.

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.

Note also that 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Lifecycle: a delegate can be removed at any time.