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...
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...
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...

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

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 uniqiuely 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 uniqiuely 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

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 uniqiuely 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 uniqiuely 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 uniqiuely 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.
[out]	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

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 defintions 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_API_NOT_CONNECTED

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

TCA_API_NOT_CONNECTED

TCA_API_NOT_CONNECTED

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