trek::FormatCollection Class Reference

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

#include <format_collection.h>

Inherits trek::PacketItem.

Public Member Functions
virtual int32_t	GetLengthInBits (uint32_t &bit_length)
	Gets the length of the random packet collection in bits. More...
virtual int32_t	GetLengthInBytes (uint32_t &byte_length)
	Gets the length of the format collection in bytes. More...
int32_t	AddFormat (ParameterCollection &pc, uint64_t fmt_id)
	Adds the packet to the collection. More...
int32_t	RemoveFormat (uint64_t fmt_id)
	Removes the specified format from the collection. More...
void	RemoveAllFormats ()
	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	GetNumberOfFormats ()
	Returns the number of formats 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 FormatCollection in bits. More...
bool	HasVariableLengthData ()
	Determines if the random packet collection has any variable length data. More...
virtual bool	HasModifiableData (bool data_zone_only=true)
	Determines if any of the parameters are modifiable. 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
	FormatCollection ()
	Class constructor. More...
	FormatCollection (FormatCollection &input)
	Class constructor. More...
virtual	~FormatCollection ()
	Class destructor. More...
void	operator= (FormatCollection &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 format collection composed of one or more parameter collections.

The FormatCollection class holds one or more formats that can be processed based on the foramt id.

Constructor & Destructor Documentation

FormatCollection() [1/2]

trek::FormatCollection::FormatCollection

(

)

Class constructor.

Default constructor of the class.

FormatCollection() [2/2]

trek::FormatCollection::FormatCollection

(

FormatCollection &

input

)

Class constructor.

Copy constructor of the class.

~FormatCollection()

trek::FormatCollection::~FormatCollection ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

AddFormat()

int32_t trek::FormatCollection::AddFormat	(	ParameterCollection &	fmt,
		uint64_t	fmt_id
	)

Adds the packet to the collection.

Adds the parameter collection with the format id specified. The FormatCollection makes a copy of the input.

Parameters

[in]	fmt	The parameter collection to add.
[in]	fmt_id	The format id that is assigned.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

Example:

FormatCollection fc;
Packet p;
 
// assuming that parameter is set already.
ret_value = fc.AddFormat( p, 0x4C10 );
 
if( ret_value )
{
    // process error
}
else
    printf( "Added format.\n" );

Build()

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

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

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

FormatCollection 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::FormatCollection::GetLengthInBits ( uint32_t &  bit_length )

virtual

Gets the length of the random packet collection in bits.

Since the data is variable length, this function will always return an error.

Parameters

[out]

bit_length

The returned bit length.

Returns

TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

FormatCollection 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::FormatCollection::GetLengthInBytes ( uint32_t &  byte_length )

virtual

Gets the length of the format collection in bytes.

Calculates the length of the format collection in bytes by determining the last bit used by any parameter in the packet. If the format 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:

FormatCollection 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::FormatCollection::GetMaximumLengthInBits ( )

virtual

Returns the maximum length of the FormatCollection in bits.

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

Implements trek::PacketItem.

GetNumberOfFormats()

uint32_t trek::FormatCollection::GetNumberOfFormats

(

)

Returns the number of formats currently in the collection.

Returns

Number of formats

Example:

FormatCollection pc;
 
printf( "The collection currently has %u formats.\n", pc.GetNumberOfFormats() );

GetParameterList()

void trek::FormatCollection::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 FormatCollections, 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::FormatCollection::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
[in]	mod_only	Specifies if the returned data should be limited to modifiable parameters.

Example:

// Asssuming that the packet is populated.
FormatCollection 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::FormatCollection::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::FormatCollection::HasVariableLengthData ( )

virtual

Determines if the random packet collection has any variable length data.

Returns

true Since which packets will be available at given time is unknown, the data is considered variable length.

Implements trek::PacketItem.

Init()

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

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

IsComplete()

bool trek::FormatCollection::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::FormatCollection::IsModifiable ( bool  top_level = true )

virtual

Determines if any of the data is modifiable.

Returns

false Random packet collections are always considered to be non-modifiable

Implements trek::PacketItem.

LoadFile()

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

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

RemoveAllFormats()

void trek::FormatCollection::RemoveAllFormats

(

)

Removes all parameters and associated memory from the collection.

Example:

FormatCollection pc;
pc.RemoveAllParameters();

RemoveFormat()

int32_t trek::FormatCollection::RemoveFormat

(

uint64_t

fmt_id

)

Removes the specified format from the collection.

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

Parameters

[in]

fmt_id

The format id to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

FormatCollection fc;
 
ret_value = fc.RemoveFormat( 3 );
 
if( ret_value )
{
    // process error
}
else
    printf( "Removed format.\n" );

SaveFile()

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

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