trek::CommandApi Class Reference

Provides access to command features of TReK. More...

#include <command_api.h>

Inherits trek::ApiClient.

Public Member Functions
	CommandApi ()
	Default constructor. More...
virtual	~CommandApi ()
	Class destructor. More...
General API Methods
These methods control the behavior of the API.
int32_t	SetBlockingFlag (bool input)
	Sets the blocking flag for this instance of the API. More...
int32_t	GetBlockingFlag (bool &input)
	Gets the current value of the blocking flag for this instance of the API. More...
int32_t	DestinationAllowsBlocking (bool &input)
	Determines if a destination allows blocking. More...
int32_t	SetBlockingTimeout (uint32_t timeout)
	Sets the amount of time a method that supports blocking will wait to unblock. More...
int32_t	GetBlockingTimeout (uint32_t &timeout)
	Gets the current value of the blocking timeout. More...
int32_t	UnblockDestination ()
	Unblocks a destination. If the destination doesn't allow blocking, the function will still return SUCCESS. More...
int32_t	GetDestinationType (char *type, uint32_t *space_available)
	If successful, returns a string name for the destination suitable for displaying in a graphical user interface or framing above the fireplace. More...
int32_t	ReadyForRequest (bool &result)
	Determine if it is ok to send a request on the command connection. More...
Destination Information
These methods provide information about a destinations configuration and capabilities.
int32_t	GetStatusMessageList (StringArray &status_list)
	Get a list of messages that the user can send. More...
int32_t	GetStatusMessage (const char *name, ParameterCollection &pc, char *info, uint32_t *space_available)
	Get the specified status message details. More...
int32_t	GetConfigurationMessageList (StringArray &config_list)
	Get a list of messages that a destination allows to be configured by a user. More...
int32_t	GetConfigurationMessage (const char *name, ParameterCollection &pc, char *info, uint32_t *space_available)
	Get the details for a configuration message. More...
int32_t	GetCommandResponseList (StringArray &resp_list)
	Get a list of possible command responses for the command source. More...
int32_t	GetCommandResponse (const char *name, CommandResponse &resp)
	Get the details for a command response. More...
int32_t	UpdateCommand (Packet &pkt)
	Adds the specified command to the destination. More...
int32_t	UpdateDestinationCommand (const char *name)
	Sends a request to the final destination to update a command. More...
int32_t	GetCommandList (StringArray &cmd_list)
	Get a list of commands known by the command controller. More...
int32_t	GetCommand (const char *name, Packet &pkt)
	Gets the complete definition of the command from the command controller. More...
int32_t	GetStatusItem (const char *name, char *value, uint32_t *space_available)
	Gets the value of a status item. More...
int32_t	SetConfigurationItem (const char *name, const char *value)
	Sets the value of a configuration item. More...
Send Command Methods
These methods send or initiate commands.
int32_t	SendThisCommand (Packet &pkt, uint32_t &token)
	Builds the command defined by Packet and sends it to the destination. More...
int32_t	SendBinaryCommand (const char *name, const uint8_t *buf_ptr, uint32_t length, uint32_t &token)
	Sends the command identified by buf_ptr to the destination using the given name. More...
int32_t	SendTrekCommand (const char *name, uint32_t &token)
	Sends the specified command based on the current definition of the command within the command controller. More...
int32_t	InsertDataAndSendCommand (const char *name, const uint8_t *buf_ptr, uint32_t length, uint32_t &token)
	Inserts the specified data into a command's 'data zone'. More...
int32_t	InitiateCommand (const char *name, uint32_t &token)
	Sends a request to the final destination to uplink a command. More...
Public Member Functions inherited from trek::ApiClient
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...
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...

Command Track Methods
These methods allow access to command track information.
int32_t	GetTrack (uint32_t token, TrackItem &track_item)
	Find out any command track information for this 'token'. More...
int32_t	StartCommandSequence (char *full_file_name, uint32_t &token)
	Start a command sequence specified in a command sequence binary file, and get a 'token' to track the command sequence. The token can be used to stop the command sequence. More...
int32_t	StopCommandSequence (uint32_t token)
	Stop an active command sequence which correlated to a specific token. More...
int32_t	FindActiveCommandSequence (uint32_t token)
	Find an active command sequence associated with a specific token. I the command sequence is still active, this function returns SUCCESS. The function returns FAIL if the command sequence is not active. More...
int32_t	StopAllCommandSequences ()
	Stop all active command sequences. More...
int32_t	GetActiveCommandSequenceCount (uint32_t &command_sequence_count)
	Count the number of active command sequences. More...
int32_t	RegisterSequenceStartCallback (SequenceStartCallback function_ptr)
	Register a callback function to receive a command sequence status messages when the command sequence is started. More...
int32_t	RegisterSequenceWaitCallback (SequenceWaitCallback function_ptr)
	Register a callback function to receive a command sequence status messages when the the command sequence will be paused for a predetermined time before executing the next spacecraft command. More...
int32_t	RegisterSequenceCommandCallback (SequenceSpacecraftCommandCallback function_ptr)
	Register a callback function to receive a command sequence status messages after a spacecraft command is sent by the command sequence. More...
int32_t	RegisterSequenceStopCallback (SequenceStopCallback function_ptr)
	Register a callback function to receive a command sequence status messages when a command sequence is completed, cancelled by user, or cancelled due to an error. More...
