trek::SwitchSet Class Reference

This class is the abstraction for sets of information that can be switch by the value of a parameter. More...

#include <switch_set.h>

Inherits trek::NamedItem.

Inherited by trek::CalibratorSwitchSet, trek::EnumeratorSwitchSet, trek::ExpectedStateAlarmSwitchSet, and trek::LimitAlarmSwitchSet.

Public Member Functions
int32_t	SetDefaultSetName (const char *name)
	Sets the default set name. More...
const char *	GetDefaultSetName ()
	Gets the default set name. More...
int32_t	SetSwitchParameterName (const char *name)
	Sets the name of the parameter to use as a switch. More...
const char *	GetSwitchParameterName ()
	Gets the parameter name for the switch. More...
void	SetSwitchType (switch_type input)
	Sets the type of switch to use. More...
switch_type	GetSwitchType ()
	Returns the current switch type. More...
int32_t	SetSwitchParameter (Parameter *input_ptr)
	Sets the parameter to use for switching. More...
int32_t	AddRangeSwitch (double low, double high, const char *name)
	Adds a range switch. More...
int32_t	AddEnumerationSwitch (const char *enum_name, const char *name)
	Adds an enumeration switch. More...
int32_t	DeleteRangeSwitch (double low)
	Deletes the specified range switch. More...
int32_t	DeleteEnumerationSwitch (const char *enum_name)
	Deletes the specified enumeration switch. More...
int32_t	GetRangeSwitches (double **input, uint32_t &array_size)
	Gets the low value for each range switch. More...
void	GetEnumerationSwitches (StringArray &input)
	Gets the enumeration values for the switch. More...
int32_t	GetRangeSwitchInfo (double low, double &high, char **name)
	Gets the high value and name for a range switch based on its low value. More...
int32_t	GetEnumerationInfo (const char *enum_name, char **name)
	Gets the name for a switch based on its enumerated value. More...
int32_t	Validate ()
	Determines if it is safe to use the switch set. More...
const char *	GetValidationErrors ()
	Gets a string of the last validation errors. More...
uint32_t	GetEnumerationInfoLength (const char *enum_name)
	Gets the length for returned info of input parameter. Does not include space for the NULL termination character. More...
int32_t	GetEnumerationInfo (const char *enum_name, char *name, uint16_t &name_size)
	Gets the name for a switch based on its enumerated value. More...
uint32_t	GetRangeSwitchInfoLength (double low)
	Gets the length for returned info of input parameter. Does not include space for the NULL termination character. More...
int32_t	GetRangeSwitchInfo (double low, double &high, char *name, uint16_t &name_size)
	Gets the high value and name for a range switch based on its low value. More...
uint32_t	GetNumberOfRangeSwitches ()
	Returns the number of range switches available. More...
int32_t	GetRangeSwitches (double *low_values, uint32_t low_value_size)
	Gets the low value for each range switch. More...
void	GetItemNames (StringArray &input)
	Retrieves an array of the (e.g., calibrator) names from the set. More...
Constructors, Destructor, and Other Basic Methods
	SwitchSet ()
	Default constructor of the class.
	SwitchSet (SwitchSet &input)
	Copy constructor of the class.
virtual	~SwitchSet ()
	Class destructor. More...
void	operator= (SwitchSet &right_side)
	Provides the equal operator.
virtual void	Init ()
	Initializes the object.
Public Member Functions inherited from trek::NamedItem
void	SetName (const char *input_ptr)
	Sets the name of the item. More...
void	SetAlias (const char *input)
	Sets the alias of the item. More...
void	SetShortDescription (const char *input_ptr)
	Sets the short description of the item. More...
void	SetLongDescription (const char *input_ptr)
	Sets the long description of the item. More...
void	SetUserDescription (const char *input_ptr)
	Sets the user description of the item. More...
void	SetOwner (const char *input_ptr)
	Sets the owner of the item. More...
const char *	GetName ()
	Returns the name of the item.
const char *	GetAlias ()
	Returns the alias of the item.
const char *	GetShortDescription ()
	Returns the short description of the item.
const char *	GetLongDescription ()
	Returns the long description of the item.
const char *	GetUserDescription ()
	Returns the user description of the item.
const char *	GetOwner ()
	Returns the owner of the item.
	NamedItem ()
	Default constructor of the class.
	NamedItem (NamedItem &input)
	Copy constructor of the class.
virtual	~NamedItem ()
	Class destructor. More...
void	operator= (NamedItem &right_side)
	Provides the equal operator.
bool	operator== (NamedItem &right_side)
	Provides the == operator.

