trek::RandomPacketCollection Class Reference

This class describes a random packet collection composed of one or more packets. More...

#include <random_packet_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 random packet collection in bytes. More...
int32_t	AddPacket (Packet &input)
	Adds the packet to the collection. More...
int32_t	RemovePacket (const char *name)
	Removes the specified packet from the collection. More...
void	RemoveAllPackets ()
	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	GetNumberOfPackets ()
	Returns the number of packets 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 RandomPacketCollection 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
	RandomPacketCollection ()
	Class constructor. More...
	RandomPacketCollection (RandomPacketCollection &input)
	Class constructor. More...
virtual	~RandomPacketCollection ()
	Class destructor. More...
void	operator= (RandomPacketCollection &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 random packet collection composed of one or more packets.

The RandomPacketCollection class holds one or more packets that are processed as subsets of data.

Constructor & Destructor Documentation

RandomPacketCollection() [1/2]

trek::RandomPacketCollection::RandomPacketCollection

(

)

Class constructor.

Default constructor of the class.

RandomPacketCollection() [2/2]

trek::RandomPacketCollection::RandomPacketCollection

(

RandomPacketCollection &

input

)

Class constructor.

Copy constructor of the class.

~RandomPacketCollection()

trek::RandomPacketCollection::~RandomPacketCollection ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

AddPacket()

int32_t trek::RandomPacketCollection::AddPacket

(

Packet &

input

)

Adds the packet to the collection.

Adds the packet to the random packet collection with the indexed by the name of the packet. The RandomPacketCollection makes a copy of the input.

Parameters

[in]

input

The packet to add.

Returns

SUCCESS

TREK_DATA_ALREADY_EXISTS

TREK_DATA_NULL_PTR

Example:

RandomPacketCollection rpc;
Packet pkt;
 
ret_value = pkt.LoadFile( "my_file.xml" );
ret_value = rpc.AddPacket( pkt );
 
if( ret_value )
{
    // process error
}
else
    printf( "Added packet.\n" );

Build()

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

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

TREK_DATA_NO_IDENTIFIER

Example:

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

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

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

virtual

Gets the length of the random packet collection in bytes.

Calculates the length of the random packet 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:

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

virtual

Returns the maximum length of the RandomPacketCollection in bits.

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

Implements trek::PacketItem.

GetNumberOfPackets()

uint32_t trek::RandomPacketCollection::GetNumberOfPackets

(

)

Returns the number of packets currently in the collection.

Returns

Number of packets

Example:

RandomPacketCollectionr pc;
 
printf( "The collection currently has %u packets.\n", prc.GetNumberOfPackets() );

GetParameterList()

void trek::RandomPacketCollection::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 RandomPacketCollections, 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::RandomPacketCollection::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.
RandomPacketCollection 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::RandomPacketCollection::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::RandomPacketCollection::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::RandomPacketCollection::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:

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

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

RemoveAllPackets()

void trek::RandomPacketCollection::RemoveAllPackets

(

)

Removes all parameters and associated memory from the collection.

Example:

RandomPacketCollection pc;
pc.RemoveAllParameters();

RemovePacket()

int32_t trek::RandomPacketCollection::RemovePacket

(

const char *

input

)

Removes the specified packet from the collection.

Removes the packet from the random packet collection and deletes its associated memory.

Parameters

[in]

input

The packet to remove.

Returns

SUCCESS

TREK_DATA_DOES_NOT_EXIST

TREK_DATA_NULL_PTR

Example:

RandomPacketCollection rpc;
 
ret_value = rpc.RemovePacket( "MyPacket" );
 
if( ret_value )
{
    // process error
}
else
    printf( "Removed packet.\n" );

SaveFile()

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

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