Subscribing to data and handling updates

Classes
protocol	<SLChannel >
	Represents a channel to a subject on the Liberator. More...
class	SLChannelListenerWrapper
	Defines a channel listener that wraps an SLChannelListener so that the callbacks are returned on the main GUI thread. More...
protocol	<SLContainerDataEvent >
	Provides information about a subscribed container and the latest changes to its structure. More...
protocol	<SLContainerElement >
	Represents an element in a container on the Liberator. When container structure changes are notified in an SLContainerDataEvent, the detailed information about which elements have been added and which have been removed is provided in an array of SLContainerElement objects. More...
protocol	<SLContainerModel >
	this protocol defines a model that represents a container. You need to implement it to process the updateModel callback in SLContainerDataEvent. More...
protocol	<SLDirectoryDataEvent >
	Provides information about a subscribed directory and the latest changes to its structure. More...
protocol	<SLDirectoryElement >
	Represents an element in a directory on the Liberator. More...
protocol	<SLJsonDataEvent >
	Provides information about a change to JSON data. More...
protocol	<SLParametersFactory >
	A factory that creates subscription parameter objects. More...
protocol	<SLRecordDataEvent >
	Provides information about a change to type 1 data (simple fieldname and data pairs) in a record. More...
protocol	<SLSubscription >
	Represents a unique subscription to a subject. More...
protocol	<SLSubscriptionDataEvent >
	Provides access to fundamental information about subscription events that relate to changes in data. This base protocol is implemented by all subscription data events. More...
protocol	<SLSubscriptionErrorEvent >
	Provides information about a subscription error. More...
protocol	<SLSubscriptionListener >
	Defines the protocol that should be implemented by the application to receive updates to subscribed data from the Liberator. More...
class	SLSubscriptionListenerWrapper
	Defines a subscription listener that wraps an SLSubscriptionListener so that the callbacks are returned on the main GUI thread. More...
protocol	<SLSubscriptionParameters >
	The base protocol for all Subscription parameter types. More...
protocol	<SLSubscriptionStatusEvent >
	Provides information about a change in the state of a subscription. More...

Enumerations
enum	SL_ErrorReason {   SL_REASON_NONE = 0, SL_REASON_USER1, SL_REASON_USER2, SL_REASON_USER3,   SL_REASON_USER4, SL_REASON_USER5, SL_REASON_LICENCE }
	Enumeration defining the reasons for an error being raised for a subscription or command. More...
enum	SL_SubjectType {   SL_SUBJECTTYPE_UNKNOWN = 200, SL_SUBJECTTYPE_PAGE = 221, SL_SUBJECTTYPE_RECORD = 222, SL_SUBJECTTYPE_NEWS = 223,   SL_SUBJECTTYPE_STORY = 224, SL_SUBJECTTYPE_CHAT = 227, SL_SUBJECTTYPE_CONTAINER = 228, SL_SUBJECTTYPE_PERMISSION = 230 }
	Enumeration that defines the subject types supported by the Liberator. More...
enum	SL_SubscriptionError {   SL_ERROR_OK = 0, SL_ERROR_NOTFOUND, SL_ERROR_UNAVAILABLE, SL_ERROR_DELETED,   SL_ERROR_READ_DENIED, SL_ERROR_WRITE_DENIED, SL_ERROR_INVALID_PARAMETERS, SL_ERROR_THROTTLE_FAILED,   SL_ERROR_CANCELLED, SL_ERROR_EXPIRED }
	Enumeration defining the errors that can occur for a subscription. More...
enum	SL_SubjectStatus { SL_STATUS_OK = 0, SL_STATUS_LIMITED, SL_STATUS_STALE, SL_STATUS_INFO }
	Enumeration that defines the status of a subject. More...

Detailed Description

StreamLink for iOS operates asynchronously. This means that when your application requests a subscription, the response is not immediately returned, but is supplied later, through a callback that is registered when the subscription was made.

The following example subscribes to the topic /DEMO/MSFT:

#import <StreamLink/StreamLink.h>

@interface ExampleSubscribeToRecord : NSObject<SLSubscriptionListener> {
}

@end

@implementation ExampleSubscribeToRecord

-(void)subscribeToRecord {
    // Create a streamlink instance that connects to the server "myliberator" with password credentials
    id<SLStreamLink> streamLink = [SLStreamLinkFactory createStreamLinkWithConfiguration:@"https://myliberator" username:@"admin" password:@"admin"];
    
    // Connect to the server
    [streamLink connect];
    
    // Subscribe to the subject /DEMO/MSFT with no parameters, with callbacks coming into this object
    id<SLSubscription> subscription = [streamLink subscribeToSubject:@"/DEMO/MSFT" subscriptionParameters:nil subscriptionListener:self];
    NSLog(@"Subscribed to %@", subscription.subject);
}

// implementation of SLSubscriptionListener protocol to simply log callbacks
-(void) recordUpdatedForSubscription:(id<SLSubscription>)subscription data:(id<SLRecordDataEvent>)data {
    NSLog(@"recordUpdatedForSubscription: subscription=[%@], data=[%@]", subscription, data);
}

-(void) containerUpdatedForSubscription:(id<SLSubscription>)subscription data:(id<SLContainerDataEvent>)data {
    NSLog(@"containerUpdatedForSubscription: subscription=[%@], data=[%@]", subscription, data);
}

-(void) errorForSubscription:(id<SLSubscription>)subscription error:(id<SLSubscriptionErrorEvent>)error {
    NSLog(@"errorForSubscription: subscription=[%@], error=[%@]", subscription, error);
}

