Overview

StreamLink.NET provides the following capabilities:

• Record subscriptions
• Container subscriptions
• Directory subscriptions
• News headline subscriptions
• Subject creation
• Publish to a subject
• Delete a subject
• Connection status notification
• Reconnection and Failover

Future releases will provide the following capabilities:

• Auto directory subscriptions
• Batch subscriptions
• Permission subscriptions
• Data caching

Getting Started

It is recommended that you read the Caplin StreamLink 5.0 Overview to gain an understanding of:

• What StreamLink is and how it can be used.
• Fundamental StreamLink conscepts & features.
• How StreamLink fits into the Caplin Platform as a whole.
• How StreamLink can integrate with your own client application software to provide a streaming data display and support online trading of financial instruments.

There are two ways to quickly start using StreamLink.NET; either adapt the StreamLinkExamples project deployed with StreamLink.NET or write code from scratch. If you decide to start by using the StreamLinkExamples then see the Running Examples in Visual Studio section. The rest of this section will provide some basic details on how to start using StreamLink.NET from scratch.

How to use StreamLink.NET

This section contains some simple examples of how client applications can use the StreamLink 5.0 API. The examples contain some simple code fragments, illustrating how the API classes and methods are used.

The API operates asynchronously. This means that when the client code issues a subscription request or a command to StreamLink, the response is not returned immediately through the method used to issue the request or command. Instead, you must set up a listener object containing one or more callback methods, and then supply this listener to StreamLink. StreamLink calls the appropriate callback method(s) on the listener object to communicate data and command responses back to the client code. This method of operation is shown in the following examples.

Referencing Caplin.StreamLink.dll

The StreamLink.NET library is distrubed as a single Assembly file (Caplin.StreamLink.dll). To use the StreamLink.NET library you must add a reference to the DLL. For more information see the Adding a Reference to the StreamLink DLL section of StreamLinkExamples project.

Subscribing to data and receiving updates

To subscribe to data and receive updates to the data you need to

• implement (code) some interfaces from the API User Layer,
• call various methods from the API User Layer to connect to a Liberator and set up the subscription.

Implementing the interfaces

Before using StreamLink you need to implement as concrete classes an appropriate set of listener and other interfaces defined in the API User Layer. These implementations effectively integrate StreamLink with your client application.

As a minimum you need to implement an ISubscriptionListener a ICredentialsProvider.

StreamLink calls the SubscriptionListener to handle subscription events. For example, to deal with events concerning subscriptions to record-structured data, implement an Caplin.StreamLink.Subscription.Record.IRecordSubscriptionListener. This class must contain implementations of the methods RecordUpdated(), RecordType2Updated(), RecordType3Updated() to handle updates to type1, type2, and type 3 records respectively. These methods contain the code to handle the record updates in a manner suitable for the client application. At run time, StreamLink passes in to each method both the subscription to which the event relates, and the updated fields as name-value pairs."

The ISubscriptionListener also must implement a SubscriptionErrorReceived() method to deal with errors in subscriptions, and a SubscriptionStatusUpdated() method to handle changes to the status of the subscription.

The ICredentialsProvider implementation supplies the user credentials information used to log in to a Liberator. In the example shown here it merely provides a user name and password that are set in the constructor. In a real implementation the Credentials Provider would usually be rather more sophisticated. For example, it could obtain login credentials from a database, a web site, or a single sign-on system. The credentials could take the form of a digitally signed secure token.

In a fully functioned implementation you would probably also want to implement an IExceptionHandler to deal with errors raised by StreamLink, and a ILogger to record StreamLink activity.

Calling StreamLink

The following simple example shows how to use the StreamLink API to subscribe to a simple record containing a share price. The subject is /MSFT. This pattern is used for subscribing to all types of data.

• Create an instance of the StreamLink class:

      
        StreamLink myStreamLink = new StreamLink();
      
    

This parameterless constructor call picks up configuration information from a default configuration file. There are variants of the constructor that enable you to obtain the configuration from a specified file or via a class that implements the Caplin.StreamLink.IStreamLinkConfiguration interface. The configuration data includes a specification of which Liberator StreamLink should use and what type of RTTP connection it should establish. For more information see the StreamLink Configuration XML Reference 5.0 document.

• Set up a CredentialsProvider with the login information that Liberator needs:

      
        ICredentialsProvider myCredentialsProvider = new PasswordCredentialsProvider("admin", "admin");
        myStreamLink.CredentialsProvider = myCredentialsProvider;
      
    

• Set up the subscription listener:

      
        IRecordSubscriptionListener mySubsListener = new MyRecordSubscriptionListener();"
      
    

