Connecting to the Liberator and receiving connection events.

Classes
protocol	<SLConnectionListener >
	Defines the protocol for receiving information about changes in the state of the StreamLink connection, the data services available from the Liberator, and the DataSources that are normally connected to the Liberator. More...
class	SLConnectionListenerWrapper
	Defines a connection listener that wraps an SLConnectionListener so that the callbacks are returned on the main GUI thread. More...
protocol	<SLConnectionServiceStatusEvent >
	Provides information about a change in the state of a data service. More...
protocol	<SLConnectionSourceStatusEvent >
	Provides information about a change in the state of a DataSource. More...
protocol	<SLConnectionStatusEvent >
	Provides information about a change in the state of the connection to the Liberator. More...
protocol	<SLStreamLink >
	Represents the StreamLink instance. More...
class	SLStreamLinkFactory
	Factory for creating SLStreamLink instances. More...

Enumerations
enum	SL_ServiceStatus { SL_SERVICE_AVAILABLE, SL_SERVICE_LIMITED, SL_SERVICE_UNAVAILABLE }
	Enumeration that defines the status of a data service. More...
enum	SL_SourceStatus { SL_SOURCE_AVAILABLE, SL_SOURCE_UNAVAILABLE }
	Enumeration that defines the status of a DataSource that is normally connected to the Liberator. More...
enum	SL_ConnectionStatus {   SL_CONN_DISCONNECTED = 1, SL_CONN_CONNECTING, SL_CONN_FAILED, SL_CONN_CONNECTED,   SL_CONN_RETRIEVING_CREDENTIALS, SL_CONN_CREDENTIALS_RETRIEVED, SL_CONN_RETRIEVING_CREDENTIALS_FAILED, SL_CONN_LOGGEDIN,   SL_CONN_LOGINFAILED, SL_CONN_EJECTED, SL_CONN_LOST, SL_CONN_RECONNECTED,   SL_CONN_UNREACHABLE }
	Enumeration that defines the state of the connection between StreamLink and the Liberator ("the server"). More...
enum	SL_LoginFailedReason {   SL_LOGINFAILED_INVALID_USER = 1, SL_LOGINFAILED_INVALID_PASS, SL_LOGINFAILED_INVALID_IP, SL_LOGINFAILED_ACCT_EXPIRED,   SL_LOGINFAILED_ALREADY_LOGGED_IN, SL_LOGINFAILED_LICENSE_SITE, SL_LOGINFAILED_LICENSE_USER, SL_LOGINFAILED_CREDENTIALSERROR,   SL_LOGINFAILED_SHUTDOWN, SL_LOGINFAILED_MONITOR_DISABLE }
	Enumeration that defines the reason why a SL_CONN_LOGINFAILED connection event was raised. More...

Detailed Description

In order to receive real-time data from a Liberator server, your application must create a SLStreamLink instance with appropriate connection details and call the [SLStreamLink connect] method. A SLStreamLink instance can be obtained from the SLStreamLinkFactory object.

The following example creates a new SLStreamLink instance using this factory method, registers a SLConnectionListener and then connects to the Liberator.

#import <StreamLink/StreamLink.h>

@interface ExampleConnectToServer : NSObject<SLConnectionListener> {
}
@end

@implementation ExampleConnectToServer

-(void)connectToServer {
    // Create a streamlink instance that connects to the server "myliberator" with password credentials
    id<SLStreamLink> streamLink = [SLStreamLinkFactory createStreamLinkWithConfiguration:@"https://myliberator" username:@"admin" password:@"admin"];
    
    // Register ourselves as a connection listener
    [streamLink addConnectionListener:self];
        
    // Connect to the server
    [streamLink connect];
}
        
// implementation of SLConnectionListener protocol to simply log callbacks
-(void)connectionStatus:(id<SLConnectionStatusEvent>) connectionStatusEvent { 
    NSLog(@"connectionStatus: connectionStatusEvent=[%@]", connectionStatusEvent);
}

-(void) serviceStatus:(id<SLConnectionServiceStatusEvent>)serviceStatusEvent {
    NSLog(@"serviceStatus: serviceStatusEvent=[%@]", serviceStatusEvent);
}
 
-(void) sourceStatus:(id<SLConnectionSourceStatusEvent>) sourceStatusEvent {
    NSLog(@"sourceStatus: sourceStatusEvent=[%@]", sourceStatusEvent);
}

-(void) statistics:(id<SLConnectionStatisticsEvent>) statisticsEvent {
    NSLog(@"statistics: statisticsEvent=[%@]", statisticsEvent);
}

@end

The callbacks on SLConnectionListener are for informational purposes; StreamLink for iOS manages the connection the Liberator and does not require any intervention from your application.

Enumeration Type Documentation

enum SL_ConnectionStatus

Enumeration that defines the state of the connection between StreamLink and the Liberator ("the server").

