trek::OrderedParameterCollection Class Reference

This class describes a parameter collection composed of one or more parameters. More...

#include <ordered_parameter_collection.h>

Inherits trek::PacketItem.

Public Member Functions
virtual int32_t	GetLengthInBits (uint32_t &bit_length)
	Gets the length of the ordered parameter collection in bits. More...
virtual int32_t	GetLengthInBytes (uint32_t &byte_length)
	Gets the length of the ordered parameter collection in bytes. More...
int32_t	InsertParameter (Parameter *input_ptr, uint32_t location)
	Adds the parameter to the collection. More...
int32_t	RemoveParameter (const char *input)
	Removes the specified parameter from the collection. More...
void	RemoveAllParameters ()
	Removes all parameters and associated memory from the collection. More...
virtual int32_t	FindParameter (const char *name, Parameter **param_ptr)
	Finds the specified parameter in the collection. More...
uint32_t	GetNumberOfParameters ()
	Returns the number of parameters currently in the collection. More...
int32_t	Build (uint8_t *input_ptr, uint32_t *input_length_ptr)
	Builds the parameters in the collection and places it in the specified buffer. More...
int32_t	Extract (uint8_t *input_ptr, uint32_t input_length, uint32_t &last_bit_used)
	Extracts all of the parameters in the collection from the specified buffer. More...
uint32_t	GetMaximumLengthInBits ()
	Returns the maximum length of the OrderedParameterCollection in bits. More...
bool	HasVariableLengthData ()
	Determines if the parameter collection has any variable length data. More...
virtual void	GetParameterList (StringArray &param_list, bool full_name=true, bool mod_only=false)
	Returns a list of all parameters within a collection. More...
virtual void	GetSortedParameterList (StringArray &param_list, bool full_name=true, bool mod_only=false)
	Returns a list of all parameters within a collection sorted by their start location. More...
virtual bool	IsComplete ()
	Determines if all parameters have a value. More...
virtual bool	IsModifiable (bool top_level=true)
	Determines if any of the data is modifiable. More...
virtual bool	HasModifiableData (bool data_zone_only=true)
	Determines if any of the parameters are modifiable. More...
Constructors, Destructor, and Other Basic Methods
	OrderedParameterCollection ()
	Class constructor. More...
	OrderedParameterCollection (OrderedParameterCollection &input)
	Class constructor. More...
virtual	~OrderedParameterCollection ()
	Class destructor. More...
void	operator= (OrderedParameterCollection &right_side)
	Provides the equal operator.
virtual PacketItem *	Clone ()
	Creates and returns an extact copy of the object.
virtual void	Init ()
	Initializes the object. More...
Serialization Methods
These methods help read and write the class to disk or memory. Most users will not be interested in these. Those that are can continue reading.
int32_t	LoadFile (const char *filename)
	Loads the parameter collection definition from the specified file. More...
int32_t	SaveFile (const char *filename)
	Saves the parameter collection definition to the specified file. More...
virtual void	CalibrateBeforeBuild ()
	Sets all parameters to calibrate prior to building. Typically used for commanding only.
Public Member Functions inherited from trek::PacketItem
	PacketItem ()
	Default constructor of the class.
virtual	~PacketItem ()
	Class destructor. More...
void	operator= (PacketItem &right_side)
	Provides the equal operator.
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...
void	SetPath (const char *input_ptr)
	Sets the path for 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.
const char *	GetPath ()
	Returns the path for the item.
int32_t	AddAttribute (const char *name, const char *value)
	Adds an attribute to the item. More...
void	GetAttributeList (StringArray &attr_array)
	Gets a list of the attribute names. More...
int32_t	GetAttribute (const char *name, char *value, uint32_t &value_len)
	Get the value of the specified attribute. More...
	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 describes a parameter collection composed of one or more parameters.

The ParameterCollection class holds one or more parameters that can be built and placed in a packet based on the start location of each parameter.

Constructor & Destructor Documentation

OrderedParameterCollection() [1/2]

trek::OrderedParameterCollection::OrderedParameterCollection

(

)

Class constructor.

Default constructor of the class.

OrderedParameterCollection() [2/2]

trek::OrderedParameterCollection::OrderedParameterCollection

(

OrderedParameterCollection &

input

)

Class constructor.

Copy constructor of the class.

~OrderedParameterCollection()

trek::OrderedParameterCollection::~OrderedParameterCollection ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

Build()

int32_t trek::OrderedParameterCollection::Build ( uint8_t *  input_ptr, uint32_t *  input_length_ptr  )

virtual

Builds the parameters in the collection and places it in the specified buffer.

The parameters composing the collection are built and placed in the buffer.

Parameters

[out]	input_ptr	The buffer to place the all the parameters in the packet.
[out]	input_length_ptr	On input specifies the length available in the buffer. If SUCCESS is returned, reset to the amount of data used.

Returns

SUCCESS

TREK_DATA_WILL_NOT_FIT

TREK_DATA_NULL_PTR

