trek::ParameterCollection Class Reference

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

#include <parameter_collection.h>

Inherits trek::PacketItem.

Public Member Functions
virtual int32_t	GetLengthInBits (uint32_t &bit_length)
	Gets the length of the parameter collection in bits. More...
virtual int32_t	GetLengthInBytes (uint32_t &byte_length)
	Gets the length of the parameter collection in bytes. More...
int32_t	AddParameter (Parameter *input_ptr)
	Adds the parameter to the collection. More...
int32_t	AddParameter (Parameter &input)
	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 ParameterCollection in bits. More...
bool	HasVariableLengthData ()
	Determines if the parameter collection has any variable length data. More...
virtual bool	HasModifiableData (bool data_zone_only=true)
	Determines if any of the parameters are modifiable. More...
void	SetStart ()
	Sets the start location for the collection. More...
int32_t	GetNextParameter (Parameter **input_ptr)
	Gets the next parameter in the collection. 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...
Constructors, Destructor, and Other Basic Methods
	ParameterCollection ()
	Class constructor. More...
	ParameterCollection (ParameterCollection &input)
	Class constructor. More...
virtual	~ParameterCollection ()
	Class destructor. More...
void	operator= (ParameterCollection &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...
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...
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 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.

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp, and define_packet/define_packet.cpp.

Constructor & Destructor Documentation

ParameterCollection() [1/2]

trek::ParameterCollection::ParameterCollection

(

)

Class constructor.

Default constructor of the class.

ParameterCollection() [2/2]

trek::ParameterCollection::ParameterCollection

(

ParameterCollection &

input

)

Class constructor.

Copy constructor of the class.

~ParameterCollection()

trek::ParameterCollection::~ParameterCollection ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

AddParameter() [1/2]

int32_t trek::ParameterCollection::AddParameter

(

Parameter &

input

)

Adds the parameter to the collection.

Adds the parameter to the parameter collection with the indexed by the name of the parameter. The ParameterCollection makes a copy of the input.

Parameters

[in]

input

The parameter to add.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

Example:

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

AddParameter() [2/2]

int32_t trek::ParameterCollection::AddParameter

(

Parameter *

input_ptr

)

Adds the parameter to the collection.

Adds the parameter to the parameter collection with the indexed by the name of the parameter. The ParameterCollection makes a copy of the input.

Parameters

[in]

input_ptr

The parameter to add.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

Example:

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

Examples

define_packet/define_packet.cpp.

Build()

int32_t trek::ParameterCollection::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:

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

Implements trek::PacketItem.

Extract()

int32_t trek::ParameterCollection::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:

ParameterCollection 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::ParameterCollection::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:

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

Implements trek::PacketItem.

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

GetLengthInBits()

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

virtual

Gets the length of the parameter collection in bits.

Calculates the length of the parameter collection in bits by determining the last bit used by any parameter in the packet. If the parameter collection contains a variable length parameter, the length returned is the maximum possible length.

Parameters

[out]

bit_length

The returned bit length.

Returns

SUCCESS

TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

ParameterCollection 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
}
else
    printf( "# of bits used: %d.\n", bit_len );

Implements trek::PacketItem.

GetLengthInBytes()

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

virtual

Gets the length of the parameter collection in bytes.

Calculates the length of the parameter collection in bytes by determining the last bit used by any parameter in the packet. If the parameter collection contains a variable length parameter, this method will fail.

Parameters

[out]

byte_length

The returned byte length.

Returns

SUCCESS

TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

ParameterCollection 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
}
else
    printf( "# of bytes used: %d.\n", byte_len );

Implements trek::PacketItem.

GetMaximumLengthInBits()

uint32_t trek::ParameterCollection::GetMaximumLengthInBits ( )

virtual

Returns the maximum length of the ParameterCollection in bits.

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

Implements trek::PacketItem.

GetNextParameter()

int32_t trek::ParameterCollection::GetNextParameter

(

Parameter **

input_ptr

)

Gets the next parameter in the collection.

Used in conjunctions with SetStart to cycle through all of the parameters contained in the collection.

Returns

SUCCESS

TREK_DATA_END_OF_LIST

TREK_DATA_NULL_PTR

Example:

ParameterCollection pc;
Parameter *param_ptr;
pc.SetStart();
 
while( !GetNextParameter( &param_ptr ) )
{
    // param_ptr is valid...can set values, build, etc.
}

GetNumberOfParameters()

uint32_t trek::ParameterCollection::GetNumberOfParameters

(

)

Returns the number of parameters currently in the collection.

Returns

Number of parameters

Example:

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

GetParameterList()

void trek::ParameterCollection::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 ParameterCollections, 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::ParameterCollection::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 ParameterCollections, 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.
ParameterCollection 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.

Examples

cmd_api_cpp/cmd_api_cpp_main.cpp.

HasModifiableData()

bool trek::ParameterCollection::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::ParameterCollection::HasVariableLengthData ( )

virtual

Determines if the parameter collection has any variable length data.

Returns

true If parameter collection has any variable length data.

false If parameter collection only has fixed length data.

Implements trek::PacketItem.

Init()

void trek::ParameterCollection::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:

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

Examples

define_packet/define_packet.cpp.

IsComplete()

bool trek::ParameterCollection::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::ParameterCollection::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

true If one or more parameters in the parameter collection are modifiable

false If none of the parameters in the parameter collection are modifiable

Implements trek::PacketItem.

LoadFile()

int32_t trek::ParameterCollection::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:

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

RemoveAllParameters()

void trek::ParameterCollection::RemoveAllParameters

(

)

Removes all parameters and associated memory from the collection.

Example:

ParameterCollection pc;
pc.RemoveAllParameters();

RemoveParameter()

int32_t trek::ParameterCollection::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:

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

SaveFile()

int32_t trek::ParameterCollection::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:

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

SetStart()

void trek::ParameterCollection::SetStart

(

)

Sets the start location for the collection.

Used in conjunctions with GetNextParameter to cycle through all of the parameters contained in the collection.

Example:

ParameterCollection pc;
Parameter *param_ptr;
pc.SetStart();
 
while( !GetNextParameter( &param_ptr ) )
{
    // param_ptr is valid...can set values, build, etc.
}