Lightstreamer iOS Client 1.2.6
Native iOS Client library for Lightstreamer
Public Member Functions | Static Public Member Functions | Properties

LSClient Class Reference

The LSClient class incapsulates a single connection to Lightstreamer Server. More...

#import <LSClient.h>

List of all members.

Public Member Functions

(id) - init
 Initializes a new LSClient object.
(void) - openConnectionWithInfo:delegate:
 Opens a connection to the Server with the supplied parameters.
(void) - changeConnectionWithConstraints:
 Requests new constraints to be applied on the overall data flow from the current connection.
(void) - closeConnection
 Closes the connection to the Server, if one is open.
(NSArray *) - subscribeItemsWithExtendedInfo:delegate:
 Subscribes to a set of items, which share the same schema and other subscription parameters.
(LSSubscribedTableKey *) - subscribeTableWithExtendedInfo:delegate:useCommandLogic:
 Subscribes to a table through the Server.
(LSSubscribedTableKey *) - subscribeTable:delegate:useCommandLogic:
 Subscribes to a table through the Server.
(void) - changeTableSubscription:withConstraints:
 Requests new constraints to be applied on the data flow from the specified subscription.
(void) - unsubscribeTable:
 Unsubscribes from a table previously subscribed to the Server.
(void) - unsubscribeTables:
 Unsubscribes from a set of tables previously subscribed to the Server.
(int) - sendMessage:delegate:
 Sends a message to Lightstreamer Server.
(void) - sendMessage:
 Sends a message to Lightstreamer Server.
(void) - beginBatch
 Signals that the next requests should be accumulated and sent to Lightstreamer Server with a single connection.
(NSArray *) - commitBatch
 Commits the current batch.
(void) - abortBatch
 Aborts the current batch.

Static Public Member Functions

(LSClient *) + client
 Creates and returns a new LSClient object.

Properties

BOOL connected
 Tells if the client is connected.
BOOL batching
 Tells if the client has an ongoing batch.
LSConnectionStatus connectionStatus
 Tells the current connection status.
id< LSConnectionDelegatedelegate
 Tells the current connection delegate.

Detailed Description

The LSClient class incapsulates a single connection to Lightstreamer Server.


Member Function Documentation

- (void) abortBatch

Aborts the current batch.

Pending requests will be lost: any subscription handle or progressive number obtained from a request that is part of the ongoing batch will have no value.

Exceptions:
LSPushConnectionExceptionThrown if the client is not connected.
- (void) beginBatch

Signals that the next requests should be accumulated and sent to Lightstreamer Server with a single connection.

The batch will continue to accomulate requests until a commit is requested. When the connetion is closed, any ongoing batch that has not been committed will be automatically aborted.
Note that subscription requests and message requests are batched separately: all subscriptions will be executed first, followed by messages.
Note also that batches cannot be nested: there is at most one and only batch ongoing for a given LSClient object.

Exceptions:
LSPushConnectionExceptionThrown if the client is not connected.
- (void) changeConnectionWithConstraints: (LSConnectionConstraints *)  connectionConstraints

Requests new constraints to be applied on the overall data flow from the current connection.

The new limits override the limits requested with the connection operation or the last call to this method (a constraint not set means an unlimited constraint and may override a previous limiting constraint). They can only be used in order to restrict the constraints set by Lightstreamer Server Metadata Adapter.
The method is blocking: it will return only after receiving the Server answer.

Parameters:
connectionConstraintsConstraints to be applied
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (void) changeTableSubscription: (LSSubscribedTableKey *)  tableKey
withConstraints: (LSSubscriptionConstraints *)  subscriptionConstraints 

Requests new constraints to be applied on the data flow from the specified subscription.

The new limits override the limits requested with the subscription operation or the last call to this method.
The server may refuse to apply certain constraints under specific conditions, for example when changing the max frequency of an unfiltered subscription. In these cases an LSPushServerException will be raised.
The method is blocking: it will return only after receiving the Server answer.

Parameters:
tableKeyHandle to a table as returned by a subscribe call.
subscriptionConstraintsConstraints to be applied
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
+ (LSClient *) client

Creates and returns a new LSClient object.


Note: use of multiple LSClient objects is discouraged. See the API docs home page, section "Using more than one LSClient", for more information.

Returns:
The LSClient object.
- (void) closeConnection

Closes the connection to the Server, if one is open.


The method is blocking: it will return only after the connection has been closed.

- (NSArray *) commitBatch

Commits the current batch.

Pending requests will be sent to Lightstreamer Server in the order they have been accomulated in the batch, in two separate blocks: subscription/unsubscription requests will be sent first, followed by message requests. The outcome of each request will be accomulated in a list and returned: if the outcome is positive an appropriate object will be added (i.e. NSNull for requests without return values, NSNumber for requests with boolean return value, NSString for requests with string return values, or the appropriate object for requests with object return values), else the appropriate exception will be added. The implementation guarantees an outcome for each request.
This method is blocking: it will return only after receiving the Server answer of all the requests.

Returns:
The list of the outcomes
Exceptions:
LSPushConnectionExceptionThrown if the client is not connected.
- (id) init

Initializes a new LSClient object.


Note: use of multiple LSClient objects is discouraged. See the API docs home page, section "Using more than one LSClient", for more information.

Returns:
The LSClient object.
- (void) openConnectionWithInfo: (LSConnectionInfo *)  connectionInfo
delegate: (id< LSConnectionDelegate >)  delegate 

Opens a connection to the Server with the supplied parameters.

The Server will initiate a push session for this client through a streaming connection. If a connection is open, it is closed first.
The method is blocking: it will return only after a connection has been established or the attempt has failed.

Parameters:
connectionInfoContains the Server address and the connection parameters. A copy of the object is stored internally.
delegateReceives notification for connection events.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the connection with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem while connecting to the Server.
- (void) sendMessage: (NSString *)  message

