Timer

Table of Contents

Overview

The Tsplice .NET API can be used in a client defines classes that allow a .NET application to interact with a Tsplice host. This API consists of the following:Generally speaking, the flow of code is as follows:

Create an instance of a TPRI.Tsplice.Client - This class can be used to send a request to the Tsplice host and parse its response
TPRI.Tsplice.Models - The classes in this namespace represent the different types of data sent to or received from the Tsplice host
ApiResponse and derived classes - These classes represent the responses returned from the Tsplice host, and typically wrap a model object containing the specific response data

TPRI.Tsplice.Client

Overview

Properties

There are two types of timers covered by these libraries: wall clock timers and set interval timers.

Methods

The Tsplice Client methods are grouped below by function.

Authentication & Authorization

The following functions can be used to authenticate and authorize a user via the Tsplice API

Expand

title	Authenticate user

Code Block

///-----------------------------------------------------------------
/// <summary>
/// Authenticate the current client-side Windows user on the host.
/// </summary>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authenticate(CancellationToken cancelToken = default)

///-----------------------------------------------------------------
/// <summary>
/// Authenticate user credentials on the host.
/// </summary>
/// <param name="username">User name</param>
/// <param name="password">User password</param>
/// <param name="domain">User domain</param>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authenticate(string username, string password,
                            string domain,
                            CancellationToken cancelToken = default)

///-----------------------------------------------------------------
/// <summary>
/// Authenticate user credentials on the host.
/// </summary>
/// <param name="credentials">User credentials</param>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authenticate(Credentials credentials,
                            CancellationToken cancelToken = default)

Expand

title	Authorize user

Code Block

///-----------------------------------------------------------------
/// <summary>
/// Authorize the current client-side Windows user for a specific
/// application.
/// </summary>
/// <param name="appName">Tsecurity application name</param>
/// <param name="cancelToken"></param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authorize(string appName, 
                         CancellationToken cancelToken = default)

///-----------------------------------------------------------------
/// <summary>
/// Authorize a user for a specific application.
/// </summary>
/// <param name="appName">Tsecurity application name</param>
/// <param name="username">User name</param>
/// <param name="password">User password</param>
/// <param name="domain">User domain</param>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authorize(string appName, string username,
                         string password, string domain,
                         CancellationToken cancelToken = default)

///-----------------------------------------------------------------
/// <summary>
/// Authorize a user for a specific application.
/// </summary>
/// <param name="appName">Tsecurity application name</param>
/// <param name="credentials">User credentials</param>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Authorization token data</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<AuthToken>>
               Authorize(string appName, Credentials credentials,
                         CancellationToken cancelToken = default)

Expand

title	Domains

Code Block

///-----------------------------------------------------------------
/// <summary>
/// Get the list of available domains on the host
/// </summary>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>
/// ApiResponse object containing the list of domains
/// </returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<List<Domain>>> GetDomains(
                           CancellationToken cancelToken = default)

System Status

The following function can be used to get the current status of the Tsplice host system.

Expand

title	Get System Status

Code Block

///-----------------------------------------------------------------
/// <summary>
/// Get the Tsentry system status information
/// </summary>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>Response object</returns>
///-----------------------------------------------------------------
public async Task<JsonResponse<SystemStatus>> GetSystemStatus(
            CancellationToken cancelToken = default)

Shared Files and Folders

The following functions can be used to interact with shared folders and files on the Tsplice host system.

...

title	Get File from Host

...

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 async calls intended to be awaited.

Code Block
// 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:

Code Block
// 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.

Code Block

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

//...

try
   {
   // Download a bunch of files from the Tsplice host
   var response = await client.GetSharedFiles("SharedFolder", "*",

CancellationToken

cancelToken

=

default)

///-----------------------------------------------------------------

///

///

Download

a

shared

file

into

the

specified

location

///

</summary> ///

<param name="sharePath">Shared folder path</param> /// <param name="localPath"> /// Target file path on local system, or null to use the default /// download location /// </param> /// <param name="cancelToken">Cancellation token</param> /// <returns>FileResponse object</returns> ///----------------------------------------------------------------- public async Task<FileResponse> GetSharedFile(

"D:\LocalFolder\",

string

sharePath,

string

localPath

=

null,

                CancelSource.Token);
   }

