Overview

The Tsplice .NET API defines classes that allow a .NET application to interact with a Tsplice host. Generally speaking, the flow of code is as follows:

• Create an instance of a TPRI.Tsplice.Client class and set the URI of the Tsplice host.

• Call member functions of the client class to send to or retrieve data from a Tsplice host.

• Process the response data objects and/or handle exceptions thrown by the client method.

Response Data

Every Tsplice client method returns a TPRI.Tsplice.Models.ApiResponse object:

• For methods that return data, the data itself is contained in the Value property of the ApiResponse.

• For methods that retrieve a file from the host, the returned object is a FileResponse object (derived from ApiResponse) with properties such as LocalPath indicating where the file has been downloaded locally.

Error Handling

Any error that occurs during a Tsplice client method will throw an exception:

• If the exception is specific to the Tsplice interface, a TPRI.Tsplice.ClientException will be thrown with an ErrorCode property indicating the type of error and a Message property providing some description of the problem.

• Other exceptions may be thrown depending on the type of error e.g. local file I/O exception, JSON serialization exception, etc.

If a Tsplice client method returns without an exception, then the call completed successfully.

Async vs. Sync

All Tsplice client calls are defined as async calls intended to be awaited.

// Request the system status
var response = await client.GetSystemStatus();

If async calls are not possible in the calling application, the Tsplice client class offers a Sync(..) method that can be used to wrap any client async method:

// Request the system status
var response = TPRI.Tsplice.Client.Sync(() => client.GetSystemStatus());

Cancelling Long-Running Requests

Each client method includes an optional cancelToken parameter that can be used to interrupt and cancel a long-running call.

// Create a cancellation source
CancelSource = new CancellationTokenSource();

//...

try
   {
   // Download a bunch of files from the Tsplice host
   var response = await client.GetSharedFiles("SharedFolder", "*",
                                              "D:\LocalFolder\",
                                              CancelSource.Token);
   }
catch (TaskCanceledException)
   {
   // Someone called CancelSource.Cancel() before all of
   // the files were downloaded
   }

Example

Following is an example usage of the Tsplice client:

var client = new TPRI.Tsplice.Client();
client.BaseUri = new Uri("https://www.somewhere.com");

try
   {
   // Request a shared file from the Tsplice host
   var response = await client.GetSharedFile(sharePath, localPath);
   // ...
   }
catch (Exception ex)
   {
   MessageBox.Show(ex.Message);
   }