-(void) statusForSubscription:(id<SLSubscription>)subscription status:(id<SLSubscriptionStatusEvent>)status {
    NSLog(@"statusForSubscription: subscription=[%@], status=[%@]", subscription, status);
}


@end

The following example subscribes to a subject that provides JSON data and sets up a JSON handler to handle the updates.

The following header file declares the interface for the JSON handler.

#import <Foundation/Foundation.h>
#import <StreamLink/StreamLink.h>

@interface ExampleJson : NSObject <SLConnectionListener, SLSubscriptionListener, SLJsonHandler>
{
    id<SLStreamLink> streamlink;
    id<SLSubscription> subscription;
}

@property (nonatomic, retain) id<SLStreamLink> streamlink;
@property (nonatomic, retain) id<SLSubscription> subscription;

@end

The following example subscribes to the topic /DEMO/JSON:

#import <StreamLink/StreamLink.h>
#import "ExampleJson.h"
#import <unistd.h>

@implementation ExampleJson

@synthesize streamlink;
@synthesize subscription;

-(void)dealloc
{
    [self.subscription unsubscribe];
    [self.streamlink disconnect];

    [self.subscription release];
    [self.streamlink release];

    [super dealloc];
}

-(id)init
{
    self = [super init];
    if (self != nil)
    {
        id<SLConfiguration> config = SLStreamLinkFactory.createSLConfiguration;
        config.username = @"admin";
        config.password = @"admin";
        config.liberatorURLs =@"http://192.168.1.120:18080";

        config.jsonHandler= self;
        
        self.streamlink = [SLStreamLinkFactory createStreamLinkWithSLConfiguration:config credentialsProvider:nil];
        self.streamlink.logger = [[[SLConsoleLogger alloc] initWithThresholdLevel:SL_LOG_FINEST] autorelease];

        self.subscription = [self.streamlink subscribeToSubject:@"/DEMO/JSON" subscriptionParameters:nil subscriptionListener:self];
        
        [self.streamlink addConnectionListener:self];
        [self.streamlink connect];
    }
    return self;
}

-(void) jsonUpdatedForSubscription:(id<SLSubscription>)subscription data:(id<SLJsonDataEvent>)data
{
    NSLog(@"Json Updated: %@", data);
}

-(void)connectionStatus:(id<SLConnectionStatusEvent>) connectionStatusEvent
{ 
    NSLog(@"Connection status is now %@", connectionStatusEvent);
}

-(void) serviceStatus:(id<SLConnectionServiceStatusEvent>)serviceStatusEvent
{
    NSLog(@"Connection service status for service %@", serviceStatusEvent);
}

-(void) sourceStatus:(id<SLConnectionSourceStatusEvent>) sourceStatusEvent
{
    NSLog(@"Connection source status for source %@", sourceStatusEvent);
}

// json handler methods: enable parsing and patching json strings to a library specific object representation
// NOTE: here we simply append the patches to the image and print the results
-(NSObject *) parse:(NSString *)jsonString {
    NSLog(@"parse %@", jsonString);
    return jsonString;
}

-(NSObject *) patch:(NSObject *)existingObject with:(NSString *)jsonPatchString {
    NSString *existing = (NSString*)existingObject;
    NSString *result = [existing stringByAppendingString: jsonPatchString];
    NSLog(@"patch \nexisting: %@ \npatch: %@ \nresult: %@", existing, jsonPatchString, result);
    return result;
}

@end

Enumeration Type Documentation

enum SL_ErrorReason

Enumeration defining the reasons for an error being raised for a subscription or command.

Enumerator
SL_REASON_NONE	No reason
SL_REASON_USER1	Liberator auth module user reason
SL_REASON_USER2	Liberator auth module user reason
SL_REASON_USER3	Liberator auth module user reason
SL_REASON_USER4	Liberator auth module user reason
SL_REASON_USER5	Liberator auth module user reason
SL_REASON_LICENCE	Licence failure

enum SL_SubjectStatus

Enumeration that defines the status of a subject.

Enumerator
SL_STATUS_OK	The data associated with the subject is correct and up-to-date.
SL_STATUS_LIMITED	One of the sources of data for the subject is not available. This may affect the validity of the subject's data.
SL_STATUS_STALE	The subject's data may not be correct and up-to-date.
SL_STATUS_INFO	An informational message about the subject (usually sent by the DataSource)

enum SL_SubjectType

Enumeration that defines the subject types supported by the Liberator.

Enumerator
SL_SUBJECTTYPE_UNKNOWN	The subject type is unknown.
SL_SUBJECTTYPE_PAGE	Page data type.
SL_SUBJECTTYPE_RECORD	Record data type.
SL_SUBJECTTYPE_NEWS	News data type.
SL_SUBJECTTYPE_STORY	Story data type
SL_SUBJECTTYPE_CHAT	Chat data type
SL_SUBJECTTYPE_CONTAINER	Container data type.
SL_SUBJECTTYPE_PERMISSION	Permission data type.

enum SL_SubscriptionError

Enumeration defining the errors that can occur for a subscription.

Enumerator
SL_ERROR_OK	No error.
SL_ERROR_NOTFOUND	The subject could not be found.
SL_ERROR_UNAVAILABLE	The subject was not available.
SL_ERROR_DELETED	The subject has been deleted.
SL_ERROR_READ_DENIED	The client does not have permission to read the subject.
SL_ERROR_WRITE_DENIED	The client does not have permission to write to the subject.
SL_ERROR_INVALID_PARAMETERS	The supplied container parameters are invalid
SL_ERROR_THROTTLE_FAILED	Throttle failed
SL_ERROR_CANCELLED	Command has been cancelled
SL_ERROR_EXPIRED