Although hints regarding possible transitions between ConnectionStates are given, you should not imply that this is a strict contract because network conditions may cause undocumented transitions.

The generalised sequence after calling [SLStreamLink connect] is as follows: SL_CONN_CONNECTING -> SL_CONN_CONNECTED -> SL_CONN_LOGGEDIN. At any point in time the connection could be lost which would raise the SL_CONN_LOST, at this point StreamLink would attempt to connect again to a Liberator server, starting the sequence once more.

With this in mind, it is possible to map these onto a "traffic light" component indicating connection health using the following mappings:

• RED SL_CONN_DISCONNECTED
• GREEN SL_CONN_LOGGEDIN
• AMBER All other SL_ConnectionStatus codes.

Enumerator
SL_CONN_DISCONNECTED	Disconnected from the server. When this state is raised by the StreamLink library all subscriptions have removed. StreamLink will not perform any activity until you call [SLStreamLink connect].
SL_CONN_CONNECTING	A connection attempt is in progress. If the connection attempt is successful, a SL_CONN_CONNECTED state will be raised, if the connection fails, a SL_CONN_FAILED event will be raised.
SL_CONN_FAILED	A connection attempt has failed.
SL_CONN_CONNECTED	A network connection has been established to the server. StreamLink will now attempt to log in to the Liberator session
SL_CONN_RETRIEVING_CREDENTIALS	StreamLink is attempting to obtain a set of credentials to log in to the server
SL_CONN_CREDENTIALS_RETRIEVED	StreamLink has successfully retrieved the credentials
SL_CONN_RETRIEVING_CREDENTIALS_FAILED	StreamLink has failed to retrieve the credentials
SL_CONN_LOGGEDIN	The client is now logged in to the server. In this state it is possible for StreamLink applications to receive subscription updates and receive responses to commands.
SL_CONN_LOGINFAILED	The client could not log in to the server. StreamLink will not perform any more connection attempts and will switch to the SL_CONN_DISCONNECTED state.
SL_CONN_EJECTED	The client has been ejected from the server. StreamLink will not attempt to reconnect and will switch to the SL_CONN_DISCONNECTED state.
SL_CONN_LOST	The connection to the server has been lost. StreamLink will attempt to reconnect.
SL_CONN_RECONNECTED	The connection to the server has been re-established. This should be treated as an informational event, StreamLink will switch to the SL_CONN_LOGGEDIN state to simplify implementation of your application (see the traffic light example above)
SL_CONN_UNREACHABLE	Connection to the server is not possible. This could be a result of the device losing network coverage. StreamLink will attempt to reconnect to the server when network coverage is re-established.

enum SL_LoginFailedReason

Enumeration that defines the reason why a SL_CONN_LOGINFAILED connection event was raised.

Enumerator
SL_LOGINFAILED_INVALID_USER	StreamLink can not log in to the Liberator because the user's username is incorrect.
SL_LOGINFAILED_INVALID_PASS	StreamLink can not log in to the Liberator because the user's password is incorrect.
SL_LOGINFAILED_INVALID_IP	StreamLink can not log in to the Liberator because the connection attempts is made from an invalid IP address.
SL_LOGINFAILED_ACCT_EXPIRED	StreamLink can not log in to the Liberator because the user's account has expired.
SL_LOGINFAILED_ALREADY_LOGGED_IN	StreamLink can not log in to the Liberator because the user is already logged in
SL_LOGINFAILED_LICENSE_SITE	StreamLink can not log in to the Liberator due to licensing limitations.
SL_LOGINFAILED_LICENSE_USER	StreamLink can not log in to the Liberator due to licensing limitations.
SL_LOGINFAILED_CREDENTIALSERROR	An error occurred whilst retrieving the credentials that are used to log in to the Liberator
SL_LOGINFAILED_SHUTDOWN	StreamLink can not log in to the Liberator because Liberator is scheduled to shut down
SL_LOGINFAILED_MONITOR_DISABLE	StreamLink can not log in to the Liberator because new sessions have been disabled by a monitor command

enum SL_ServiceStatus

Enumeration that defines the status of a data service.

A data service represents one or more DataSources and is configured on the Liberator server. Typically a data service represents a single logical source of data.

For more information about data services see the Caplin DataSource Overview and the Caplin Liberator Administration Guide.

Enumerator
SL_SERVICE_AVAILABLE	The data service is available.
SL_SERVICE_LIMITED	There is limited access to the data service. This typically means that not all DataSources within the service are available.
SL_SERVICE_UNAVAILABLE	The data service is not available.

enum SL_SourceStatus

Enumeration that defines the status of a DataSource that is normally connected to the Liberator.

Enumerator
SL_SOURCE_AVAILABLE	The DataSource is available.
SL_SOURCE_UNAVAILABLE	The DataSource is not available.