CancellationToken cancelToken = default) ///----------------------------------------------------------------- /// <summary> /// Download files matching a filter from a shared folder into /// the specified folder /// </summary> /// <param name="sharePath">Shared folder path</param> /// <param name="search"> /// Search string, or null to match all files /// </param> /// <param name="localRoot"> /// Root folder for local files, or null to use the default /// download folder /// </param> /// <param name="cancelToken">Cancellation token</param> /// <returns>FileResponse object</returns> ///----------------------------------------------------------------- public async Task<List<FileResponse>> GetSharedFiles( string sharePath, string search = null, string localRoot = null, CancellationToken cancelToken = default)

Expand

title	Put File

Code Block

///-----------------------------------------------------------------
/// <summary>
/// Upload a shared file
/// </summary>
/// <param name="sharePath">Shared folder path</param>
/// <param name="localPath">Target file path on local system</param>
/// <param name="cancelToken">Cancellation token</param>
/// <returns>ApiResponse object</returns>
///-----------------------------------------------------------------
public async Task<ApiResponse> PutSharedFile(
                     string sharePath, string localPath,
                     CancellationToken cancelToken = default)

///----------------------------------------------------------------- /// <summary> /// Copy

catch (TaskCanceledException)
   {
   // Someone called CancelSource.Cancel() before all of
   // the files were downloaded
   }

Expand

title	Copy, Move, or Delete File

Code Block

Example

Following is an example usage of the Tsplice client:

///----------------------------------------------------------------- /// <summary> /// Delete a shared file from the host /// </summary> /// <param name="sharePath">Shared folder path</param> /// <param name="cancelToken">Cancellation token</param> /// <returns>FileResponse object</returns> ///----------------------------------------------------------------- public async Task<ApiResponse> DeleteSharedFile( string sharePath, CancellationToken cancelToken = default)

Tsplice host
   var response = await client.GetSharedFile(sharePath, localPath);
   // ...
   }
catch (Exception ex)
   {
   MessageBox.Show(ex.Message);
   }

Code Block

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

try
   {
   // Request a shared file from

one location

the

host to another /// location on the host /// </summary> /// <param name="srcSharePath">Source shared file path</param> /// <param name="dstSharePath">Destination shared file path</param> /// <param name="cancelToken">Cancellation token</param> /// <returns>ApiResponse object</returns> ///----------------------------------------------------------------- public async Task<ApiResponse> CopySharedFile( string srcSharePath, string dstSharePath, CancellationToken cancelToken = default) ///----------------------------------------------------------------- /// <summary> /// Rename or move a shared file on the host /// </summary> /// <param name="srcSharePath">Source shared file path</param> /// <param name="dstSharePath">Destination shared file path</param> /// <param name="cancelToken">Cancellation token</param> /// <returns>ApiResponse object</returns> ///----------------------------------------------------------------- public async Task<ApiResponse> MoveSharedFile( string srcSharePath, string dstSharePath, CancellationToken cancelToken = default)

Expand

title	Delete File

Code Block

Version	Old Version 2	New Version Current
Changes made by	AJ Johnson	AJ Johnson
Saved on	Feb 05, 2024	Feb 06, 2024

Versions Compared

Key

Overview

TPRI.Tsplice.Client

Overview

Properties

Methods

Authentication & Authorization

System Status

Shared Files and Folders

Response Data

Error Handling

Async vs. Sync

Cancelling Long-Running Requests

Example

Page Comparison

Versions Compared

Key

Overview

TPRI.Tsplice.Client

Overview

Properties

Methods

Authentication & Authorization

System Status

Shared Files and Folders

Response Data

Error Handling

Async vs. Sync

Cancelling Long-Running Requests

Example