Example:

OrderedParameterCollection pc;
int32_t ret_value;
unsigned char buf[100];
uint32_t last_bit;
 
ret_value = pc.Build( buf, &last_bit );
 
if( ret_value )
{
    // process error
}
else
{
    // data now in buffer
}

Implements trek::PacketItem.

Extract()

int32_t trek::OrderedParameterCollection::Extract ( uint8_t *  input_ptr, uint32_t  input_length, uint32_t &  last_bit_used  )

virtual

Extracts all of the parameters in the collection from the specified buffer.

Loops through all of the parameters contained in the collection and extracts their indiviual values (see trek::Parameter for details on what parameter extraction encompasses).

Parameters

[in]	input_ptr	The buffer to extract the parameters from.
[in]	input_length	The valid number of bytes that can be read from this buffer.
[out]	last_bit_used	Set to the last bit read from if SUCCESS is returned.

Returns

SUCCESS

TREK_DATA_NULL_PTR

TREK_LAST_BIT_ERROR

Note

Currently only returns SUCCESS, but may have other return values in a later release. The parameters within the collection that fail extraction will not have a value.

Example:

OrderedParameterCollection pc;
int32_t ret_value;
unsigned char buf[100];
uint32_t last_bit;
 
ret_value = pc.Extract( buf, 100, last_bit );
 
if( ret_value )
{
    // process error
}
else
{
    // Can get values for each parameter.
}

Implements trek::PacketItem.

FindParameter()

int32_t trek::OrderedParameterCollection::FindParameter ( const char *  input, Parameter **  param_ptr  )

virtual

Finds the specified parameter in the collection.

Returns a pointer to the data if found.

Parameters

[in]	input	The parameter to find.
[out]	param_ptr	If successful, a valid pointer to the Parameter referenced by the input.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

OrderedParameterCollection pc;
Parameter *param_ptr;
 
ret_value = pc.FindParameter( "MyParameter", param_ptr );
 
if( ret_value )
{
    // process error
}
else
    printf( "Found parameter.\n" );

Implements trek::PacketItem.

GetLengthInBits()

int32_t trek::OrderedParameterCollection::GetLengthInBits ( uint32_t &  bit_length )

virtual

Gets the length of the ordered parameter collection in bits.

The ordered parameter collection is variable length by definition and this function will always fail.

Parameters

[out]

bit_length

The returned bit length.

Returns

TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

OrderedParameterCollection pc;
uint32_t bit_len;
 
// assuming that parameter collection has some data added already.
ret_value = pc.GetLengthInBits( bit_len );
 
if( ret_value )
{
    // process error, it's always going to have an error
}
else
    printf( "# of bits used: %d.\n", bit_len );

Implements trek::PacketItem.

GetLengthInBytes()

int32_t trek::OrderedParameterCollection::GetLengthInBytes ( uint32_t &  byte_length )

virtual

Gets the length of the ordered parameter collection in bytes.

The ordered parameter collection is variable length by definition and this function will always fail.

Parameters

[out]

byte_length

The returned byte length.

Returns

TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

OrderedParameterCollection pc;
uint32_t byte_len;
 
// assuming that parameter collection has some data added already.
ret_value = pc.GetLengthInBytes( bit_len );
 
if( ret_value )
{
    // process error, it's always going to have an error
}
else
    printf( "# of bytes used: %d.\n", byte_len );

Implements trek::PacketItem.

GetMaximumLengthInBits()

uint32_t trek::OrderedParameterCollection::GetMaximumLengthInBits ( )

virtual

Returns the maximum length of the OrderedParameterCollection in bits.

If the OrderedParameterCollection has variable length data, the actual length may be less than the returned value.

Implements trek::PacketItem.

GetNumberOfParameters()

uint32_t trek::OrderedParameterCollection::GetNumberOfParameters

(

)

Returns the number of parameters currently in the collection.

Returns

Number of parameters

Example:

OrderedParameterCollection pc;
 
printf( "The collection currently has %u parameters.\n", pc.GetNumberOfParameters() );

GetParameterList()

void trek::OrderedParameterCollection::GetParameterList ( StringArray &  param_list, bool  full_name = true, bool  mod_only = false  )

virtual

Returns a list of all parameters within a collection.

The StringArray is not cleared prior to adding parameters.

Parameters

[out]	param_list	The names of all parameters in the collection.
[in]	full_name	Specifies if the fully qualified name should be returned (ignored for OrderedParameterCollections, only short names returned)
[in]	mod_only	Specifies if the returned data should be limited to modifiable parameters.

Example:

// Asssuming that the collection is populated.
ParameterCollect pc;
StringArray all_params;
 
pc.GetParameterList( all_params );
 
for( uint32_t ii = 0; ii < all_params.Size(); ii++ )
    printf("Name of parameter is %s\n.", all_params.GetAt(ii) );

Implements trek::PacketItem.

GetSortedParameterList()

