trek::ApiClient Class Reference

Provides functions that are common to all C++ TReK APIs. More...

#include <api_client.h>

Inherited by trek::CommandApi, and trek::TelemetryApi.

Public Member Functions
Setup Methods
These methods control setting up the API.
int32_t	Connect (const char *name)
	Connects this instance of the API to TReK for the specified destination. More...
int32_t	Disconnect ()
	Disconnects from the destination. More...
General API Methods
These methods control the behavior of the API.
void	SetWaitTimeout (uint32_t timeout)
	Sets the timeout value for API calls that require communicating with TReK. More...
uint32_t	GetWaitTimeout ()
	Returns the current timeout value for API calls. More...
int32_t	Cleanse ()
	Cleans up any resources from crashed user programs. More...
bool	IsConnected ()
	Returns true if API is connected. More...
	ApiClient ()
	Default constructor. More...
virtual	~ApiClient ()
	Class destructor. More...

Detailed Description

Provides functions that are common to all C++ TReK APIs.

Constructor & Destructor Documentation

ApiClient()

trek::ApiClient::ApiClient

(

)

Default constructor.

There are no other constructors.

~ApiClient()

trek::ApiClient::~ApiClient ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

Cleanse()

int32_t trek::ApiClient::Cleanse

(

)

Cleans up any resources from crashed user programs.

This method can be called at any time. A good practice is to call this method after a successful Connect call. This will allow TReK to remove any resources that are no longer in use by another user program.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WORKER_WAIT_ERR

Example:

TelemetryApi api;
int32_t ret_value;
 
ret_value = api.Connect( "TheName" );       // assume success
 
ret_value = api.Cleanse();      // ok if it fails.
 
printf("Even if Cleanse() failed, keep on going...it is still ok to use the API.\n");

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp tlm_api_cpp_next/cpp_next_main.cpp cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp, tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

Connect()

int32_t trek::ApiClient::Connect

(

const char *

name

)

Connects this instance of the API to TReK for the specified destination.

This method will allocate the resources necessary to communicate with TReK. When the API connection is no longer needed, Disconnect() should be called.

Parameters

[in]

name

The name to connect.

Returns

SUCCESS

TCA_ALREADY_CONNECTED

TCA_NAME_LEN_ERROR

TCA_LOCAL_MUTEX_CREATE_ERR

TCA_OPEN_SERVER_SHM_ERR

TCA_OPEN_SERVER_MUTEX_ERR

TCA_OPEN_SERVER_SEM_ERR

TCA_SERVER_WAIT_ERR

TCA_SERVER_SIGNAL_ERR

TCA_SESSION_WAIT_ERR

TCA_SESSION_REQUEST_FAIL

TCA_OPEN_WORKER_SHM_ERR

Example:

ApiClient api;
int32_t ret_value;
 
ret_value = api.Connect( "TheName" );
 
if( ret_value == SUCCESS )
    printf("Able to connect to destination\n" );
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp tlm_api_cpp_next/cpp_next_main.cpp cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp, tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

Disconnect()

int32_t trek::ApiClient::Disconnect

(

)

Disconnects from the destination.

Disconnects this instance of the API from TReK. This method will deallocate any resources used for communication with TReK.

Returns

SUCCESS

TCA_WORKER_WAIT_ERR

Example:

ApiClient api;
int32_t ret_value;
 
ret_value = api.Disconnect();
 
if( ret_value == SUCCESS )
    printf("Disconnected destination\n" );
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
tlm_api_cpp_newest/cpp_newest_main.cpp tlm_api_cpp_next/cpp_next_main.cpp cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp, tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

GetWaitTimeout()

uint32_t trek::ApiClient::GetWaitTimeout

(

)

Returns the current timeout value for API calls.

Return value is in milliseconds.

Returns

the timeout value in milliseconds

Example:

ApiClient api;
uint32_t timeout;
 
timeout = api.GetWaitTimeout();
 
printf("Timeout is %u.\n", timeout );

Longer examples that include this method:
None

IsConnected()

bool trek::ApiClient::IsConnected

(

)

Returns true if API is connected.

Example:

TelemetryApi api;
int32_t ret_value;
 
if( !api.IsConnected() )
    ret_value = api.Connect( "TheName" );       // assume success

Longer examples that include this method:
None

SetWaitTimeout()

void trek::ApiClient::SetWaitTimeout

(

uint32_t

timeout

)

Sets the timeout value for API calls that require communicating with TReK.

Any method call in this class that requires communication with TReK has a timeout value. This method will set the timeout for all other calls. The timeout should rarely occur and if it does would indicate that another process or thread has locked the command destination in TReK.

Parameters

[in]

timeout

timeout value in milliseconds

Example:

ApiClient api;
 
api.SetWaitTimeout( 5000 ); // reset to 5 seconds

Longer examples that include this method:
None