int32_t	RegisterSequenceErrorCallback (SequenceErrorCallback function_ptr)
	Register a callback function to receive a command sequence status messages when a command sequence encounter an error. More...

Additional Inherited Members

Protected Member Functions inherited from trek::ApiClient

Detailed Description

Provides access to command features of TReK.

This class provides access to the command feature of TReK. Users of the class can uplink commands, update commands, receive command track information, and more.

Examples:
cmd_api_cpp/cmd_api_cpp_main.cpp - general example showing many API functions.

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

Constructor & Destructor Documentation

CommandApi()

trek::CommandApi::CommandApi

(

)

Default constructor.

There are no other constructors.

~CommandApi()

trek::CommandApi::~CommandApi ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

DestinationAllowsBlocking()

int32_t trek::CommandApi::DestinationAllowsBlocking

(

bool &

blocking_allowed

)

Determines if a destination allows blocking.

This will determine if the blocking flag is available for use.

Parameters

[out]

blocking_allowed

set to true if blocking is available, otherwise false.

Returns

SUCCESS if connected (value of input flag set)

TCA_API_NOT_CONNECTED if not connected (value of input flag is unchanged)

Example:

CommandApi api;
int32_t ret_value;
bool flag;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.DestinationAllowsBlocking( flag );
 
if( ret_value == SUCCESS )
    printf("The variable flag is set.\n");
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
None

FindActiveCommandSequence()

int32_t trek::CommandApi::FindActiveCommandSequence

(

uint32_t

token

)

Find an active command sequence associated with a specific token. I the command sequence is still active, this function returns SUCCESS. The function returns FAIL if the command sequence is not active.

Parameters

[in]

token

used to correlate specific instances of command sequence.

Returns

SUCCESS

FAIL

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

Example:

#include "command_api.h"
 
using namespace trek;
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value==FAIL)
    {
        printf("\nError %d:  failed to find the command sequence.\n", ret_value);
    }
 
    //wait until the command sequence starts
    Sleep(2000);
 
    //use this method to check if the command sequence associated with token_1 is active.
    // In this case, the command sequence associated with token_1 is active
    ret_value = api.FindActiveCommandSequence(token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nThe command sequence associated with token %u is active.\n", token_1);
    }
    else if (ret_value == FAIL)
    {
        printf("\nError %d:  failed to find the command sequence.\n", ret_value);
    }
    else
    {
        printf("\nerror %d: failed to check active command sequence.\n", ret_value);
    }
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    //wait until the command sequence stops
    Sleep(5000);
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

GetActiveCommandSequenceCount()

int32_t trek::CommandApi::GetActiveCommandSequenceCount

(

uint32_t &

command_sequence_count

)

Count the number of active command sequences.

Parameters

[out]

command_sequence_count

the number of active command sequences

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_NULL_POINTER

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

Example:

#include "command_api.h"
 