void trek::OrderedParameterCollection::GetSortedParameterList ( StringArray &  param_list, bool  full_name = true, bool  mod_only = false  )

virtual

Returns a list of all parameters within a collection sorted by their start location.

The StringArray is not cleared before adding parameters.

Parameters

[out]	param_list	The names of all parameters in the collection.
[in]	full_name	Specifies if the fully qualified name should be returned (ignored for OrderedParameterCollections, only short names returned)
[in]	mod_only	Specifies if the returned data should be limited to modifiable parameters.

Example:

// Asssuming that the packet is populated.
OrderedParameterCollection pc;
StringArray all_params;
 
pc.GetSortedParameterList( all_params );
 
for( uint32_t ii = 0; ii < all_params.Size(); ii++ )
    printf("My name is %s\n." all_params.GetAt(ii) );

Implements trek::PacketItem.

HasModifiableData()

bool trek::OrderedParameterCollection::HasModifiableData ( bool  data_zone_only = true )

virtual

Determines if any of the parameters are modifiable.

Parameters

[in]

data_zone_only

Ignored by this method.

Returns

true Contains at least one modifiable parameter

false No modifiable parameters

Implements trek::PacketItem.

HasVariableLengthData()

bool trek::OrderedParameterCollection::HasVariableLengthData ( )

virtual

Determines if the parameter collection has any variable length data.

Returns

false Data is not considered variable length in this context

Implements trek::PacketItem.

Init()

void trek::OrderedParameterCollection::Init ( )

virtual

Initializes the object.

This method can be called to reinitialize a parameter collection to its default configuration. It is useful if you want to reuse the same object as shown in the example below.

Example:

OrderedParameterCollection pc;
Parameter p;
Packet pkt;
 
// not checking return codes, but you should
 
p.SetName( "First" );
p.SetDataType( DT_UNSIGNED_INTEGER, 32 );
pc.AddParameter( p );
 
p.Init();
 
p.SetName( "Second" );
p.SetDataType( DT_TWOS_COMPLEMENT, 16 );
pc.AddParameter( p );       // alias, short description, and long descriptions are blank.
 
pkt.AddHeader( pc );
 
pc.Init();      // now can be used to add data

Reimplemented from trek::PacketItem.

InsertParameter()

int32_t trek::OrderedParameterCollection::InsertParameter	(	Parameter *	input_ptr,
		uint32_t	location
	)

Adds the parameter to the collection.

Adds the parameter to the end of the delimited parameter collection. The OrderedParameterCollection makes a copy of the input.

Parameters

[in]	input_ptr	The parameter to add.
[in]	location	The insertion location within the ordered collection. If greater than last location, appends.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

Example:

OrderedParameterCollection pc;
Parameter p;
 
// assuming that parameter is set already.
ret_value = pc.AddParameter( &p );
 
if( ret_value )
{
    // process error
}
else
    printf( "Added parameter.\n" );

IsComplete()

bool trek::OrderedParameterCollection::IsComplete ( )

virtual

Determines if all parameters have a value.

Returns

true If all parameters have a value

false If one or more parameters do not have a value

Implements trek::PacketItem.

IsModifiable()

bool trek::OrderedParameterCollection::IsModifiable ( bool  top_level = true )

virtual

Determines if any of the data is modifiable.

Parameters

[in]

top_level

Designates that this is a top level packet. Default (true) should always be passed in.

Returns

false Delimited parameter collections are always considered to be non-modifiable

Implements trek::PacketItem.

LoadFile()

int32_t trek::OrderedParameterCollection::LoadFile

(

const char *

filename

)

Loads the parameter collection definition from the specified file.

Reads an XML format for the parameter collection. It can be written in with SaveFile.

Parameters

[in]

filename

The file to load the parameter object from.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Other return codes

Example:

OrderedParameterCollection pc;
 
ret_value = pc.LoadFile( "my_file.xml" );

RemoveAllParameters()

void trek::OrderedParameterCollection::RemoveAllParameters

(

)

Removes all parameters and associated memory from the collection.

Example:

OrderedParameterCollection pc;
pc.RemoveAllParameters();

RemoveParameter()

int32_t trek::OrderedParameterCollection::RemoveParameter

(

const char *

input

)

Removes the specified parameter from the collection.

Removes the parameter from the parameter collection and deletes its associated memory.

Parameters

[in]

input

The parameter to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

OrderedParameterCollection pc;
 
ret_value = pc.RemoveParameter( "MyParameter" );
 
if( ret_value )
{
    // process error
}
else
    printf( "Removed parameter.\n" );

SaveFile()

int32_t trek::OrderedParameterCollection::SaveFile

(

const char *

filename

)

Saves the parameter collection definition to the specified file.

Writes an XML format for the parameter collection. It can be read in with LoadFile.

Parameters

[in]

filename

The file to save the parameter object to.

Returns

SUCCESS

TREK_DATA_NULL_PTR

Other return codes

Example:

OrderedParameterCollection pc;
 
ret_value = pc.SaveFile( "my_file.xml" );