Getting started with iStreamLight

Here there is little introductory guide to iStreamLight and its use. Please refer to the Lightstreamer SDK for more information about the text protocol, its terminology and its peculiarities.

Adding iStreamLight to your project

iStreamLight is distributed, for now, as pure Objective-C sources. So, download one of the 2 test projects (check versioning of the library on the project home) and copy the iStreamLight source folder inside your project.

Wherever you need to use iStreamLight, remember to import its header files, for example:

#import "../iStreamLight/LSListener.h"
#import "../iStreamLight/LSClient.h"
#import "../iStreamLight/LSSession.h"

Creating a client object

First of all, you need a client object that represents the server you are connecting to. Follow this example:

LSClient *client= [[LSClient alloc] initWithServerURL:[NSURL
  URLWithString:@"http://push.lightstreamer.com:"]];

Opening a session

The act of opening a session will actually connect to the server and keep the stream open until you (or the server) will close it. Remember that each session spawns a thread, so don't abuse of them: if you have many items to subscribe, reuse the same session as far as you can.

Here is an example:

LSSession *session= [[_client createSession:@"" password:nil 
  adapterSet:@"DEMO" listener:self options:[[LSSessionOptions alloc] init]
  autorebind:YES] retain];

Check obvious and less obvious parameters:

• user and password;
• the name of the Lightstreamer adapter set;
• the update listener (see later);
• the session options, with which you can specify max frequency, max bandwidth, content length, and so on;
• the autorebind flag.

The update listener

Before opening a session you need to setup an update listener, that is an object that implements the LSListener protocol and is able to receive the asynchronous updates. The term listener may be confusing for an Objective-C developer, but it is exactly the same concept of delegate.

The LSListener protocol specifies two mandatory methods:

- (void) onUpdate:(LSSession *)session window:(NSInteger)window table:(NSInteger)table
  item:(NSInteger)item values:(NSArray *)values;
- (void) onException:(LSSession *)session exception:(LSException *)exception;

You will receive updates sent from Lightstreamer on the onUpdate method, while the onException will receive asynchronous exceptions that could be raised.

Subscribing an item

To subscribe to an item you simply add a window or a table to an active session. Here is an example:

[session add:1 adapter:@"QUOTE_ADAPTER" table:1 group:@"item1" 
  schema:@"stock_name last_price time pct_change min max"
  selector:nil mode:LSModeMerge requestedBufferSize:0 requestedMaxFrequency:0.0
  snapshot:YES];

If the call completes successfully (i.e.: no exceptions are raised), soon after you will start receiving the updates on the listener.

Unsubscribing an item

You cannot unsubscribe from a single item, but you can unsubscribe from all the items of a window by deleting it from an active session:

[session delete:1];

Soon after your listener will stop receiving updates for those items.

Silent subscribe

If you need a silent subscribe, that is a subscription that does not start pushing immediately (see the text protocol SDK for typical use cases of this function), you can do that by using the addSilent method, followed by the start method when you actually want to start the push:

[session addSilent:2 adapter:@"QUOTE_ADAPTER" table:1 group:@"item1" 
  schema:@"stock_name last_price time pct_change min max" 
  selector:nil mode:LSModeMerge requestedBufferSize:0 requestedMaxFrequency:0.0
  snapshot:YES];

And then:

[session start:2];

Sending messages

You can even send messages to the Lightstreamer adapter by using sendMessage method. Remember that it is up to the adapter what to do with the message. Here is an example:

[session sendMessage:@"Is there anybody out there?"];

Issues and support

If you should find any issue with iStreamLight, feel free to post it on the issue tracker. If you need direct support you can send an e-mail to the user support at the domain flyingdolphinstudio dot com.