using namespace trek;
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    // Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //integer to store the number of active command sequence count
    uint32_t active_command_sequence_count;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence starts
    Sleep(2000);
    //wait until command sequence start.
    Sleep(1000);
 
    //Use this method to obtain the number of active command sequences.
    // We should now have 1 active command sequences.
    ret_value = api.GetActiveCommandSequenceCount(active_command_sequence_count);
    if (ret_value == SUCCESS)
    {
        printf("Active command sequence count: %d.\n", active_command_sequence_count);
    }
    else if (ret_value)
    {
        printf("Error %d:  GetActiveCommandSequenceCount error.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

GetBlockingFlag()

int32_t trek::CommandApi::GetBlockingFlag

(

bool &

flag

)

Gets the current value of the blocking flag for this instance of the API.

Parameters

[out]

flag

boolean indicating the current value of the blocking flag.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

Example:

CommandApi api;
int32_t ret_value;
bool flag;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetBlockingFlag( flag );
 
if( ret_value == SUCCESS )
    printf("The variable flag is set.\n");
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
None

GetBlockingTimeout()

int32_t trek::CommandApi::GetBlockingTimeout

(

uint32_t &

timeout

)

Gets the current value of the blocking timeout.

Return value is in milliseconds.

Parameters

[out]

timeout

timeout value in milliseconds

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
uint32_t timeout;
 
// assumes api is already connected (see longer example for details)
 
ret_value = api.GetBlockingTimeout( timeout );
 
if( ret_value == SUCCESS )
    printf("Timeout is %u.\n", timeout );
else
    printf("Error: %d.\n", ret_value );

Longer examples that include this method:
None

GetCommand()

int32_t trek::CommandApi::GetCommand	(	const char *	name,
		Packet &	pkt
	)

Gets the complete definition of the command from the command controller.

The returned data can be used for the SendThisCommand method.

Parameters

[in]	name	the name of the command to retrieve.
[out]	pkt	the definition of the returned command.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

Example:

CommandApi api;
int32_t ret_value;
Packet cmd_pkt;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetCommand( "MyCommandName", cmd_pkt );     // name should be a value returned from GetCommandList()
 
if( ret_value )
    printf( "Got it.  Variable cmd_pkt has all the details.\n" );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
None

GetCommandList()

int32_t trek::CommandApi::GetCommandList

(

StringArray &

cmd_list

)

Get a list of commands known by the command controller.

Details about each command can be obtained by calling the GetCommand method.

Parameters

[out]

cmd_list

list of commands known to the command controller.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_FILE_OPEN_ERR

Example:

CommandApi api;
int32_t ret_value;
StringArray cmd_list;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetCommandList( cmd_list );
 
if( ret_value == SUCCESS )
    printf("Available commands are:\n");        // could be an array of 0
    for( uint32_t ii = 0; ii < cmd_list.Size(); ii++ )
        printf("%s\n", cmd_list.GetAt(ii));
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
None

GetCommandResponse()

int32_t trek::CommandApi::GetCommandResponse	(	const char *	name,
		CommandResponse &	response
	)

Get the details for a command response.

The CommandResponse contains the details including the possible error codes and descriptions.

Parameters

[in]	name	the name of the command response. Usually returned from GetCommandResponseList.
[out]	response	the details about the command response.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

Example:

CommandApi api;
int32_t ret_value;
std::string name;
CommandResponse response;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetCommandResponse( "ERR", response );      // name should be a value returned from GetCommandResponseList()
 
if( ret_value )
    printf( "ERR description is %s (order is %u).\n", response.GetShortDescription(), response.GetOrder() );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

GetCommandResponseList()

int32_t trek::CommandApi::GetCommandResponseList

(

StringArray &

resp_list

)

Get a list of possible command responses for the command source.

The order of the list is set by the Command Controller and should be listed from first expected response to last expected response. An empty list indicates that no responses are expected from the destination. GetCommandResponse can be called to get details about each response in the list.

Parameters

[out]

resp_list

a vector of strings containing the name of each response.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_FILE_OPEN_ERR

Example:

CommandApi api;
int32_t ret_value;
StringArray resp_list;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetCommandResponseList( resp_list );
 
if( ret_value == SUCCESS )
    printf("Command responses are:\n");     // could be an array of 0
    for( uint32_t ii = 0; ii < resp_list.Size(); ii++ )
        printf("%s\n", resp_list.GetAt(ii));
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

GetConfigurationMessage()

int32_t trek::CommandApi::GetConfigurationMessage	(	const char *	name,
		ParameterCollection &	pc,
		char *	info,
		uint32_t *	space_available
	)

Get the details for a configuration message.

The returned ParameterCollection will contain one or more of parameters that may be configured for the destination.

Parameters

[in]	name	the name of the configuration message. Usually returned from GetConfigurationMessageList.
[out]	pc	the parameters contained in the configuration message
[out]	info	short description of the message
[in,out]	space_available	On input the amount of space available for info. If return code is CMD_API_NOT_ENOUGH_SPACE value is set to required space.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_NOT_ENOUGH_SPACE

Example:

CommandApi api;
int32_t ret_value;
char info[128];
uint32_t info_len = 128;
ParameterCollection pc;
bool available;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetConfigurationMessage( "ConfigMessageName", pc, info, &info_len );        // name should be a value returned from GetConfigurationMessageList()
 
if( ret_value == SUCCESS )
    printf( "ConfigMessageName description is %s.\n", info );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
None

GetConfigurationMessageList()

int32_t trek::CommandApi::GetConfigurationMessageList

(

StringArray &

config_list

)

Get a list of messages that a destination allows to be configured by a user.

The returned names can be used in calls to GetConfigurationMessage to get the details of what may be configured.

Parameters

[out]

config_list

a vector of strings containing the name of each status message.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_FILE_OPEN_ERR

Example:

CommandApi api;
int32_t ret_value;
StringArray rqst_list;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetConfigurationMessageList( rqst_list );
 
if( ret_value == SUCCESS )
    printf("Configuration messages are:\n");        // could be an array of 0
    for( uint32_t ii = 0; ii < rqst_list.Size(); ii++ )
        printf("%s\n", rqst_list.GetAt(ii));
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
None

GetDestinationType()

int32_t trek::CommandApi::GetDestinationType	(	char *	type,
		uint32_t *	space_available
	)

If successful, returns a string name for the destination suitable for displaying in a graphical user interface or framing above the fireplace.

The string value is set by the Command Controller.

Parameters

[out]	type	string representation of the destination type
[in,out]	space_available	On input the amount of space available for type. If return code is CMD_API_NOT_ENOUGH_SPACE value is set to required space.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_NOT_ENOUGH_SPACE

GetStatusItem()

int32_t trek::CommandApi::GetStatusItem	(	const char *	name,
		char *	value,
		uint32_t *	space_available
	)

Gets the value of a status item.

Parameters

[in]	name	The name of the status item.
[out]	value	The value of the status item.
[in,out]	space_available	On input the amount of space available for value. If return code is CMD_API_NOT_ENOUGH_SPACE value is set to required space.

Request String	Description
AosLos	Indicates if MCC-H currently AOS or LOS.
CarProcessingEnablement	Indicates if command action reponse processing is enabled or disabled.
CarTimeout	The amount of time in seconds that the POIC will wait for a CAR message before declaring failure.
ClearToSendMechanism	The current response required before another command can be uplinked. Valid values are ERR, CAR, and FSV.
CommandDatabaseVersion	The version of the command database used by the POIC.
ConnectionStatus	Describes if connection to POIC was successful and if not the reason for failure.
CrrProcessingEnablement	Indicates if command reaction reponse processing is enabled or disabled.
CurrentStationMode	Indicates the current ISS mode.
FsvProcessingEnablement	Indicates if flight system verifier processing is enabled or disabled.
FsvTimeout	The amount of time in seconds that the POIC will wait for a FSV message before declaring failure.
KuAosLos	Indicates whether the Ku-Band path is AOS or LOS. If LOS telemetry indicators for commanding may not be available.
MaximumRetries	The number of attempts the POIC will make to transmit a command. SetConfigurationItem can be used to control for individual sessions.
McchConnection	Indicates if the POIC system is connected to MCC-H.
McchEnablement	Indicates if the MCC-H is enabled or disabled for commanding.
MinimumTimeDelay	The time delay required between issuing commands. Value is milliseconds.
Mission	The mission from the MOP.
NonEhsCommandingEnablement	Indicates if remote users are enabled or disabled from commanding.
OperationalSupportMode	The operational support mode from the MOP.
PoicConnection	Indicates if a remote EHS command system is connected. Not applicable to TReK users.
PoicEnablement	Indicates if the POIC is enabled or disabled for commanding.
Project	The project from the MOP.
RemoteEhsEnablement	Indicates if a remote instance of the EHS system is enabled for commanding. Not applicable to TReK users.
SourceMessageKey	Internal value used only by the API.
UplinkPath	Identifiers the uplink path for real-time commands.
UserEnablement	Indicates if the user in enabled or disabled for S-band commanding.
UserInhibitStatus	Indicates if the user is inhibited from commanding due to LOS.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_NOT_ENOUGH_SPACE

Example:

CommandApi api;
int32_t ret_value;
char value[128];
uint32_t value_len = 128;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetStatusItem( "UserEnablement", value, &value_len );
 
if( ret_value == SUCCESS )
    printf( "Value is %s.\n", value );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
None

GetStatusMessage()

int32_t trek::CommandApi::GetStatusMessage	(	const char *	name,
		ParameterCollection &	pc,
		char *	info,
		uint32_t *	space_available
	)

Get the specified status message details.

The returned ParameterCollection will contain the list of parameters and their current values.

Parameters

[in]	name	the name of the status message. Usually returned from GetStatusMessageList.
[out]	pc	the parameters contained in the status message
[out]	info	short description of the message
[in,out]	space_available	On input the amount of space available for info. If return code is CMD_API_NOT_ENOUGH_SPACE value is set to required space.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_NOT_ENOUGH_SPACE

Example:

CommandApi api;
int32_t ret_value;
char info[128];
uint32_t info_len = 128;
ParameterCollection pc;
bool available;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetStatusMessage( "TheStatusMessageName", pc, info, &info_len );        // name should be a value returned from GetStatusMessageList()
 
if( ret_value )
    printf( "TheStatusMessageName description is %s.\n", info );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

GetStatusMessageList()

int32_t trek::CommandApi::GetStatusMessageList

(

StringArray &

rqst_list

)

Get a list of messages that the user can send.

• Get details about the specified user request message.

Get a list of messages that contain status from the command source.

The returned names can be used in calls to GetStatusMessage to get the contents of the status message.

Parameters

[out]

rqst_list

A vector of strings containing the name of each status message. The current contents of rqst_list is replaced.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_FILE_OPEN_ERR

CMD_API_NO_STATUS_MESSAGES

Example:

CommandApi api;
int32_t ret_value;
StringArray rqst_list;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.GetStatusMessageList( rqst_list );
 
if( ret_value == SUCCESS )
    printf("Status messages are:\n");       // could be an array of 0
    for( uint32_t ii = 0; ii < rqst_list.Size(); ii++ )
        printf("%s\n", rqst_list.GetAt(ii));
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

GetTrack()

int32_t trek::CommandApi::GetTrack	(	uint32_t	token,
		TrackItem &	track_item
	)

Find out any command track information for this 'token'.

The TrackItem contains the name of the command, the time the command was sent, and an ordered (by receipt time) list of all responses, if any. It is possible that the same response name is received multiple times for a command.

Parameters

[in]	token	used to correlate specific instances of command sends. This value is returned from a call to SendThisCommand or InitiateCommand.
[out]	track_item	class containing all of the details associated with the command track

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
std::string my_cmd;
uint32_t token;
TrackItem track_item;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
ret_value = api.InitiateCommand( my_cmd, token );
 
if( ret_value == SUCCESS )
{
    ret_value = api.GetTrack( token, track_item );
 
    // print the uplink time.
    TrekTime uplink_time;
    uplink_time = track_item.GetUplinkTime();
    std::string uplink_time_as_str;
    uplink_time.GetTime( uplink_time_as_str );
    printf( "Command %s was uplinked at %s\n", my_cmd.c_str(), uplink_time_as_str.c_str() );
}
else
    printf("Error %d returned when initiating command.\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

InitiateCommand()

int32_t trek::CommandApi::InitiateCommand	(	const char *	name,
		uint32_t &	token
	)

Sends a request to the final destination to uplink a command.

If the final destination does not support this means of sending a command, the method will return an error. The returned token can be used to obtain and/or correlate tracking information.

Parameters

[in]	name	The name of the command.
[out]	token	Value that uniquely identifies a command send instance.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

Example:

CommandApi api;
int32_t ret_value;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
ret_value = api.InitiateCommand( "MyCommandName", token );
 
if( ret_value == SUCCESS )
    printf("Command sent successfully\n");
else
    printf("Error %d returned when initiating command.\n", ret_value );

Longer examples that include this method:
cmd_api_cpp/cmd_api_cpp_main.cpp

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

InsertDataAndSendCommand()

int32_t trek::CommandApi::InsertDataAndSendCommand	(	const char *	name,
		const uint8_t *	buf_ptr,
		uint32_t	length,
		uint32_t &	token
	)

Inserts the specified data into a command's 'data zone'.

The data field in the command must contain a single parameter for the insertion of the data. The returned token can be used to obtain and/or correlate tracking information.

Note

The destination's Command Controller may manipulate the data sent here to meet interface requirements. See the documentation for a specific command controller for any details.

Parameters

[in]	name	The name of the command.
[in]	buf_ptr	Pointer to the first byte of command data.
[in]	length	The length of the command pointed to by buf_ptr
[out]	token	Value that uniquely identifies a command send instance

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_LEN_ERROR

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_DOES_NOT_EXIST

Example:

CommandApi api;
int32_t ret_value;
uint8_t buffer[80];
uint32_t length = 80;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
// set the contents of buffer prior to sending the command
buf[0] = 0x05;
buf[1] = 0xa3;
// etc.
 
ret_value = api.InsertDataAndSendCommand( "MyCommandName", buffer, length, token );
 
if( ret_value == SUCCESS )
    printf("Command sent successfully\n");
else
    printf("Error %d returned when sending command.\n", ret_value );

Longer examples that include this method:
None

ReadyForRequest()

int32_t trek::CommandApi::ReadyForRequest

(

bool &

result

)

Determine if it is ok to send a request on the command connection.

Parameters

[out]

result

true if ok for requests. otherwise false.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
bool result;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.ReadyForRequest(result);
 
if( ret_value == SUCCESS )
{
    if( result == true )
        printf("Safe to send commands.\n");
    else
        printf("If you send a command, it will be rejected.\n" );
else
    printf("Error %d.  Could not determine ready status.\n", ret_value );

Longer examples that include this method:
None

RegisterSequenceCommandCallback()

int32_t trek::CommandApi::RegisterSequenceCommandCallback

(

SequenceSpacecraftCommandCallback

function_ptr

)

Register a callback function to receive a command sequence status messages after a spacecraft command is sent by the command sequence.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

CMD_API_NOT_CLEAR_TO_SEND

Callback function:

Parameters

[out]	token	An integer that uniquely identifies the command sequence.
[out]	status_name	returns "command sent" or "error".
[out]	command_name	returns name of the command that was sent by the command sequence
[out]	command_count	An integer that counts how many spacecraft commands were sent out. The number is not incremented if command was not successfully sent.
[out]	return_code	An integer that returns 0 if command was successfully sent, or an error code otherwise.

Example:

#include "command_api.h"
 
 
using namespace trek;
 
//example callback function
void command_callback
(
    uint32_t token,
    char  status_name[64],
    char  command_name[64],
    uint32_t spacecraft_command_count,
    int32_t return_code,
    uint32_t cmd_token
)
{
    printf("\ncommand_callback token : %u\n", token);
    printf("command_callback status_name : %s\n", status_name);
    printf("command_callback command_name : %s\n", command_name);
    printf("command_callback spacecraft_command_count : %u\n", spacecraft_command_count);
    printf("command_callback return_code : %i\n", return_code);
    printf("command_callback cmd_token : %i\n", cmd_token);
}
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
 
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //call this method to register a callback function to the command API.
    // The callback will be called whenever there is an update.
 
    ret_value=api.RegisterSequenceCommandCallback(&command_callback);
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

RegisterSequenceErrorCallback()

int32_t trek::CommandApi::RegisterSequenceErrorCallback

(

SequenceErrorCallback

function_ptr

)

Register a callback function to receive a command sequence status messages when a command sequence encounter an error.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

CMD_API_NOT_CLEAR_TO_SEND

Callback function:

Parameters

[out]	token	An integer that uniquely identifies the command sequence.
[out]	status_name	returns "completed" or "cancelled" or "error".
[out]	command_count	An integer that counts how many spacecraft commands were sent out. The number is not incremented if command was not successfully sent.
[out]	return_code	An integer that returns 0 if command was completed or cancelled, or an error code otherwise.

Return Code

SUCCESS

CMD_API_NULL_POINTER

CMD_API_ZERO_LENGTH

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_LEN_ERROR

TCA_WORKER_WAIT_ERR

CMD_API_BAD_TIME_ERR

CMD_API_NO_CONTROLLER

Example:

#include "command_api.h"
 
using namespace trek;
 
//example callback function
 
void error_callback
(
    uint32_t token,
    uint32_t spacecraft_command_count,
    int32_t return_code
)
{
    printf("\nerror_callback token : %u\n", token);
    printf("error_callback spacecraft_command_count : %u\n", spacecraft_command_count);
    printf("error_callback return_code : %i\n", return_code);
}
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_error_example";
 
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
    //call this method to register a callback function to the command API.
    // The callback will be called whenever there is an update.
    ret_value=api.RegisterSequenceErrorCallback(&error_callback);
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(10000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

RegisterSequenceStartCallback()

int32_t trek::CommandApi::RegisterSequenceStartCallback

(

SequenceStartCallback

function_ptr

)

Register a callback function to receive a command sequence status messages when the command sequence is started.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

CMD_API_NOT_CLEAR_TO_SEND

Callback function:

Parameters

[out]	token	An integer that uniquely identifies the command sequence.
[out]	full_file_name	The folder path and file name of the comman sequence binary file.

Example:

#include "command_api.h"
 
using namespace trek;
 
//example callback function
 
void start_callback
(
    uint32_t token,
    char* full_file_name
)
{
    printf("\ntest_start_callback token : %u\n", token);
    printf("start_callback full_file_name : %s\n", full_file_name);
}
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
    //call this method to register a callback function to the command API.
    // The callback will be called whenever there is an update.
 
    ret_value= api.RegisterSequenceStartCallback(&start_callback);
    if (ret_value)
    {
        printf("Error %d:  could not register callback function.\n", ret_value);
        return 1;
    }
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

RegisterSequenceStopCallback()

int32_t trek::CommandApi::RegisterSequenceStopCallback

(

SequenceStopCallback

function_ptr

)

Register a callback function to receive a command sequence status messages when a command sequence is completed, cancelled by user, or cancelled due to an error.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

CMD_API_NOT_CLEAR_TO_SEND

Callback function:

Parameters

[out]	token	An integer that uniquely identifies the command sequence.
[out]	status_name	returns "completed" or "cancelled" or "error".
[out]	command_count	An integer that counts how many spacecraft commands were sent out. The number is not incremented if command was not successfully sent.
[out]	return_code	An integer that returns SUCCESS if command was completed or cancelled, or an error code otherwise.

Return Code

SUCCESS

CMD_API_NULL_POINTER

CMD_API_ZERO_LENGTH

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_LEN_ERROR

TCA_WORKER_WAIT_ERR

CMD_API_FILE_OPEN_ERR

CMD_API_BAD_TIME_ERR

CMD_API_NO_CONTROLLER

Example:

#include "command_api.h"
 
using namespace trek;
 
//example callback function
void stop_callback
(
    uint32_t token,
    char  status_name[64],
    uint32_t spacecraft_command_count,
    int32_t return_code
)
{
    printf("\nstop_callback token : %u\n", token);
    printf("stop_callback status_name : %s\n", status_name);
    printf("stop_callback spacecraft_command_count : %u\n", spacecraft_command_count);
    printf("stop_callback return_code : %i\n", return_code);
}
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
 
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //call this method to register a callback function to the command API.
    // The callback will be called whenever there is an update.
 
    ret_value=api.RegisterSequenceStopCallback(&stop_callback);
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

RegisterSequenceWaitCallback()

int32_t trek::CommandApi::RegisterSequenceWaitCallback

(

SequenceWaitCallback

function_ptr

)

Register a callback function to receive a command sequence status messages when the the command sequence will be paused for a predetermined time before executing the next spacecraft command.

Parameters

[in]

function_ptr

A pointer to the callback function.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_SEM_OPEN_ERROR

CMD_API_NOT_CLEAR_TO_SEND

Callback function:

Parameters

[out]	token	An integer that uniquely identifies the command sequence.
[out]	status_name	returns "wait" or "error". Use RegisterSequenceErrorCallback to obtain the error code.
[out]	wait_millisecond	An integer that inform the wait time before the next spacecraft command will be sent out.

Example:

#include "command_api.h"
 
 
using namespace trek;
 
//example callback function
void wait_callback
(
    uint32_t token,
    char  status_name[64],
    int64_t wait_millisecond
)
{
    printf("\nwait_callback token : %u\n", token);
    printf("wait_callback status_name : %s\n", status_name);
    printf("wait_callback wait_ms : %u\n", wait_millisecond);
}
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace [your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
 
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
    //call this method to register a callback function to the command API.
    // The callback will be called whenever there is an update.
 
    ret_value=api.RegisterSequenceWaitCallback(&wait_callback);
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

SendBinaryCommand()

int32_t trek::CommandApi::SendBinaryCommand	(	const char *	name,
		const uint8_t *	buf_ptr,
		uint32_t	length,
		uint32_t &	token
	)

Sends the command identified by buf_ptr to the destination using the given name.

The returned token can be used to obtain and/or correlate tracking information.

Note

The destination's Command Controller may manipulate the data sent here to meet interface requirements. See the documentation for a specific command controller for any details.

Parameters

[in]	name	the name of the command. Some destinations may not require the name, but it is advisable to set it for tracking purposes
[in]	buf_ptr	pointer to the first byte of command data.
[in]	length	the length of the command pointed to by buf_ptr
[out]	token	value that uniquely identifies a command send instance

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_LEN_ERROR

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_ZERO_LENGTH

Example:

CommandApi api;
int32_t ret_value;
uint8_t buffer[100];
uint32_t length = 100;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
// set the contents of buffer prior to sending the command
buf[0] = 0x05;
buf[1] = 0xa3;
// etc.
 
ret_value = api.SendBinaryCommand( "MyCommandName", buffer, length, token );
 
if( ret_value == SUCCESS )
    printf("Command sent successfully\n");
else
    printf("Error %d returned when sending command.\n", ret_value );

Longer examples that include this method:
None

SendThisCommand()

int32_t trek::CommandApi::SendThisCommand	(	Packet &	pkt,
		uint32_t &	token
	)

Builds the command defined by Packet and sends it to the destination.

The returned token can be used to obtain and/or correlate tracking information.

Note

The destination's command controller may manipulate the data sent here to meet interface requirements. See the documentation for a specific command controller for any details.

Parameters

[in]	pkt	a complete definition of the packet to send. All parameter values must have a value.
[out]	token	value that uniquely identifies a command send instance

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
Packet my_cmd;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
// use the methods of Packet to populate each parameter.
ret_value = api.SendThisCommand( my_cmd, token );
 
if( ret_value == SUCCESS )
    printf("Command sent successfully\n");
else
    printf("Error %d returned when sending command.\n", ret_value );

Longer examples that include this method:
None

SendTrekCommand()

int32_t trek::CommandApi::SendTrekCommand	(	const char *	name,
		uint32_t &	token
	)

Sends the specified command based on the current definition of the command within the command controller.

The returned token can be used to obtain and/or correlate tracking information.

Parameters

[in]	name	the name of the command. Some destinations may not require the name, but it is advisable to set it for tracking purposes
[out]	token	value that uniquely identifies a command send instance

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

CMD_API_DOES_NOT_EXIST

Example:

CommandApi api;
int32_t ret_value;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
ret_value = api.SendTrekCommand( "MyCommandName", token );
 
if( ret_value == SUCCESS )
    printf("Command sent successfully\n");
else
    printf("Error %d returned when sending command.\n", ret_value );

Longer examples that include this method:
None

SetBlockingFlag()

int32_t trek::CommandApi::SetBlockingFlag

(

bool

input

)

Sets the blocking flag for this instance of the API.

Upon initialization the blocking flag is set to true. For command controllers that have optional blocking, this flag indicates whether or not the API method will block until the 'clear to send' mechanism is released. The API methods that use this flag are: SendBinaryCommand, InsertDataAndSendCommand, InitiateCommand, SendThisCommand, and SendTrekCommand.

Note

It is not recommended that you change this behavior of the API unless you have exhausted all other options. Changing a destination that allows blocking to one that does not enforce it can cause commands to be rejected because the destination is not ready. If the destination is broken (i.e., has a bug that needs to be fixed), this method may provide a temporary workaround until the problem is resolved.

Parameters

[in]

input

set to true if blocking is desired.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
std::string cmd_name = "MyCommand";
uint32_t token;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.SetBlockingFlag( false );
 
if( ret_value == SUCCESS )
    printf("Will not block\n");
else
    printf("Could not change blocking flag (%d).\n", ret_value );

Longer examples that include this method:
None

SetBlockingTimeout()

int32_t trek::CommandApi::SetBlockingTimeout

(

uint32_t

timeout

)

Sets the amount of time a method that supports blocking will wait to unblock.

Value is ignored for destinations that do not support blocking or when user has turned off blocking with SetBlockingFlag. This timeout value should be less than the value set by ApiClient::SetWaitTimeout.

The default value for the blocking timeout is 20,000 milliseconds.

Parameters

[in]

timeout

timeout value in milliseconds

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.SetBlockingTimeout( 15000 );        // reset to 15 seconds
 
if( ret_value == SUCCESS )
    printf( "Blocking timeout reset.\n" );
else
    printf( "Failed because of %d\n", ret_value );

Longer examples that include this method:
None

SetConfigurationItem()

int32_t trek::CommandApi::SetConfigurationItem	(	const char *	name,
		const char *	value
	)

Sets the value of a configuration item.

Parameters

[in]	name	The name of the configuration item.
[in]	value	The value of the configuration item.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

Request String	Description
NumberOfRetries	Sets the number of times a command will be retried if it does not succeed. Cannot exceed the MaximumRetries status value (GetStatusItem).

Example:

CommandApi api;
int32_t ret_value;
char value[128];
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.SetConfigurationItem( "NumberOfRetries", "2" );
 
if( ret_value == SUCCESS )
    printf( "Value set\n" );
else
    printf( "Error %d\n", ret_value );

Longer examples that include this method:
None

StartCommandSequence()

int32_t trek::CommandApi::StartCommandSequence	(	char *	full_file_name,
		uint32_t &	token
	)

Start a command sequence specified in a command sequence binary file, and get a 'token' to track the command sequence. The token can be used to stop the command sequence.

Parameters

[in]	full_file_name	the command sequence binary full file path and name that will be started.
[out]	token	used to correlate specific instances of command sequence.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_NULL_POINTER

TCA_WORKER_WAIT_ERR

CMD_API_MAX_LEN_ERROR

CMD_API_BAD_INDEX

CMD_API_SEM_OPEN_ERROR

CMD_API_FILE_OPEN_ERR

CMD_API_THREAD_START_FAILED

Example:

#include "command_api.h"
 
using namespace trek;
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
    //wait until the command sequence is finsihed
    Sleep(60000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

StopAllCommandSequences()

int32_t trek::CommandApi::StopAllCommandSequences

(

)

Stop all active command sequences.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

Example:

#include "command_api.h"
 
using namespace trek;
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1, token_2;
 
    //use this method to start 2 command sequences
    ret_value=ret_value=api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
 
    ret_value=ret_value=api.StartCommandSequence(binary_sequence_path, token_2);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_2);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence starts
    Sleep(2000);
 
    //use this method to cancel all active command sequences
    api.StopAllCommandSequences();
 
    //check if command sequence successfully send the stop all signal
    if (ret_value == SUCCESS)
    {
        printf("\nstop signal was sent to all command sequences.\n");
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to stop all command sequences.\n", ret_value);
    }
 
    //wait until the command sequence finished stopping
    Sleep(5000);
 
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

StopCommandSequence()

int32_t trek::CommandApi::StopCommandSequence

(

uint32_t

token

)

Stop an active command sequence which correlated to a specific token.

Parameters

[in]

token

used to correlate specific instances of command sequence.

Returns

SUCCESS

FAIL

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

TCA_WORKER_WAIT_ERR

CMD_API_BAD_INDEX

CMD_API_SEM_OPEN_ERROR

Example:

#include "command_api.h"
 
using namespace trek;
 
int main(void)
{
    CommandApi api;
    int32_t ret_value;
 
    //Replace[your folder path] with the path to the command_sequence_example file.If the file does not exist in the folder, it must be moved manually.
    char binary_sequence_path[256] = "[your folder path]/command_sequence_example";
    //
    //  Connect to a destination.  The name passed into the Connect() call is
    //  the name used when configuring the destination in the TReK Command
    //  application.
    //
 
    ret_value = api.Connect("ufo");
 
    if (ret_value)
    {
        printf("Error %d:  Could not connect to destination.\n", ret_value);
        return 1;
    }
 
    //  Calling this method allows the API to clean up resources that may be
    //  left over from a user program that crashed.  Not checking the return
    //  value as it is safe to continue if this method fails.
    api.Cleanse();
 
 
    //Declare integer tokens to keep track command sequnces. Each command sequence willbe assigned a unique token.
    uint32_t token_1;
 
    //use this method to start a command sequence
    ret_value = ret_value = api.StartCommandSequence(binary_sequence_path, token_1);
    if (ret_value == SUCCESS)
    {
        printf("\nCommand sequence associated with token %u was started.\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to start command sequence.\n", ret_value);
    }
 
    //wait until the command sequence starts
    Sleep(2000);
 
    //use this method to cancel a single active command sequence associated with a token. 
    // In this case, the command sequence associated with token_1 is canceled
    ret_value = api.StopCommandSequence(token_1);
 
    //check if command sequence successfully send the stop signal 
    if (ret_value == SUCCESS)
    {
        printf("\nstop signal was sent to the command sequence associated with token %u .\n", token_1);
    }
    else if (ret_value)
    {
        printf("\nError %d:  failed to stop command sequence.\n", ret_value);
    }
    //
    //  It is always best to call Disconnect when you are finished with the
    //  API.  There are system resources that can be freed when you no
    //  longer need the API.
    //
 
    //wait until the command sequence stops
    Sleep(5000);
 
    ret_value = api.Disconnect();
 
    if (ret_value)
    {
        printf("Error %d:  API did not disconnect properly.\n", ret_value);
        return 1;
    }
 
    return 0;
}

UnblockDestination()

int32_t trek::CommandApi::UnblockDestination

(

)

Unblocks a destination. If the destination doesn't allow blocking, the function will still return SUCCESS.

This function is provided in case a logic error in the delivered software prevents a command connection from being used. You should not call this method unless it is determined that the delivered software has an error. Please contact the TReK Help Desk if the destination is remaining blocked unexpectedly for help.

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

Example:

CommandApi api;
int32_t ret_value;
 
ret_value = api.Connect( "DestName" );      // assume success
 
ret_value = api.UnblockDestination();
 
if( ret_value == SUCCESS )
    printf("The destination unblocked.\n");
else
    printf("Failed because of %d\n", ret_value );

Longer examples that include this method:
None

UpdateCommand()

int32_t trek::CommandApi::UpdateCommand

(

Packet &

pkt

)

Adds the specified command to the destination.

Updates the specified command in the destination.

The name of the command is retrieved from the Packet class. The current definition is removed from the command store and replaced with the new definition supplied. No checks are performed to see if the command definitions match in any way.

Note

The TReK Wizard provides a means of updating commands to a destination.

Parameters

[in]

pkt

the new definition of the command

Returns

SUCCESS

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_DOES_NOT_EXIST

CMD_API_MAX_NAME_LEN_ERROR

Example:

CommandApi api;
int32_t ret_value;
Packet my_cmd;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
// use the methods of Packet to update each field (also could just use the TReK Wizard)
ret_value = api.UpdateCommand( my_cmd );
 
if( ret_value == SUCCESS )
    printf("Command updated\n");
else
    printf("Error %d returned when updating command.\n", ret_value );

Longer examples that include this method:
None

UpdateDestinationCommand()

int32_t trek::CommandApi::UpdateDestinationCommand

(

const char *

name

)

Sends a request to the final destination to update a command.

If the final destination does not support this means of sending a command, the method will return an error. The actual data sent to the destination will vary based on the defined interface.

Parameters

[in]

name

The name of the command.

Returns

SUCCESS

CMD_API_NULL_POINTER

TCA_API_NOT_CONNECTED

TCA_WAIT_TIMEOUT

CMD_API_MAX_NAME_LEN_ERROR

Example:

CommandApi api;
int32_t ret_value;
uint32_t token;
 
ret_value = api.Connect( "DestName" );  // check return code...assuming success for example
 
ret_value = api.UpdateDestinationCommand( "MyCommandName", token );
 
if( ret_value )
    printf("Error %d returned when updating destination command.\n", ret_value );

Longer examples that include this method:
None