Detailed Description

This class is the abstraction for sets of information that can be switch by the value of a parameter.

The switch parameter can be used to determine which set of information to use. Used for enumeration, calbiration, limits, and expected states. Two types of switching are supported: range switching and enumeration switching.

Constructor & Destructor Documentation

~SwitchSet()

trek::SwitchSet::~SwitchSet ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

AddEnumerationSwitch()

int32_t trek::SwitchSet::AddEnumerationSwitch	(	const char *	enum_name,
		const char *	name
	)

Adds an enumeration switch.

Adds the specified enumeration switch. Checks are performed to make sure the specified enumeration does not already exist.

Parameters

[in]	enum_name	The enumerated value to use for switching.
[in]	name	The name of the item to switch to when the switch parameter has the specified enumeration.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_INCORRECT_SWITCH_TYPE

TREK_DATA_ALREADY_EXISTS

Example:

CalibratorSwitchSet css;
int32_t ret_value;
ret_value = css.AddEnumerationSwitch( "On", "one" );
ret_value = css.AddEnumerationSwitch( "OFF", "two" );

AddRangeSwitch()

int32_t trek::SwitchSet::AddRangeSwitch	(	double	low,
		double	high,
		const char *	name
	)

Adds a range switch.

Adds the specified range switch. Checks are performed to make sure the specified range does not overlap with a current range. Ranges are evaluated by low < value <= high.

Parameters

[in]	low	The low value for the range.
[in]	high	The high value for the range.
[in]	name	The name of the item to switch to when the switch parameter falls within the range.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_INCORRECT_SWITCH_TYPE

TREK_DATA_LOW_TO_HIGH

TREK_DATA_NEED_UNIQUE_RANGE

Example:

CalibratorSwitchSet css;
int32_t ret_value;
ret_value = css.AddRangeSwitch( 0, 10, "one" );
ret_value = css.AddRangeSwitch( 10, 100, "two" );

DeleteEnumerationSwitch()

int32_t trek::SwitchSet::DeleteEnumerationSwitch

(

const char *

enum_name

)

Deletes the specified enumeration switch.

Parameters

[in]

enum_name

The enumerated value to delete.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

Example:

CalibratorSwitchSet css;
int32_t ret_value;
ret_value = css.AddRangeSwitch( "first", "one" );
ret_value = css.DeleteEnumerationSwitch( "first" );

DeleteRangeSwitch()

int32_t trek::SwitchSet::DeleteRangeSwitch

(

double

low

)

Deletes the specified range switch.

Only need to specify the low range as ranges are not allowed to overlap.

Parameters

[in]

low

The low range of the switch to delete.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

Example:

CalibratorSwitchSet css;
int32_t ret_value;
ret_value = css.AddRangeSwitch( 0, 10, "one" );
ret_value = css.DeleteRangeSwitch( 0 );

GetDefaultSetName()

const char * trek::SwitchSet::GetDefaultSetName

(

)

Gets the default set name.

Returns

The default set name (returns empty string if not set)

Example:

CalibratorSwitchSet css;
printf( "Default set name is '%s'\n", css.GetDefaultSetName();

GetEnumerationInfo() [1/2]

int32_t trek::SwitchSet::GetEnumerationInfo	(	const char *	enum_name,
		char **	name
	)

Gets the name for a switch based on its enumerated value.

All of the enumerations can be found by calling GetEnumerationSwitches. The caller of the function is responsible for deleting the memory that is created.

Parameters

[in]	enum_name	The enumerated value to search for
[out]	name	The name of the item when switch is valid.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

Example:

CalibratorSwitchSet css;
int32_t ret_value;
char *name;
 
ret_value = css.GetEnumerationInfo( "ON", &name );
 
if( ret_value == SUCCESS )
{
    printf( "When ON use %s\n", name );
    delete name;
}

GetEnumerationInfo() [2/2]

int32_t trek::SwitchSet::GetEnumerationInfo	(	const char *	enum_name,
		char *	name,
		uint16_t &	name_size
	)

Gets the name for a switch based on its enumerated value.

All of the enumerations can be found by calling GetEnumerationSwitches. The caller of the function is responsible for allocating the memory needed for the returned data by calling GetEnumerationInfoLength.

Parameters

[in]	enum_name	The enumerated value to search for
[out]	name	The name of the item when switch is valid.
[in]	name_size	The size of the data allocated for name.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NOT_ENOUGH_SPACE

Example:

CalibratorSwitchSet css;
int32_t ret_value;
char *name;
 
name = new char[css.GetEnumerationInfoLength("ON")];
 
ret_value = css.GetEnumerationInfo( "ON", name, name_size );
 
if( ret_value == SUCCESS )
{
    printf( "When ON use %s\n", name );
    delete name;
}

GetEnumerationInfoLength()

uint32_t trek::SwitchSet::GetEnumerationInfoLength

(

const char *

enum_name

)

Gets the length for returned info of input parameter. Does not include space for the NULL termination character.

If the input does not exist, zero is returned.

Parameters

[in]

enum_name

The enumerated value to search for

Returns

Number of bytes needed for info string

Example:

CalibratorSwitchSet css;
 
uint32_t info_size = css.GetEnumerationInfoLength("ON");
 
printf( "The info returned for 'ON' will be %u bytes in length.\n", info_size );

GetEnumerationSwitches()

void trek::SwitchSet::GetEnumerationSwitches

(

StringArray &

input

)

Gets the enumeration values for the switch.

The input array will be cleared prior to values being added.

Parameters

[out]

input

Will contain all of the enumerated values for the switch.

Example:

CalibratorSwitchSet css;
StringArray enum_array;
 
css.GetEnumerationSwitches( enum_array );
 
for( uint32_t ii = 0; ii < enum_array.Size(); ii++ )
    printf( "Enum value is %s\n", enum_array.GetAt(ii) );

GetItemNames()

void trek::SwitchSet::GetItemNames

(

StringArray &

input

)

Retrieves an array of the (e.g., calibrator) names from the set.

Parameters

[in]

input

The array to set. Previous items will be cleared.

Example:

CalibratorSwitchSet css;
StringArray my_array;
//...
css.GetItemNames( my_array );

GetNumberOfRangeSwitches()

uint32_t trek::SwitchSet::GetNumberOfRangeSwitches

(

)

Returns the number of range switches available.

Returns

The number of range switches.

GetRangeSwitches() [1/2]

int32_t trek::SwitchSet::GetRangeSwitches	(	double **	input,
		uint32_t &	array_size
	)

Gets the low value for each range switch.

The low range returned can be used to access details about each range by calling GetRangeSwitchInfo. The caller of the function is responsible for deleting the memory that is created.

Parameters

[out]	input	This value will contain an array of doubles that are the low value.
[out]	array_size	The number of values returned.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Example:

CalibratorSwitchSet css;
int32_t ret_value;
double *low_values;
uint32_t array_size;
 
ret_value = css.GetRangeSwitches( &low_values, array_size );
 
if( ret_value == SUCCESS )
{
    for( uint32_t ii = 0; ii < array_size; ii++ )
        printf( "Low value was %lf\n", low_values[ii] );
    delete low_values;
}

GetRangeSwitches() [2/2]

int32_t trek::SwitchSet::GetRangeSwitches	(	double *	low_values,
		uint32_t	low_value_size
	)

Gets the low value for each range switch.

The low range returned can be used to access details about each range by calling GetRangeSwitchInfo. The caller of the function is responsible for allocating the memory that is needed. The size of memory needed can be found by calling GetNumberOfRangeSwitches.

Parameters

[out]	input	This value will contain an array of doubles that are the low value.
[in]	array_size	The size of the array.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_NOT_ENOUGH_SPACE

Example:

CalibratorSwitchSet css;
int32_t ret_value;
double *low_values;
uint32_t array_size;
 
array_size = GetNumberOfRangeSwitches();
low_values = new double[array_size];
 
ret_value = css.GetRangeSwitches( low_values, array_size );
 
if( ret_value == SUCCESS )
{
    for( uint32_t ii = 0; ii < array_size; ii++ )
        printf( "Low value was %lf\n", low_values[ii] );
}
 
delete low_values;

GetRangeSwitchInfo() [1/2]

int32_t trek::SwitchSet::GetRangeSwitchInfo	(	double	low,
		double &	high,
		char **	name
	)

Gets the high value and name for a range switch based on its low value.

All of the low ranges can be found by calling GetRangeSwitches. The caller of the function is responsible for deleting the memory that is created.

Parameters

[in]	low	The low value to search for
[out]	high	The corresponding low value.
[out]	name	The name of the item when switch is valid.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

Example:

CalibratorSwitchSet css;
int32_t ret_value;
double high_value;
char *name;
 
ret_value = css.GetRangeSwitchInfo( 5, high_value, &name );
 
if( ret_value == SUCCESS )
{
    printf( "5 < value <= %lf will use %s\n", high_value, name );
    delete name;
}

GetRangeSwitchInfo() [2/2]

int32_t trek::SwitchSet::GetRangeSwitchInfo	(	double	low,
		double &	high,
		char *	name,
		uint16_t &	name_size
	)

Gets the high value and name for a range switch based on its low value.

All of the low ranges can be found by calling GetRangeSwitches. The caller of the function is responsible for allocating the memory that is needed. The size of data that will be returned can be found by calling GetRangeSwitchInfoLength.

Parameters

[in]	low	The low value to search for
[out]	high	The corresponding low value.
[out]	name	The name of the item when switch is valid.
[in]	name_size	The size of data allocated for name.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_DATA_DOES_NOT_EXIST

Example:

CalibratorSwitchSet css;
int32_t ret_value;
double high_value;
char *name;
 
ret_value = css.GetRangeSwitchInfo( 5, high_value, &name );
 
if( ret_value == SUCCESS )
{
    printf( "5 < value <= %lf will use %s\n", high_value, name );
    delete name;
}

GetRangeSwitchInfoLength()

uint32_t trek::SwitchSet::GetRangeSwitchInfoLength

(

double

low

)

Gets the length for returned info of input parameter. Does not include space for the NULL termination character.

If the input does not exist, zero is returned.

Parameters

[in]

low

The value to search for

Returns

Number of bytes needed for info string

Example:

CalibratorSwitchSet css;
 
uint32_t info_size = css.GetRangeSwitchInfoLength(15);
 
printf( "The info returned for value 15 will be %u bytes in length.\n", info_size );

GetSwitchParameterName()

const char * trek::SwitchSet::GetSwitchParameterName

(

)

Gets the parameter name for the switch.

Returns

The switch parameter name (returns empty string if not set)

Example:

CalibratorSwitchSet css;
printf( "Switch parameter name is '%s'\n", css.GetSwitchParameterName();

GetSwitchType()

switch_type trek::SwitchSet::GetSwitchType

(

)

Returns the current switch type.

Returns

RANGE_SWITCH or ENUMERATION_SWITCH

Example:

CalibratorSwitchSet css;
if( css.GetSwitchType() == RANGE_SWITCH )
    printf( "It's a range switch.\n" );
else
    printf( "It's an enumeration switch.\n" );

GetValidationErrors()

const char * trek::SwitchSet::GetValidationErrors

(

)

Gets a string of the last validation errors.

Returns

A constant string of validation errors. Example:

LimitAlarmSwitchSet limit_set;
int32_t num_err;
 
// assuming that set has some data added already.
num_err = limit_set.Validate();
 
if( num_err )
{
    printf( "%d validation errors found.\n", num_err );
    printf( "%s\n", limit_set.GetValidationErrors() );
}
else
    printf( "ok to use\n" );

SetDefaultSetName()

int32_t trek::SwitchSet::SetDefaultSetName

(

const char *

name

)

Sets the default set name.

The name of the item (e.g., calibrator) to use if no other set can be identified by switching.

Parameters

[in]

name

The name of the set.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Example:

CalibratorSwitchSet css;
 
ret_value = css.SetDefaultSetName( "CalSet1" );

SetSwitchParameter()

int32_t trek::SwitchSet::SetSwitchParameter

(

Parameter *

input_ptr

)

Sets the parameter to use for switching.

Parameters

[in]

input_ptr

A valid reference to a parameter in a packet.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Note

This function is only intended for use by internal TReK code.

SetSwitchParameterName()

int32_t trek::SwitchSet::SetSwitchParameterName

(

const char *

name

)

Sets the name of the parameter to use as a switch.

Parameters

[in]

name

The name of the switch parameter.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Example:

CalibratorSwitchSet css;
 
ret_value = css.SetSwitchParameterName( "SwitchParameter" );

SetSwitchType()

void trek::SwitchSet::SetSwitchType

(

switch_type

input

)

Sets the type of switch to use.

Parameters

input

The new switch type

Example:

CalibratorSwitchSet css;
css.SetSwitchType( ENUMERATION_SWITCH );

Validate()

int32_t trek::SwitchSet::Validate

(

)

Determines if it is safe to use the switch set.

Insures that class is properly configured. Safe to use if 0 is returned.

Returns

The number of errors found.

Example:

LimitAlarmSwitchSet limit_set;
int32_t num_err;
 
// assuming that set has some data added already.
num_err = limit_set.Validate();
 
if( num_err )
{
    printf( "%d validation errors found.\n", num_err );
    printf( "%s\n", limit_set.GetValidationErrors() );
}
else
    printf( "ok to use\n" );