• Get the StreamLinkProvider. The StreamLinkProvider object provides access to the majority of the StreamLink functionality; in this example it creates the subscription."

      
        IStreamLinkProvider myStreamLinkProvider = myStreamLink.StreamLinkProvider;
      
    

• Create a subscription to /DEMO/MSFT via the StreamLinkProvider, supplying the subscription listener that ill receive updates, events, and errors relating to the subscribed data item:

      
        IRecordSubscription myRecordSubscription =
        myStreamLinkProvider.CreateRecordSubscription(mySubsListener, "/MSFT");
      
    

• Now issue a Subscribe command to queue the subscription request. The request remains queued until StreamLink logs in to the Liberator.

      
        myRecordSubscription.Subscribe();
      
    

• Connect to the Liberator:

      
        myStreamLinkProvider.Connect();
      
    

StreamLink connects to the Liberator defined in its configuration and logs in to the Liberator using the details previously set up in myCredentialsProvider. Some time later Liberator returns an image of the /MSFT record through a call to the RecordUpdated() method of mySubsListener (instantiation of MyRecordSubscriptionListener). Subsequently, each time StreamLink receives an update to /MSFT, it calls RecordUpdated() passing the updated fields and their new values. You only need to connect to the Liberator once; subsequent subscribe commands are passed to the Liberator immediately.

Subscribing to more than one data item

The StreamLink API supports subscriptions to multiple data items using a single connection to the server. As a result, there is no need to create multiple instances of the StreamLink class in order to make multiple requests. For example, you can subscribe to multiple records and receive updates into a single instance of RecordSubscriptionListener. However, StreamLink also allows you to register a different listener for each subscribed item.

Creating a data item on Liberator

This example shows how a client application can use StreamLink to modify data on a Liberator server. In this case the application creates a new record data item. This pattern is used for issuing all StreamLink commands.

Note that creating a data item on Liberator is only possible if no DataSources own the namespace that the object resides in. For example, publishing an object with the name /RECORDS/NEWRECORD will fail if a DataSource is configured to provide objects in the /RECORDS/* namespace.

• The application will need to issue a command to StreamLink, so the first thing to do is implement an ICommandListener to receive the results of the command. In the code fragments below the command listener implementation is called MyCommandListener.

• Create an instance of the StreamLink class and set up a CredentialsProvider with the login information that Liberator needs (see Subscribing to data and receiving updates):

      
        StreamLink myStreamLink = new StreamLink();

        ICredentialsProvider myCredentialsProvider = new PasswordCredentialsProvider("admin", "admin");
        myStreamLink.CredentialsProvider = myCredentialsProvider;
      
    

• Get the StreamLinkProvider. The StreamLinkProvider object provides access to the majority of the StreamLink functionality; in this example it provides access to the ParametersFactory, described below.

      
        IStreamLinkProvider myStreamLinkProvider = myStreamLink.StreamLinkProvider;
      
    

• Get the ParametersFactory used to create parameters for the command:

      
        IParametersFactory myParametersFactory = myStreamLinkProvider.ParametersFactory;
      
    

• Set up the parameters needed to create the subject. These are predefined for each type of data item and are identified by an "enum". In this case the enum is Caplin.StreamLink.SubjectType.Record.

      
        ICreateParameters subjectCreationParameters =
        myParametersFactory.CreateCreateParameters(Caplin.StreamLink.SubjectType.Record);
      
    

• Set up the command listener:

      
        ICommandListener myCommandListener = new MyCommandListener();
      
    

• Issue a "Create Subject" command to the StreamLinkProvider to create the subject. Assuming the application is already connected to the Liberator, StreamLink will send the command immediately.

        
          myStreamLinkProvider.CreateSubject(myCommandListener, "/MyRecord", subjectCreationParameters);
        
      

When the command has executed successfully, StreamLink calls the CommandSuccess() method of myCommandListener (instantiation of MyCommandListener). If the command fails, for example because the user does not have permission to create record subjects on Liberator, StreamLink calls CommandError() instead.

Architecture

StreamLink.NET is organized into four layers.

The API User Layer defines interfaces that the API user implements ^†.

The API Implementation Layer contains interfaces, classes and enums that you will use in your code. You should not implement any of the interfaces defined in this layer, as they are already implemented for you.

The Subscription and Command Management Layer is internal to StreamLink. It implements the functionality of the StreamLink API; managing subscriptions, implementing the commands issued from the API User Layer, making calls on the RTTP protocol layer, and handling data and status information received from RTTP for onward transmission to the callback methods you have defined in the API User Layer.

The RTTP Protocol Layer contains the RTTP implementation which deals with communication with the Liberator. This layer is also internal to StreamLink.

^† The API User Layer does contain one implemented interface, namely PasswordCredentialsProvider. This is a basic implementation of ICredentialsProvider; it provides the ability to log in to the Liberator using a username and password.