Lightstreamer iOS Client 3.0.1 Reference

Getting Started With the iOS, macOS and tvOS Client Libraries

The iOS, macOS and tvOS Client Libraries, from version 2.0 on, follow the Unified Client API model: a common API model used across all Lightstreamer client libraries.

Obtaining a connection and subscribing to a table is a simple and straightforward procedure:

Note: as of version 3.0, iOS, macOS and tvOS client libraries do not contain Mobile Push Notifications (MPN) APIs. They will be added in a subsequest release of the Unified Client API model. In the meantime, you can still have full MPN functionalities by using previous client libraries: 1.4.x for iOS, 1.2.x for macOS and 1.0.x for tvOS, which are still available and supported.

Importing the Framework in Your Project

The client library is packaged as a framework. This both simplifies its inclusion in your project and provides better interoperability with Swift.

To add it to your project proceed as follows:

  • In the “Build Phases” section of your Xcode project, add the framework package to the “Link Binary With Libraries” list.
  • Import the the framework in your source code with:

    #import <Lightstreamer_iOS_Client/Lightstreamer_iOS_Client.h>

    (where “_iOS_” must be changed accordingly to your target platform).

  • If you are developing with Swift, add the import statement above to your bridging header.

Creating an Instance of LSLightstreamerClient

To create an instance of LSLightstreamerClient simply allocate and initialize it.

Objective-C:

LSLightstreamerClient *client= [[LSLightstreamerClient alloc] initWithServerAddress:@"http://myserver.mydomain.com"
                                                                         adapterSet:@"MY_ADAPTER_SET"];

Swift:

let client = LSLightstreamerClient(serverAddress: "http://myserver.mydomain.com",
                                      adapterSet: "MY_ADAPTER_SET")

Connection Parameters and Starting the Connection

You can set additional connection parameters on [LSLightstreamerClient connectionDetails] and [LSLightstreamerClient connectionOptions]. Before connecting you may want to add a delegate. Done this, connect using [LSLightstreamerClient connect].

Objective-C:

client.connectionDetails.user= @"my_user";
[client.connectionDetails setPassword:@"my_password"];
client.connectionOptions.requestedMaxBandwidth= @"100";

[client addDelegate:self];

[client connect];

Swift:

client.connectionDetails.user = "my_user"
client.connectionDetails.setPassword("my_password")
client.connectionOptions.requestedMaxBandwidth = "100"

client.addDelegate(self)

client.connect()

Please note that the [LSLightstreamerClient connect] call is now asynchronous: it will not block and return immediately. You may safely use it on the main thread. Connection progress will be notified through delegate events.

Listening for Connection Events

Added delegates will receive the [LSClientDelegate client:didChangeStatus:] event each time the connection changes its status.

Objective-C:

- (void) client:(nonnull LSLightstreamerClient *)client didChangeStatus:(nonnull NSString *)status {
    if ([status hasPrefix:@"CONNECTED:"]) {
        // ...
    }
}

Swift:

func client(_ client: LSLightstreamerClient, didChangeStatus status: String) {
    if (status.hasPrefix("CONNECTED")) {
        // ...
    }
}

Once the connection is established you will receive a notification with a status beginning with “CONNECTED:”. See event documentation for more information.

Creating a Subscription

You don’t have to wait for a connection to be established to subscribe. You may safely subscribe in any moment, the subscription will be delivered to the server as soon as a session has been created.

To create a subscription allocate and initialize an LSSubscription instance and set its properties with the desired values. Once the subscription is set up, subscribe using [LSLightstreamerClient subscribe:].

Objective-C:

LSSubscription *subscription= [[LSSubscription alloc] initWithSubscriptionMode:@"MERGE"];
subscription.items= @[@"my_item_1", @"my_item_2"];
subscription.fields= @[@"my_field_1", @"my_field_2"];
subscription.dataAdapter= @"MY_ADAPTER";
subscription.requestedSnapshot= @"yes";
[subscription addDelegate:self];

[client subscribe:subscription];

Swift:

let subscription = LSSubscription(subscriptionMode: "MERGE")
subscription.items = ["my_item_1", "my_item_2"]
subscription.fields = ["my_field_1", "my_field_2"]
subscription.dataAdapter = "MY_ADAPTER"
subscription.requestedSnapshot = "yes"
subscription.addDelegate(self)

client.subscribe(subscription)

The library keeps memory of active subscriptions and automatically resubscribes them if the connection drops.

Listening for Subscription Events

Subscription delegates will receive the [LSSubscriptionDelegate subscription:didUpdateItem:] event each time an update is received.

Objective-C:

- (void) subscription:(nonnull LSSubscription *)subscription didUpdateItem:(nonnull LSItemUpdate *)itemUpdate {
    NSString *value= [itemUpdate valueWithFieldName:@"my_field_1"];
    // ...
}

Swift:

func subscription(_ subscription: LSSubscription, didUpdateItem itemUpdate: LSItemUpdate) {
    let value = itemUpdate.value(withFieldName: "my_field_1")
    // ...
}

Congratulations! Your subscription with Lightstreamer Server is now set up!

Closing the Connection

To close the connection simply call [LSLightstreamerClient disconnect].

Objective-C:

[client disconnect];

Swift:

client.disconnect()