Sends a message to Lightstreamer Server.

The message is associated to the current session and is interpreted and managed by the Metadata Adapter related to the session.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediatly but the request will be processed only on batch commit.

Parameters:
messageAny text string, to be interpreted by the Metadata Adapter.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (int) sendMessage: (LSMessageInfo *)  messageInfo
delegate: (id< LSMessageDelegate >)  delegate 

Sends a message to Lightstreamer Server.

The message is associated to the current session and is interpreted and managed by the Metadata Adapter related to the session.
Upon subsequent calls to the method, the sequential management of the messages is guaranteed. However, any message that, for any reason, doesn't reach the Server can be discarded by the Server if this causes the subsequent message to be kept waiting for longer than a configurable timeout. A shorter timeout can be associated with the subsequent message itself. A sequence identifier must also be associated with the messages; the sequential management is restricted to all subsets of messages with the same sequence identifier associated. In case the sequential management is undesired the special UNORDERED_MESSAGES sequence identifier can be used.
This method is always non-blocking: it will return immediately with a valid progressive number, but the message will be submitted later. If inside a batch, the message will be submitted on batch commit (see commitBatch), reporting errors in the commit result and the outcome asynchronously to the delegate. If outside of a batch, reporting both errors and the outcome asynchronously to the delegate.

Parameters:
messageInfoThe message string to be interpreted by the Metadata Adapter, the sequence this message has to be associated with and a delay timeout to be waited by the server for missing messages before considering them lost. A copy of the object is stored internally.
delegateReceives notification of the outcome of the message request.
Returns:
A number representing the progressive number of the message within its sequence is returned (starting from 1). Note that each time a new session is established the progressive number is reset.
- (NSArray *) subscribeItemsWithExtendedInfo: (LSExtendedTableInfo *)  tableInfo
delegate: (id< LSTableDelegate >)  delegate 

Subscribes to a set of items, which share the same schema and other subscription parameters.

All item and field names are provided. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
The items are not collected as one table, but they are subscribed each in a different table. However, the items are subscribed alltogether with a single connection to the Server. The items unsubscription can be made either in a single operation (through unsubscribeTables) or through independent unsubscribe operations.
Subscribed items are identified to the listener both by position and by by name. If the request fails, no subscriptions have been performed.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediately but the request will be processed only on batch commit.

Parameters:
tableInfoContains the specification and request parameters of the items to subscribe to. A copy of the object is stored internally.
delegateReceives notification of data updates and subscription termination.
Returns:
An array of handles to the subscribed tables, one for each item. The order of the handles reflects the order of the items in the item set description. The handles are needed for unsubscription.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (LSSubscribedTableKey *) subscribeTable: (LSTableInfo *)  tableInfo
delegate: (id< LSTableDelegate >)  delegate
useCommandLogic: (BOOL)  commandLogic 

Subscribes to a table through the Server.

The table is specified by group name and schema name. Specific item and field names have to be determined by the Metadata Adapter, and are identified to the delegate only by positional information, as item and field names are not known.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediately but the request will be processed only on batch commit.

Parameters:
tableInfoContains the specification and request parameters of the items to subscribe to. A copy of the object is stored internally.
delegateReceives notification of data updates and subscription termination.
commandLogicIf YES, enables the notification of item updates with "COMMAND logic", This requires that the items are subscribed to in COMMAND mode or behave equivalently; in particular, that the special "key" and "command" fields are included in the schema.
Returns:
A handle to the subscribed table, to be used for unsubscription.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (LSSubscribedTableKey *) subscribeTableWithExtendedInfo: (LSExtendedTableInfo *)  tableInfo
delegate: (id< LSTableDelegate >)  delegate
useCommandLogic: (BOOL)  commandLogic 

Subscribes to a table through the Server.

The table is specified by providing item and field names. This requires that a LiteralBasedProvider or equivalent Metadata Adapter is configured on the Server, in order to understand the request.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediately but the request will be processed only on batch commit.

Parameters:
tableInfoContains the specification and request parameters of the items to subscribe to. A copy of the object is stored internally.
delegateReceives notification of data updates and subscription termination.
commandLogicIf YES, enables the notification of item updates with "COMMAND logic", This requires that the items are subscribed to in COMMAND mode or behave equivalently; in particular, that the special "key" and "command" fields are included in the schema.
Returns:
A handle to the subscribed table, to be used for unsubscription.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (void) unsubscribeTable: (LSSubscribedTableKey *)  tableKey

Unsubscribes from a table previously subscribed to the Server.


The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediately but the request will be processed only on batch commit.

Parameters:
tableKeyHandle to a table as returned by a subscribe call.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).
- (void) unsubscribeTables: (NSArray *)  tableKeys

Unsubscribes from a set of tables previously subscribed to the Server.

The unsubscription requests are sent to the Server in a single connection.
The method is blocking if executed outside of a batch, else it is non-blocking: outside of a batch, it will return only after receiving the Server answer. Inside a batch, the method will return immediately but the request will be processed only on batch commit.

Parameters:
tableKeysArray of handles to tables as returned by one or more subscribe calls.
Exceptions:
LSPushServerExceptionThrown in case the server refuses the request with a specific error code.
LSPushConnectionExceptionThrown in case of any other problem (including if the client is not connected).

Property Documentation

- (BOOL) batching [read, assign]

Tells if the client has an ongoing batch.

- (BOOL) connected [read, assign]

Tells if the client is connected.

If NO, any operation requiring an active connection will be refused.

- (LSConnectionStatus) connectionStatus [read, assign]

Tells the current connection status.

- (id<LSConnectionDelegate>) delegate [read, assign]

Tells the current connection delegate.


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