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

#include <packet.h>

Public Member Functions
	Packet ()
	Class constructor. More...

virtual	~Packet ()
	Class destructor. More...

PacketItem *	Clone ()
	Creates and returns an extact copy of the object.

void	Init ()
	Initializes the object. More...

void	operator= (Packet &right_side)
	Provides the equal operator.

Packet Attribute Methods
These methods are for attributes associated with a packet.
int32_t	SetLengthParameter (const char *name, packet_zone_type zone, int32_t offset=0)
	Sets the length parameter for the packet. More...

int32_t	SetCounterParameter (const char *name, packet_zone_type zone, uint32_t start_count=0, bool fwd_count=true, uint32_t min_count=0, uint32_t max_count=0, uint32_t reset_count=0)
	Sets the counter parameter for the packet. More...

int32_t	SetChecksumParameter (const char *name, packet_zone_type zone, packet_checksum_point_type start_pt, int32_t start_offset, packet_checksum_point_type end_pt, int32_t end_offset, packet_checksum_type type)
	Sets the checksum parameter for the packet. More...

int32_t	AddIdentifier (const char name, packet_identifier_struct id_struct_ptr)
	Adds an identifier to the packet. More...

int32_t	AddIdentifier (const char *name, packet_zone_type zone, identifier_types type, bool default_value_available, int32_t default_value, bool expected_value_available, int32_t expected_value)
	Adds an identifier to the packet. More...

int32_t	SetTimeStampParameter (const char *name, packet_zone_type zone, double offset_in_secs=0)
	Sets the time stamp parameter for the packet. More...

void	ClearLengthParameter ()
	Turns off length calculation when calling Build.

void	ClearCounterParameter ()
	Turns off counter generation when calling Build.

void	ClearTimeStampParameter ()
	Turns off time stamp generation when calling Build.

void	ClearChecksumParameter ()
	Turns off checksum parameter calculation when calling Build.

void	RemoveAllIdentifiers ()
	Removes all identifiers from the packet. More...

int32_t	RemoveIdentifier (const char *name)
	Removes the specified parameter as an identifier. More...

int32_t	UpdateExpectedValue (const char *name, int32_t new_value)
	Updates the expected value for an identifier. More...

const char *	GetLengthParameter ()
	Returns the name of the parameter that is used for the length of the packet. More...

const char *	GetCounterParameter ()
	Returns the name of the parameter that is used for the counter of the packet. More...

const char *	GetTimeStampParameter ()
	Returns the name of the parameter that is used for the time stamp of the packet. More...

const char *	GetChecksumParameter ()
	Returns the name of the parameter that is used for the checksum of the packet. More...

int32_t	GetLengthParameterInfo (packet_zone_type &zone, int32_t &offset, uint32_t &parent_start_bit)
	Gets the length parameter's attributes. More...

int32_t	GetCounterParameterInfo (packet_zone_type &zone, uint32_t &start_count, bool &fwd_count, uint32_t &min_count, uint32_t &max_count, uint32_t &parent_start_bit)
	Gets the counter parameter's associated attributes. More...

int32_t	GetCounterParameterInfo (packet_zone_type &zone, uint32_t &start_count, bool &fwd_count, uint32_t &min_count, uint32_t &max_count, uint32_t &reset_value, uint32_t &parent_start_bit)
	Gets the counter parameter's associated attributes. More...

int32_t	GetTimeStampParameterInfo (packet_zone_type &zone, double &offset_in_secs, uint32_t &parent_start_bit)
	Gets the time stamp parameter's attributes. More...

int32_t	GetChecksumParameterInfo (packet_zone_type &zone, packet_checksum_point_type &start_pt, int32_t &start_offset, packet_checksum_point_type &end_pt, int32_t &end_offset, packet_checksum_type &type)
	Gets the checksum parameter's attributes. More...

int32_t	GetIdentifierInfo (const char *name, packet_zone_type &zone, identifier_types &type, bool &has_default_value, int32_t &default_value, bool &has_expected_value, int32_t &expected_value, uint32_t &parent_start_bit)
	Retrieves the attributes associated with the named identifier. More...

int32_t	GetIdentifierInfo (const char *name, packet_zone_type &zone, identifier_types &type, bool &has_default_value, int32_t &default_value, bool &has_expected_value, int32_t &expected_value)
	Retrieves the attributes associated with the named identifier. More...

int32_t	GetIdentifierInfo (const char *name, identifier_types &type)
	Retrieves the type associated with the named identifier. More...

bool	HasVariableLengthData ()
	Determines if the Packet has any variable length data. More...

void	SetPacketType (const char *input)
	Sets the packet type. Intended for internal use only.

void	SetShortPacketType (const char *input)
	Sets the short packet type. Intended for internal use only.

const char *	GetPacketType ()
	Get the packet type. Intended for internal use only.

const char *	GetShortPacketType ()
	Get the short packet type. Intended for internal use only.

void	GetIdentifierList (StringArray &id_list, bool recursive=true)
	Gets a list of the parameter names used as identifiers. More...

void	SetModifiableFlagForAllParameters (bool input)
	Sets the modifiable flag for all parameters currently in the packet. More...

virtual bool	HasModifiableData (bool data_zone_only=true)
	Determines if the packet has any modifiable data. More...

int32_t	ReplaceZone (const char zone_path, PacketItem item)

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 Packet definition from the specified file. More...

int32_t	SaveFile (const char *filename)
	Saves the Packet definition to the specified file. More...

Debug Methods
These methods are helpful to debug problems.
const char *	PrintDefinition (bool include_value=false)
	Returns a string with basic information about all parameters in the packet. More...

const char *	PrintValues ()
	Returns a string with the value of all parameters in the packet. More...

const char *	PrintPacket (uint8_t *pkt, uint32_t pkt_len)
	This method is used to print all of the headers in the packet and a hexidecimal representation of the packet contents. 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.

Working With the Entire Packet
These methods apply to the entire packet.
int32_t	Validate ()
	Validates that the data contained in the packet is logically correct. More...

const char *	GetValidationErrors ()
	Gets a string of the last validation errors. More...

int32_t	GetLengthInBits (uint32_t &bit_length)
	Gets the length of the packet in bits. More...

int32_t	GetLengthInBytes (uint32_t &byte_length)
	Gets the length of the packet in bytes. More...

bool	HasChecksumError ()
	Determines if the last packet extraction had a checksum error. More...

bool	HasLengthError ()
	Determines if the last packet extraction had a length error. More...

int32_t	AddHeader (PacketItem &item)
	Sets the specified packet item as the header for the packet. More...

int32_t	AddData (PacketItem &item)
	Sets the specified packet item as the data for the packet. More...

int32_t	AddTrailer (PacketItem &item)
	Sets the specified packet item as the trailer for the packet. More...

void	RemoveHeader ()
	Removes the header from the packet. More...

void	RemoveData ()
	Removes the data from the packet. More...

void	RemoveTrailer ()
	Removes the trailer from the packet. More...

bool	HasHeaderZone ()
	Determines if the packet has a header zone. More...

bool	HasDataZone ()
	Determines if the packet has a data zone. More...

bool	HasTrailerZone ()
	Determines if the packet has a trailer zone. More...

int32_t	GetHeaderZone (PacketItem **copy_ptr)

int32_t	GetDataZone (PacketItem **copy_ptr)

int32_t	GetTrailerZone (PacketItem **copy_ptr)

int32_t	GetHeaderLengthInBits (uint32_t &len)
	Gets the length of the header in bits. More...

int32_t	GetHeaderLengthInBytes (uint32_t &len)
	Gets the length of the header in bits. More...

int32_t	Build (uint8_t input_ptr, uint32_t input_length_ptr)
	Builds the packet 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 packet from the specified buffer. More...

int32_t	CreateGlobalPacketMap ()
	Creates the map used to hold all of the parameters. More...

int32_t	FindParameter (const char name, Parameter *param_ptr)
	Finds the specified parameter name in the packet. More...

int32_t	FindLastParameter (const char name, Parameter *param_ptr)
	Finds the specified parameter name in the packet. More...

int32_t	GetFullyQualifiedNames (const char *name, StringArray &array)
	Gets all of the fully qualified names for a given parameter name within a packet. More...

void	GetParameterList (StringArray &param_list, bool full_name=true, bool mod_only=false)
	Returns a list of all parameters within a packet. More...

void	GetSortedParameterList (StringArray &param_list, bool full_name=true, bool mod_only=false)
	Returns a list of all parameters within a packet sorted by their start location. More...

void	SetTimeStampOffset (double offset_in_secs)
	Sets an offset for the current system time to use when building packets. More...

uint32_t	GetMaximumLengthInBits ()
	Returns the maximum length of the packet in bits. More...

void	ClearGlobalPacketMap ()
	Removes all parameters from the global packet map. More...

bool	IsComplete ()
	Determines if the packet definition is considered complete. More...

virtual bool	IsModifiable (bool top_level=true)
	Determines if any of the data is modifiable. More...

void	ClearAllParameterValues ()
	Clears each parameter value in the packet. More...

Detailed Description

This class describes a packet composed of one or more parameters.

The Packet class encapsulates one or more parameters that can be built or extracted. The Packet class has three zones: header, data, and trailer. For the Packet to be considered valid, at least one zone must be populated. Each zone can be populated with a ParameterCollection or another Packet. The example below shows a packet that has all three zones populated. The Header and Trailer zones consist of a parameter collection and the Data zone consists of another Packet which only has two zones populated (Header and Data).

Examples: build_packet/build_packet.cpp, define_packet/define_packet.cpp, extract_packet/extract_packet.cpp, tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

Constructor & Destructor Documentation

◆ Packet()

trek::Packet::Packet ( )

Class constructor.

Default constructor of the class.

◆ ~Packet()

trek::Packet::~Packet ( )

virtual

Class destructor.

Removes all resources created with this instance of the class.

Member Function Documentation

◆ AddData()

int32_t trek::Packet::AddData ( PacketItem & item )

Sets the specified packet item as the data for the packet.

A copy of the input is made. Any changes made to the input after being added will not be part of the packet unless the data is removed using RemoveData and the changes are added again. The global packet map is cleared as part of this method.

Parameters

[in] item The Packet or ParameterCollection to use as the data.

Returns: SUCCESS; TREK_DATA_ZONE_ALREADY_EXISTS

Example:

Packet pkt;
ParameterCollection pc;
int32_t ret_value;
 
// use pc.AddParameter() and other methods to populate the ParameterCollection
 
ret_value = pkt.AddData( pc );
 
if( ret_value )
{
    // process errors
}
else
    printf("Data added\n");

Examples: define_packet/define_packet.cpp.

◆ AddHeader()

int32_t trek::Packet::AddHeader ( PacketItem & item )

Sets the specified packet item as the header for the packet.

A copy of the input is made. Any changes made to the input after being added will not be part of the packet unless the header is removed using RemoveHeader and the changes are added again. The global packet map is cleared as part of this method.

Parameters

[in] item The Packet or ParameterCollection to use as the header.

Returns: SUCCESS; TREK_DATA_ZONE_ALREADY_EXISTS

Example:

Packet pkt;
ParameterCollection pc;
int32_t ret_value;
 
// use pc.AddParameter() and other methods to populate the ParameterCollection
 
ret_value = pkt.AddHeader( pc );
 
if( ret_value )
{
    // process errors
}
else
    printf("Header added\n");

Examples: define_packet/define_packet.cpp.

◆ AddIdentifier() [1/2]

int32_t trek::Packet::AddIdentifier	(	const char *	name,
		packet_identifier_struct *	id_struct_ptr
	)

Adds an identifier to the packet.

The identifiers are set by Build and will override any data set by a user.

Note: The identifier parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the identifier.
[in]	id_struct_ptr	Structure with all of the details about the identifier.

Returns: SUCCESS; TREK_DATA_ALREADY_EXISTS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// 
packet_identifier_struct my_struct;
char *name = "APID";
int32_t ret_value;
Packet pkt;     // assuming that parameters are already added
 
my_struct.zone = HEADER_ZONE;
my_struct.type = FIXED_VALUE_IDENTIFIER;
my_struct.default_value_available = false;  // no need to set default_value
my_struct.expected_value_available = true;
my_struct.expected_value = 7;
 
ret_value = pkt.AddIdentifier( name, &my_struct );
 
if( ret_value )
{
    // process error
}
else
    printf("Success!\n");

Examples: define_packet/define_packet.cpp.

◆ AddIdentifier() [2/2]

int32_t trek::Packet::AddIdentifier	(	const char *	name,
		packet_zone_type	zone,
		identifier_types	type,
		bool	default_value_available,
		int32_t	default_value,
		bool	expected_value_available,
		int32_t	expected_value
	)

Adds an identifier to the packet.

The identifiers are set by Build and will override any data set by a user.

Note: The identifier parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the identifier.
[in]	zone	The zone containing the identifier parameter.
[in]	type	The type of identifier.
[in]	default_value_available	If true, the default_value is valid.
[in]	default_value	Only valid if has_default_value=true.
[in]	expected_value_available	If true, the expected_value is valid.
[in]	expected_value	Only valid if has_expected_value=true.

Returns: SUCCESS; TREK_DATA_ALREADY_EXISTS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// 
char *name = "APID";
int32_t ret_value;
Packet pkt;     // assuming that parameters are already added
 
ret_value = pkt.AddIdentifier( name, HEADER_ZONE, FIXED_VALUE_IDENTIFIER, false, 0, true, 7 );
 
if( ret_value )
{
    // process error
}
else
    printf("Success!\n");

◆ AddTrailer()

int32_t trek::Packet::AddTrailer ( PacketItem & item )

Sets the specified packet item as the trailer for the packet.

A copy of the input is made. Any changes made to the input after being added will not be part of the trailer unless the header is removed using RemoveTrailer and the changes are added again. The global packet map is cleared as part of this method.

Parameters

[in] item The Packet or ParameterCollection to use as the trailer.

Returns: SUCCESS; TREK_DATA_ZONE_ALREADY_EXISTS

Example:

Packet pkt;
ParameterCollection pc;
int32_t ret_value;
 
// use pc.AddParameter() and other methods to populate the ParameterCollection
 
ret_value = pkt.AddTrailer( pc );
 
if( ret_value )
{
    // process errors
}
else
    printf("Trailer added\n");

Examples: define_packet/define_packet.cpp.

◆ Build()

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

virtual

Builds the packet and places it in the specified buffer.

The parameters composing the packet are built and placed in the buffer. After building the parameters, the length, time stamp, counter, and checksum parameters are set if specified. Since nesting of packets is allowed (packet within a packet). The innermost packet is built first.

Parameters

[out]	input_ptr	The buffer to place the all the parameters in the packet.
[in,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_ERROR_BUILDING_HEADER_ZONE; TREK_DATA_ERROR_BUILDING_DATA_ZONE; TREK_DATA_ERROR_BUILDING_TRAILER_ZONE; TREK_DATA_NOT_ENOUGH_SPACE; TREK_DATA_ERROR_BUILDING_LEN_PARAM; TREK_DATA_NEG_LEN_ERROR; TREK_DATA_ERROR_BUILDING_COUNTER_PARAM; TREK_DATA_ERROR_BUILDING_TIME_PARAM; TREK_DATA_ERROR_BUILDING_IDENTIFIER; TREK_DATA_ERROR_BUILDING_CHECKSUM_PARAM; TREK_DATA_NULL_PTR

Example:

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

Implements trek::PacketItem.

Examples: build_packet/build_packet.cpp.

◆ ClearAllParameterValues()

void trek::Packet::ClearAllParameterValues ( )

Clears each parameter value in the packet.

This will prevent the Build method from succeeding.

Example:

Packet pkt;

pkt.ClearAllParameterValues();

trek::Packet::ClearAllParameterValues

void ClearAllParameterValues()

Clears each parameter value in the packet.

Definition: packet.cpp:1268

◆ ClearGlobalPacketMap()

void trek::Packet::ClearGlobalPacketMap ( )

Removes all parameters from the global packet map.

If parameters are added after CreateGlobalPacketMap is called, this method should be called and the global packet map recreated with another call to CreateGlobalPacketMap.

Example:

// You should add packets to the parameter collections first.
// Not shown here for simplication of example.
Packet pkt;
 
pkt.ClearGlobalPacketMap();

◆ CreateGlobalPacketMap()

int32_t trek::Packet::CreateGlobalPacketMap ( )

Creates the map used to hold all of the parameters.

The parameters composing the packet are stored in a map for quick lookup. After all of the data has been added to the packet, this method should be called to build the map.

Returns: SUCCESS

Example:

// You should add packets to the parameter collections first.
// Not shown here for simplication of example.
Packet pkt;
ParameterCollection hdr_pc, data_pc, trailer_pc;
int ret_value;
 
pkt.AddHeader( hdr_pc );
pkt.AddData( data_pc );
pkt.AddTrailer( trailer_pc );
 
ret_value = pkt.CreateGlobalPacketMap();
 
if( ret_value )
{
    // process error (currently none, but that may change).
}

Examples: build_packet/build_packet.cpp, define_packet/define_packet.cpp, and extract_packet/extract_packet.cpp.

◆ Extract()

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

virtual

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

Loops through all of the parameters contained in the packet and extracts their indiviual values (see Parameter for details on what parameter extraction encompasses). If a checksum parameter is defined, the checksum for the buffer is checked to ensure that the data is not corrupt. If the checksum does not match, the data is still extracted. An error will be returned indicating that there is a checksum error. The ParameterStatus associated with any GetValue calls for a Parameter will have the Data Quality Checksum Error set to indicate that the value may be bad.

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_NO_PARENT; TREK_DATA_EXT_NUM_SAMP_EXTRACT_FAIL; TREK_DATA_EXT_NUM_SAMP_PARAM_NOT_FOUND; TREK_DATA_EXT_STATUS_PARAM_NOT_FOUND; TREK_DATA_EXT_NUM_SAMP_BAD_VALUE; TREK_DATA_EXT_NUM_SAMP_VALUE_FAIL; TREK_DATA_INVALID_DATA_TYPE; TREK_DATA_INVALID_BYTE_ORDER; TREK_DATA_INVALID_DATA_TYPE; TREK_DATA_NULL_PTR; TREK_DATA_PACKET_LENGTH_ERROR

Example:

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

Implements trek::PacketItem.

Examples: extract_packet/extract_packet.cpp, tlm_api_cpp_newest/cpp_newest_main.cpp, and tlm_api_cpp_next/cpp_next_main.cpp.

◆ FindLastParameter()

int32_t trek::Packet::FindLastParameter	(	const char *	name,
		Parameter **	param_ptr
	)

Finds the specified parameter name in the packet.

This method will return the last parameter successfully extracted in the packet. If multiple parameters are stored in a packet (e.g., the same parameter exists in multiple formats), this is the method to use to get the current value. It is used by all TReK Telemetry API calls.

Parameters

[in]	name	The name of the parameter to find.
[out]	param_ptr	The found parameter. Only set if return code indicates success.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// Asssuming that the packet is populated.
Packet pkt;
Parameter *p_ptr;
int ret_value;
 
ret_value = pkt.FindLastParameter( "MyParameterName", &p_ptr );
if( ret_value )
{
    // process error
}
else
{
    printf("length of parameter is %u\n." p_ptr->GetLength());
}

◆ FindParameter()

int32_t trek::Packet::FindParameter	(	const char *	name,
		Parameter **	param_ptr
	)

virtual

Finds the specified parameter name in the packet.

Parameters are stored in the map with two names. The short name (the actual name in the Parameter class) and a fully qualified name which includes the packet hierarchy. If two or more parameters have the same name, you must use the fully qualified name to find the packet. Otherwise, either name will work. The fully qualified names for a given parameter can be found using GetFullyQualifiedNames.

Parameters

[in]	name	The name of the parameter to find.
[out]	param_ptr	The found parameter. Only set if return code indicates success.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_MORE_THAN_ONE_PARAMETER; TREK_DATA_NULL_PTR

Example:

// Asssuming that the packet is populated.
Packet pkt;
Parameter *p_ptr;
int ret_value;
 
ret_value = pkt.FindParameter( "MyParameterName", &p_ptr );
if( ret_value )
{
    // process error
}
else
{
    printf("length of parameter is %u\n." p_ptr->GetLength());
}

Implements trek::PacketItem.

Examples: build_packet/build_packet.cpp, extract_packet/extract_packet.cpp, and tlm_api_cpp_newest/cpp_newest_main.cpp.

◆ GetChecksumParameter()

const char * trek::Packet::GetChecksumParameter ( )

Returns the name of the parameter that is used for the checksum of the packet.

A blank name indicates that the checksum parameter has not been set. If the returned value is not blank, then the checksum attributes associated with the parameter can be retrieved using GetChecksumParameterInfo.

Returns: The name of the checksum parameter. Blank if not in use.

Example:

Packet pkt;     // assuming that packet is set up
 
if( strcmp( pkt.GetChecksumParameter(), "" ) )
{
    // call GetChecksumParameterInfo for details
}
else
    printf("Blank name...no info to retrieve!\n");

◆ GetChecksumParameterInfo()

int32_t trek::Packet::GetChecksumParameterInfo	(	packet_zone_type &	zone,
		packet_checksum_point_type &	start_pt,
		int32_t &	start_offset,
		packet_checksum_point_type &	end_pt,
		int32_t &	end_offset,
		packet_checksum_type &	type
	)

Gets the checksum parameter's attributes.

Retrieves the zone (header, data, trailer) where the checksum parameter can be found, the start count for the parameter, the direction of the count, the minimum count value the maximum count value, and its parent's start bit. Details about the counter parameter can be retrieved with FindParameter.

Note: The checksum parameter is only returned for the outermost packet. If a checksum exists in an inner packet, it will not be found...at least not yet.

Parameters

[out]	zone	The zone containing the checksum parameter.
[out]	start_pt	The start point for the checksum.
[out]	start_offset	The offset relative to the start point.
[out]	end_pt	The end point for the checksum.
[out]	end_offset	The offset relative to the end point.
[out]	type	The type of checksum performed.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
packet_zone_type zone;
packet_checksum_point_type start_pt, end_ptr; 
int32_t start_offset, end_offset; 
packet_checksum_type type;
 
ret_value = pkt.GetChecksumParameterInfo( zone, start_pt, start_offset, end_pt, end_offset, type );
 
if( ret_value )
{
    // no checksum parameter is set
}
else
    printf("Checksum parameter found and it has a start offset of %d\n", start_offset);

◆ GetCounterParameter()

const char * trek::Packet::GetCounterParameter ( )

Returns the name of the parameter that is used for the counter of the packet.

A blank name indicates that the counter parameter has not been set. If the returned value is not blank, then the counter attributes associated with the parameter can be retrieved using GetCounterParameterInfo.

Returns: The name of the counter parameter. Blank if not in use.

Example:

Packet pkt;     // assuming that packet is set up
 
if( strcmp( pkt.GetCounterParameter(), "" ) )
{
    // call GetCounterParameterInfo for details
}
else
    printf("Blank name...no info to retrieve!\n");

◆ GetCounterParameterInfo() [1/2]

int32_t trek::Packet::GetCounterParameterInfo	(	packet_zone_type &	zone,
		uint32_t &	start_count,
		bool &	fwd_count,
		uint32_t &	min_count,
		uint32_t &	max_count,
		uint32_t &	parent_start_bit
	)

Gets the counter parameter's associated attributes.

Retrieves the zone (header, data, trailer) where the counter parameter can be found, the start count for the parameter, the direction of the count, the minimum count value the maximum count value, and its parent's start bit. Details about the counter parameter can be retrieved with FindParameter.

Note: If there is not a counter parameter associated with this packet, the function will return the outermost counter associated with any subpackets.

Parameters

[out]	zone	The zone containing the couter parameter.
[out]	start_count	The beginning value of the counter.
[out]	fwd_count	If true, an incrementing counter. If false, counter decrements.
[out]	min_count	The minimum count value allowed. For forward counters, also used as next value when max_count is reached.
[out]	max_count	The maximum count value allowed. For decrementing counters, also used as the next value when min_count is reached.
[out]	parent_start_bit	The start bit of the parameter's parent.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
packet_zone_type the_zone;
bool fwd_count;
uint32_t start_cnt, min_cnt, max_cnt, parent_start_bit;
 
ret_value = pkt.GetCounterParameterInfo( zone, start_cnt, fwd_count, min_cnt, max_cnt, parent_start_bit );
 
if( ret_value )
{
    // no counter parameter is set
}
else
    printf("Counter parameter found and it has a start count of %d\n", start_cnt);

◆ GetCounterParameterInfo() [2/2]

int32_t trek::Packet::GetCounterParameterInfo	(	packet_zone_type &	zone,
		uint32_t &	start_count,
		bool &	fwd_count,
		uint32_t &	min_count,
		uint32_t &	max_count,
		uint32_t &	reset_value,
		uint32_t &	parent_start_bit
	)

Gets the counter parameter's associated attributes.

Retrieves the zone (header, data, trailer) where the counter parameter can be found, the start count for the parameter, the direction of the count, the minimum count value the maximum count value, and its parent's start bit. Details about the counter parameter can be retrieved with FindParameter.

Note: If there is not a counter parameter associated with this packet, the function will return the outermost counter associated with any subpackets.

Parameters

[out]	zone	The zone containing the couter parameter.
[out]	start_count	The beginning value of the counter.
[out]	fwd_count	If true, an incrementing counter. If false, counter decrements.
[out]	min_count	The minimum count value allowed. For forward counters, also used as next value when max_count is reached.
[out]	max_count	The maximum count value allowed. For decrementing counters, also used as the next value when min_count is reached.
[out]	reset_value	The value a counter resets to when the minimum or maximum count is reached.
[out]	parent_start_bit	The start bit of the parameter's parent.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
packet_zone_type the_zone;
bool fwd_count;
uint32_t start_cnt, min_cnt, max_cnt, reset_value, parent_start_bit;
 
ret_value = pkt.GetCounterParameterInfo( zone, start_cnt, fwd_count, min_cnt, max_cnt, reset_value, parent_start_bit );
 
if( ret_value )
{
    // no counter parameter is set
}
else
    printf("Counter parameter found and it has a start count of %d\n", start_cnt);

◆ GetFullyQualifiedNames()

int32_t trek::Packet::GetFullyQualifiedNames	(	const char *	name,
		StringArray &	found_parameters
	)

virtual

Gets all of the fully qualified names for a given parameter name within a packet.

Fully qualified names are required to be used when mulitple parameters exist with the same name within a packet. This is most likely to happen when a common parameter name such as "Length" is used more than once. For example, a packet encapsulating another packet may each have a "Length" parameter. It is suggested that more explicit names be used where possible (e.g., "CCSDSLength").

Parameters

[in]	name	The name of the parameter.
[out]	found_parameters	The fully qualified names of all parameters in the packet. Only set if return is success.

Returns: SUCCESS; TREK_DATA_UNEXPECTED_ERROR; TREK_DATA_NULL_PTR; TREK_DATA_DOES_NOT_EXIST

Example:

// Asssuming that the packet is populated.
Packet pkt;
StringArray found_params;
int ret_value;
 
ret_value = pkt.GetFullyQualifiedNames( "MyParameterName", found_params );
if( ret_value )
{
    // process error
}
else
{
    for( uint32_t ii = 0; ii < found_params.Size(); ii++ )
        printf("Full name is %s\n." found_params.GetAt(ii) );
}

Reimplemented from trek::PacketItem.

◆ GetHeaderLengthInBits()

int32_t trek::Packet::GetHeaderLengthInBits ( uint32_t & len )

Gets the length of the header in bits.

Calculates the length of the header in bits by determining the last bit used by any parameter in the header. CreateGlobalPacketMap must be called before this method will work.

Parameters

[out] len The returned bit length.

Returns: SUCCESS; TREK_DATA_MISSING_ZONE

Example:

Packet pkt;
uint32_t bit_len;
 
// assuming that packet has some data added already.
pkt.CreateGlobalPacketMap();
ret_value = pkt.GetHeaderLengthInBits( bit_len );
 
if( ret_value )
{
    // process error
}
else
    printf( "# of bits used: %d.\n", bit_len );

◆ GetHeaderLengthInBytes()

int32_t trek::Packet::GetHeaderLengthInBytes ( uint32_t & len )

Gets the length of the header in bits.

Calculates the length of the header in bits by determining the last bit used by any parameter in the header. CreateGlobalPacketMap must be called before this method will work.

Parameters

[out] len The returned bit length.

Returns: SUCCESS; TREK_DATA_MISSING_ZONE

Example:

Packet pkt;
uint32_t byte_len;
 
// assuming that packet has some data added already.
pkt.CreateGlobalPacketMap();
ret_value = pkt.GetHeaderLengthInBytes( byte_len );
 
if( ret_value )
{
    // process error
}
else
    printf( "# of bytes used: %d.\n", byte_len );

◆ GetIdentifierInfo() [1/3]

int32_t trek::Packet::GetIdentifierInfo	(	const char *	name,
		identifier_types &	type
	)

Retrieves the type associated with the named identifier.

Details about the identifier parameter can be retrieved with FindParameter.

Parameters

[in]	name	The name of the parameter to used for a counter.
[out]	type	The type of identifier.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

Packet pkt;     // assuming that parameters are already added
char *name = "id"; 
identifier_types type;
 
ret_value = pkt.GetIdentifierInfo( name, type );
 
if( ret_value )
{
    // couldn't find an identifier with that name
}
else
    printf("Identifier found\n");

◆ GetIdentifierInfo() [2/3]

int32_t trek::Packet::GetIdentifierInfo	(	const char *	name,
		packet_zone_type &	zone,
		identifier_types &	type,
		bool &	has_default_value,
		int32_t &	default_value,
		bool &	has_expected_value,
		int32_t &	expected_value
	)

Retrieves the attributes associated with the named identifier.

For the specified identifier the following information is retrieved: the zone (header, data, trailer) where it can be found, the type of identifier, when or not it has a default value, the default value, whether or not it has an expected value, and the expected value. Details about the identifier parameter can be retrieved with FindParameter.

Parameters

[in]	name	The name of the parameter to used for a counter.
[out]	zone	The zone containing the length parameter.
[out]	type	The type of identifier.
[out]	has_default_value	If true, the default_value is valid.
[out]	default_value	Only valid if has_default_value=true.
[out]	has_expected_value	If true, the expected_value is valid.
[out]	expected_value	Only valid if has_expected_value=true.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

Packet pkt;     // assuming that parameters are already added
char *name = "id"; 
packet_zone_type zone;
identifier_types type;
bool has_default_value, has_expected_value; 
int32_t default_value, expected_value; 
 
ret_value = pkt.GetIdentifierInfo( name, 
                                   zone, 
                                   type, 
                                   has_default_value, 
                                   default_value, 
                                   has_expected_value, 
                                   expected_value );
 
if( ret_value )
{
    // couldn't find an identifier with that name
}
else
    printf("Identifier found\n");

◆ GetIdentifierInfo() [3/3]

int32_t trek::Packet::GetIdentifierInfo	(	const char *	name,
		packet_zone_type &	zone,
		identifier_types &	type,
		bool &	has_default_value,
		int32_t &	default_value,
		bool &	has_expected_value,
		int32_t &	expected_value,
		uint32_t &	parent_start_bit
	)

Retrieves the attributes associated with the named identifier.

For the specified identifier the following information is retrieved: the zone (header, data, trailer) where it can be found, the type of identifier, when or not it has a default value, the default value, whether or not it has an expected value, the expected value , and its parent's start bit. Details about the identifier parameter can be retrieved with FindParameter.

Parameters

[in]	name	The name of the parameter to used for a counter.
[out]	zone	The zone containing the length parameter.
[out]	type	The type of identifier.
[out]	has_default_value	If true, the default_value is valid.
[out]	default_value	Only valid if has_default_value=true.
[out]	has_expected_value	If true, the expected_value is valid.
[out]	expected_value	Only valid if has_expected_value=true.
[out]	parent_start_bit	The start bit of the parameter's parent.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
char *name = "id"; 
packet_zone_type zone;
identifier_types type;
bool has_default_value, has_expected_value; 
int32_t default_value, expected_value; 
uint32_t parent_start_bit;
 
ret_value = pkt.GetIdentifierInfo( name, 
                                   zone, 
                                   type, 
                                   has_default_value, 
                                   default_value, 
                                   has_expected_value, 
                                   expected_value, 
                                   parent_start_bit );
 
if( ret_value )
{
    // couldn't find an identifier with that name
}
else
    printf("Identifier found\n");

◆ GetIdentifierList()

void trek::Packet::GetIdentifierList	(	StringArray &	id_list,
		bool	recursive = `true`
	)

Gets a list of the parameter names used as identifiers.

The parameter names returned are identified by their short name. It is possible for the same name to appear multiple times in the StringArray. GetFullyQualifiedNames can be used to get the detailed name of the parameter to resolve conflicts. If no identifiers are available, the returned StringArray is unchanged. The StringArray is not cleared prior to adding identifiers.

Parameters

[out]	id_list	The short names of all identifier parameters.
[out]	recursive	Determines if identifier seach includes sub-packets.

Example:

Packet pkt;
StringArray the_list;
pkt.GetIdentifierList( the_list, true );
 
if( ret_value )
{
    // process error
}
else
{
    for( uint32_t ii = 0; ii < the_list.size(); ii++ )
        printf("Identifier name is: %s\n", the_list[ii].c_str() );
}

◆ GetLengthInBits()

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

virtual

Gets the length of the packet in bits.

Calculates the length of the packet in bits by determining the last bit used by any parameter in the packet. CreateGlobalPacketMap must be called before this method will work. The packet must have a fixed length or it will fail.

Parameters

[out] bit_length The returned bit length.

Returns: SUCCESS; TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

Packet pkt;
uint32_t bit_len;
 
// assuming that packet has some data added already.
pkt.CreateGlobalPacketMap();
ret_value = pkt.GetLengthInBits( bit_len );
 
if( ret_value )
{
    // process error
}
else
    printf( "# of bits used: %d.\n", bit_len );

Implements trek::PacketItem.

◆ GetLengthInBytes()

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

virtual

Gets the length of the packet in bytes.

Calculates the length of the packet in bytes by determining the last byte used by any parameter in the packet. CreateGlobalPacketMap must be called before this method will work. The packet must have a fixed length or it will fail.

Parameters

[out] byte_length The returned byte length.

Returns: SUCCESS; TREK_DATA_FIXED_LENGTH_REQUIRED

Example:

Packet pkt;
int32_t ret_value;
uint32_t byte_len;
 
// assuming that packet has some data added already.
pkt.CreateGlobalPacketMap();
ret_value = pkt.GetLengthInBytes( byte_len );
 
if( ret_value )
{
    // process error
}
else
    printf( "# of bytes used: %d.\n", byte_len );

Implements trek::PacketItem.

◆ GetLengthParameter()

const char * trek::Packet::GetLengthParameter ( )

Returns the name of the parameter that is used for the length of the packet.

A blank name indicates that the length parameter has not been set. If the returned value is not blank, then the length attributes associated with the parameter can be retrieved using GetLengthParameterInfo.

Returns: The name of the length parameter. Blank if not in use

Example:

Packet pkt;     // assuming that packet is set up
 
if( strcmp( pkt.GetLengthParameter(), "" ) )
{
    // call GetLengthParameterInfo for details
}
else
    printf("Blank name...no info to retrieve!\n");

◆ GetLengthParameterInfo()

int32_t trek::Packet::GetLengthParameterInfo	(	packet_zone_type &	zone,
		int32_t &	offset,
		uint32_t &	parent_start_bit
	)

Gets the length parameter's attributes.

Retrieves the zone (header, data, trailer) where it the length parameter can be found, the offset associated with the length, and its parent's start bit. Details about the length parameter can be retrieved with FindParameter.

Note: If there is not a length parameter associated with this packet, the function will return the outermost length associated with any subpackets.

Parameters

[out]	zone	The zone containing the length parameter.
[out]	offset	The offset associated with the length.
[out]	parent_start_bit	The start bit of the parameter's parent.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
packet_zone_type the_zone;
int32_t offset;
uint32_t parent_start_bit
 
ret_value = pkt.GetLengthParameter( zone, offset, parent_start_bit );
 
if( ret_value )
{
    // no length parameter is set
}
else
    printf("Length parameter found and it has an offset of %d\n", offset);

◆ GetMaximumLengthInBits()

uint32_t trek::Packet::GetMaximumLengthInBits ( )

virtual

Returns the maximum length of the packet in bits.

Returns: The maximum length of the packet in bits.

Example:

Packet pkt;
pkt.CreateGlobalPacketMap();
printf("Length in bytes is %u\n", (pkt.GetMaximumLengthInBits()+7)/8 );

Implements trek::PacketItem.

◆ GetParameterList()

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

virtual

Returns a list of all parameters within a packet.

The contents of the StringArray are cleared prior to adding the parameters.

Parameters

[out]	param_list	The names of all parameters in the packet.
[in]	full_name	Specifies if the fully qualified name should be returned (default=true)
[in]	mod_only	Specifies if the returned data should be limited to modifiable parameters.

Note: If full names are not used and there are multiple parameters contained in the packet with the same name, then the returned list will contain duplicate names.

Example:

// Asssuming that the packet is populated.
Packet pkt;
StringArray all_params;
 
pkt.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::Packet::GetSortedParameterList	(	StringArray &	param_list,
		bool	full_name = `true`,
		bool	mod_only = `false`
	)

virtual

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

This method returns all of the short or fully qualified names for the parameters in a packet based on their start location. If a parameter has multiple samples, only the first sample is listed in the StringArray. If no parameters are in the packet the StringArray will be empty. This could occur if CreateGlobalPacketMap has not been called since adding items to the packet. The StringArray is not cleared before adding parameters.

Parameters

[out]	param_list	The fully qualified names of all parameters in the packet.
[in]	full_name	Specifies if the fully qualified name should be returned (default=true)
[in]	mod_only	Specifies if the returned data should be limited to modifiable parameters.

Note: If full names are not used and there are multiple parameters contained in the packet with the same name, then the returned list will contain duplicate names.

Example:

// Asssuming that the packet is populated.
Packet pkt;
StringArray all_params;
 
pkt.GetSortedParameterList( all_params );
 
for( uint32_t ii = 0; ii < all_params.size(); ii++ )
    printf("Full name is %s\n." all_params.GetAt(ii) );

Implements trek::PacketItem.

Examples: extract_packet/extract_packet.cpp.

◆ GetTimeStampParameter()

const char * trek::Packet::GetTimeStampParameter ( )

Returns the name of the parameter that is used for the time stamp of the packet.

A blank name indicates that the time stamp parameter has not been set. If the returned value is not blank, then the time stamp attributes associated with the parameter can be retrieved using GetTimeStampParameterInfo.

Returns: The name of the time stamp parameter. Blank if not in use.

Example:

Packet pkt;     // assuming that packet is set up
 
if( strcmp( pkt.GetTimeStampParameter(), "" ) )
{
    // call GetTimeStampParameterInfo for details.
}
else
    printf("Blank name...no info to retrieve!\n");

◆ GetTimeStampParameterInfo()

int32_t trek::Packet::GetTimeStampParameterInfo	(	packet_zone_type &	zone,
		double &	offset_in_secs,
		uint32_t &	parent_start_bit
	)

Gets the time stamp parameter's attributes.

Retrieves the zone (header, data, trailer) where the time stamp parameter can be found, the offset applied to the time (build only), and its parent's start bit. Details about the time parameter can be retrieved with FindParameter.

Note: Unlike the other packet attributes, the innermost time stamp is returned as this value is best used to determine the time of the source data.

Parameters

[out]	zone	The zone containing the time stamp parameter.
[out]	offset_in_secs	The offset used for the time when building a packet.
[out]	parent_start_bit	The start bit of the parameter's parent.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
packet_zone_type the_zone;
double offset_in_secs;
uint32_t parent_start_bit;
 
ret_value = pkt.GetTimeStampParameterInfo( zone, offset_in_secs, parent_start_bit );
 
if( ret_value )
{
    // no time stamp parameter is set
}
else
    printf("Time stamp parameter found and it has an offset of %lf\n", offset_in_secs);

◆ GetValidationErrors()

const char * trek::Packet::GetValidationErrors ( )

Gets a string of the last validation errors.

Returns: A constant string of validation errors. Example:

Packet pkt;

int32_t num_err;

// assuming that packet has some data added already.

num_err = pkt.Validate();

if( num_err )

{

printf( "%d validation errors found.\n", num_err );

printf( "%s\n", pkt.GetValidationErrors() );

}

else

printf( "Packet is ok to use\n" );

trek::Packet::Validate
int32_t Validate()
Validates that the data contained in the packet is logically correct.
Definition: packet.cpp:903

trek::Packet::GetValidationErrors
const char * GetValidationErrors()
Gets a string of the last validation errors.
Definition: packet.cpp:870

◆ HasChecksumError()

bool trek::Packet::HasChecksumError ( )

Determines if the last packet extraction had a checksum error.

Returns: true If a checksum error was detected.; false If checksum passed or no checksum is defined.

Example:

Packet pkt;
 
pkt.Extract();      // would return an error if checksum failed too.
if( pkt.HasChecksumError() )
{
    // you can still get the data, it may just be bad.
}

◆ HasDataZone()

bool trek::Packet::HasDataZone ( )

Determines if the packet has a data zone.

Returns: true If a packet data is currently set.; false If packet data is currently empty.

Example:

Packet pkt;
 
if( pkt.HasDataZone() )
{
    // not sure if you'll really use this method
}

◆ HasHeaderZone()

bool trek::Packet::HasHeaderZone ( )

Determines if the packet has a header zone.

Returns: true If a packet header is currently set.; false If packet header is currently empty.

Example:

Packet pkt;
 
if( pkt.HasHeaderZone() )
{
    // not sure if you'll really use this method
}

◆ HasLengthError()

bool trek::Packet::HasLengthError ( )

Determines if the last packet extraction had a length error.

Returns: true If a length error was detected.; false If ok.

Example:

Packet pkt;
 
pkt.Extract();      // would return an error if length error occurred too.
if( pkt.HasLengthError() )
{
    // you can still get data, but some may be missing.
}

◆ HasModifiableData()

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

virtual

Determines if the packet has any modifiable data.

Parameters

[in] data_zone_only If true, limits the search to the data zone only.

Returns: false if no parameter is modifiable. otherwise returns true.

Implements trek::PacketItem.

◆ HasTrailerZone()

bool trek::Packet::HasTrailerZone ( )

Determines if the packet has a trailer zone.

Returns: true If a packet trailer is currently set.; false If packet trailer is currently empty.

Example:

Packet pkt;
 
if( pkt.HasTrailerZone() )
{
    // not sure if you'll really use this method
}

◆ HasVariableLengthData()

bool trek::Packet::HasVariableLengthData ( )

virtual

Determines if the Packet has any variable length data.

Returns: true If packet has any variable length data.; false If packet only has fixed length data.

Implements trek::PacketItem.

◆ Init()

void trek::Packet::Init ( )

virtual

Initializes the object.

This method can be called to reinitialize a packet 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.SetAlias( "AliasForFirst" );
p.SetShortDescription( "Some words." );
p.SetLongDescription( "Lots of words.  Ok, maybe not that many." );
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 );
 
pkt.Init();     // removes the Header from the packet and all of it's associated parameters.
 
p.Init();
// etc.

Reimplemented from trek::PacketItem.

◆ IsComplete()

bool trek::Packet::IsComplete ( )

virtual

Determines if the packet definition is considered complete.

Returns: true If all parameters have a value.; false If any parameter does not have a value or none of the header, data, or trailer zones are set.

Example:

// Asssuming that the packet is populated.
Packet pkt;
 
if( pkt.IsComplete() )
{
    // Can Build() packet
}
else
{
    // Build() will fail
}

Implements trek::PacketItem.

◆ IsModifiable()

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

virtual

Determines if any of the data is modifiable.

Packets are considered modifiable if the data zone contains any modifiable data. If the data zone contains nested packets, any parameter in that packet can make the top level packet 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 data zone of the packet are modifiable; false If none of the parameters in the data zone of the packet are modifiable

Implements trek::PacketItem.

◆ LoadFile()

int32_t trek::Packet::LoadFile ( const char * filename )

Loads the Packet definition from the specified file.

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

Parameters

[in] filename The file to load the packet object from.

Returns: SUCCESS; TREK_DATA_NULL_PTR; Other return codes

Example:

Packet pkt;
 
ret_value = pkt.LoadFile( "my_file.xml" );

Examples: build_packet/build_packet.cpp, and extract_packet/extract_packet.cpp.

◆ PrintDefinition()

const char * trek::Packet::PrintDefinition ( bool include_value = false )

Returns a string with basic information about all parameters in the packet.

The returned string contains the short name, fully qualified name, start bit, data type, length, and (optionally) value for each parameter in the packet. The parameters are returned based on the order of the start bit. Only the first sample of a parameter's value is shown.

Returns: formatted string

Example:

// Asssuming that the packet is populated.
Packet pkt;
 
printf( "%s", pkt.PrintDefinition( true ) );    // include values

◆ PrintPacket()

const char * trek::Packet::PrintPacket	(	uint8_t *	pkt_buf,
		uint32_t	pkt_len
	)

This method is used to print all of the headers in the packet and a hexidecimal representation of the packet contents.

This is the method used by the Data GUI to view packets.

Parameters

[in]	pkt_buf	The packet to print
[in]	pkt_len	The length of the packet

Returns: SUCCESS

Example:

// Asssuming that the packet is populated.
Packet pkt;
unsigned char pkt_buf[1000];
uint32_t pkt_len;
 
// This print will extract the data internally
printf( "%s", pkt.PrintPacket( pkt_buf, pkt_len ) );

◆ PrintValues()

const char * trek::Packet::PrintValues ( )

Returns a string with the value of all parameters in the packet.

Returns: SUCCESS

Example:

// Asssuming that the packet is populated.
Packet pkt;
 
printf( "%s", pkt.PrintValues() );

Examples: tlm_api_cpp_next/cpp_next_main.cpp.

◆ RemoveAllIdentifiers()

void trek::Packet::RemoveAllIdentifiers ( )

Removes all identifiers from the packet.

The parameters corresponding to the identifiers are not removed.

Example:

Packet pkt;     // assuming that parameters are already added
 
pkt.RemoveAllIdentifiers();

◆ RemoveData()

void trek::Packet::RemoveData ( )

Removes the data from the packet.

Deletes the current data, if any, from the packet. AddData can be used to add a new data. The global packet map is cleared as part of this method.

Example:

Packet pkt;
 
pkt.RemoveData();

◆ RemoveHeader()

void trek::Packet::RemoveHeader ( )

Removes the header from the packet.

Deletes the current header, if any, from the packet. AddHeader can be used to add a new header. The global packet map is cleared as part of this method.

Example:

Packet pkt;
 
pkt.RemoveHeader();

◆ RemoveIdentifier()

int32_t trek::Packet::RemoveIdentifier ( const char * name )

Removes the specified parameter as an identifier.

The specified parameter is removed as an identifier for this packet. The parameter corresponding to the name is not removed.

Parameters

[in] name The name of the parameter to be removed as an identifier.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

Packet pkt;     // assuming that parameters are already added
 
ret_value = pkt.RemoveIdentifier( "APID" );
 
if( ret_value )
{
    // it wasn't an identifer
}
else
    printf("Success!\n");

◆ RemoveTrailer()

void trek::Packet::RemoveTrailer ( )

Removes the trailer from the packet.

Deletes the current trailer, if any, from the packet. AddTrailer can be used to add a new trailer. The global packet map is cleared as part of this method.

Example:

Packet pkt;
 
pkt.RemoveTrailer();

◆ SaveFile()

int32_t trek::Packet::SaveFile ( const char * filename )

Saves the Packet definition to the specified file.

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

Parameters

[in] filename The file to save the packet object to.

Returns: SUCCESS; TREK_DATA_NULL_PTR; Other return codes

Example:

Packet pkt;
 
ret_value = pkt.SaveFile( "my_file.xml" );

Examples: define_packet/define_packet.cpp.

◆ SetChecksumParameter()

int32_t trek::Packet::SetChecksumParameter	(	const char *	name,
		packet_zone_type	zone,
		packet_checksum_point_type	start_pt,
		int32_t	start_offset,
		packet_checksum_point_type	end_pt,
		int32_t	end_offset,
		packet_checksum_type	type
	)

Sets the checksum parameter for the packet.

The checksum parameter is used when calling Build to calculate a checksum for the packet as it is built.
If the checksum parameter is no longer needed call the ClearChecksumParameter method. The table below shows the data type that is required for each checksum type.

Checksum Type	Data Type Required	Notes
CT_CRC32	32-bit unsigned integer	None
CT_MD5	128-bit (16 bytes) unspecified bytes	None
CT_SUM16	16-bit unsigned integer	The length of the data being used, must be on a 16-bit boundary.

Note: The checksum parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the checksum.
[in]	zone	The zone of the packet where the checksum can be found.
[in]	start_pt	The start point for the checksum. Must be before the end_pt.
[in]	start_offset	The offset from the specified start_pt. Useful if the checksum does not include all of a 'zone'.
[in]	end_pt	The end point for the checksum. Must be after the start_pt.
[in]	end_offset	The offset from the specified end_pt. Useful if the checksum does not include all of a 'zone'.
[in]	type	The type of checksum to be performed. The data type for the parameter must be compatible with the selected type.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// Setting the checksum parameter for an ISS CCSDS command packet...
Packet pkt;
const char *checksum_param_name = "Checksum";
int32_t ret_value;
 
// not checking all the return codes, but you should...
Parameter p;
p.SetName( checksum_param_name );
p.SetDataType( DT_UNSIGNED_INTEGER, 16 );
p.SetStartBit( 0 );
 
ParameterCollection pc;
pc.AddParameter(p);
 
pkt.AddTrailerZone(pc);
 
ret_value = pkt.SetChecksumParameter( checksum_param_name, TRAILER_ZONE, START_HEADER, 0, END_DATA, 0, CT_SUM16 );
 
if( ret_value )
{
    // process errors
}
else
{
    // success
}

Examples: define_packet/define_packet.cpp.

◆ SetCounterParameter()

int32_t trek::Packet::SetCounterParameter	(	const char *	name,
		packet_zone_type	zone,
		uint32_t	start_count = `0`,
		bool	fwd_count = `true`,
		uint32_t	min_count = `0`,
		uint32_t	max_count = `0`,
		uint32_t	reset_count = `0`
	)

Sets the counter parameter for the packet.

The counter parameter is used when calling Build to set a counter for the packet as it is built.
If the counter parameter is no longer needed call the ClearCounterParameter method. If min_count and max_count are both set to 0 (default), the counter will use the full size of the counter based on its length.

Note: The counter parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the counter.
[in]	zone	The zone of the packet where the counter can be found. Typically the header.
[in]	start_count	The start point for the counter. Typically zero.
[in]	fwd_count	If true, counter is incremented for each subsequent packet. If false, counter is decremented.
[in]	min_count	The minimum count value for the parameter.
[in]	max_count	The maximum count value for the parameter. If set to zero, the maximum value allowed by the parameter data type is used.
[in]	reset_count	The value to use when the counter reaches the end point.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_INVALID_LENGTH; TREK_DATA_NULL_PTR

Example:

// Setting the time stamp parameter for an ISS CCSDS packet...
Packet pkt;
char *cntr_param_name = "SeqCnt";
int32_t ret_value;
 
// not checking all the return codes, but you should...
Parameter p;
p.SetName( cntr_param_name );
p.SetDataType( DT_UNSIGNED_INTEGER, 14 );
p.SetStartBit( 18 );
 
ParameterCollection pc;
pc.AddParameter(p);
 
pkt.AddHeader(pc);
 
// defaults are ok for start_count (0), fwd_count (true), min_count (0), 
// max_count (0), and reset_count (0)
ret_value = pkt.SetCounterParameter( cntr_param_name, HEADER_ZONE );
 
if( ret_value )
{
    // process errors
}
else
{
    // success
}

Examples: define_packet/define_packet.cpp.

◆ SetLengthParameter()

int32_t trek::Packet::SetLengthParameter	(	const char *	name,
		packet_zone_type	zone,
		int32_t	offset = `0`
	)

Sets the length parameter for the packet.

The length parameter is used when calling Build to calculate the length of the packet as it is built. This is necessary for variable length packets, but can be omitted for fixed length packets if desired. If the length parameter is no longer needed call the ClearLengthParameter method.

Note: The length parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the length.
[in]	zone	The zone of the packet where the length can be found. Typically the header.
[in]	offset	The offset applied to the value of the length parameter value.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// Setting the length parameter for a CCSDS packet...
Packet pkt;
char *len_param_name = "Length";
int32_t ret_value;
 
// not checking all the return codes, but you should...
Parameter p;
p.SetName( len_param_name );
p.SetDataType( DT_UNSIGNED_INTEGER, 16 );
p.SetStartBit( 32 );
 
ParameterCollection pc;
pc.AddParameter(p);
 
pkt.AddHeader(pc);
 
ret_value = pkt.SetLengthParameter( len_param_name, HEADER_ZONE, 7 );
 
if( ret_value )
{
    // process errors
}
else
{
    // success
}

Examples: define_packet/define_packet.cpp.

◆ SetModifiableFlagForAllParameters()

void trek::Packet::SetModifiableFlagForAllParameters ( bool input )

Sets the modifiable flag for all parameters currently in the packet.

Parameters

[in] input The new flag value.

◆ SetTimeStampOffset()

void trek::Packet::SetTimeStampOffset ( double offset_in_secs )

Sets an offset for the current system time to use when building packets.

The offset can be used to simulate time for periods other than the current time. This value is only used for Build. The offset is not applied when extracting the data.

Parameters

[out] offset_in_secs The offset in seconds.

Example:

// Asssuming that the packet is populated.
Packet pkt;
 
pkt.SetTimeStampOffset( (double)-3600 );    // shift time to one hour earlier than now

◆ SetTimeStampParameter()

int32_t trek::Packet::SetTimeStampParameter	(	const char *	name,
		packet_zone_type	zone,
		double	offset_in_secs = `0`
	)

Sets the time stamp parameter for the packet.

The time stamp parameter is used when calling Build to set the current time for the packet as it is built.
If the time stamp parameter is no longer needed call the ClearTimeStampParameter method.

Note: The time stamp parameter specified cannot be in a nested packet.

Parameters

[in]	name	The name of the parameter to be used for the time stamp.
[in]	zone	The zone of the packet where the time stamp can be found. Typically the header.
[in]	offset_in_secs	The offset applied to the time stamp before inclusion in the packet.

Returns: SUCCESS; TREK_DATA_DOES_NOT_EXIST; TREK_DATA_NULL_PTR

Example:

// Setting the counter parameter for an ISS CCSDS packet...
Packet pkt;
char *time_param_name = "TimeStamp";
int32_t ret_value;
 
// not checking all the return codes, but you should...
Parameter p;
p.SetName( time_param_name );
p.SetDataType( DT_ISS_TIME, 40 );
p.SetStartBit( 48 );
 
ParameterCollection pc;
pc.AddParameter(p);
 
pkt.AddHeader(pc);
 
// default is ok for offset_in_secs (0)
ret_value = pkt.SetTimeStampParameter( time_param_name, HEADER_ZONE );
 
if( ret_value )
{
    // process errors
}
else
{
    // success
}

Examples: define_packet/define_packet.cpp.

◆ UpdateExpectedValue()

int32_t trek::Packet::UpdateExpectedValue	(	const char *	name,
		int32_t	new_value
	)

Updates the expected value for an identifier.

Parameters

[in]	name	The name of the identifier.
[in]	new_value	The value for the identifier.

Returns: SUCCESS; TREK_DATA_NULL_PTR; TREK_DATA_DOES_NOT_EXIST

Example:

Packet pkt;     // assuming that parameters are already added
 
pkt.UpdateExpectedValue( "CCSDS=APID", 12 );

◆ Validate()

int32_t trek::Packet::Validate ( )

virtual

Validates that the data contained in the packet is logically correct.

Checks the data within the packet for errors that could cause the code to crash. Validation is performed as data is populated with information, but it is possbile to bypass some of these checks if the data is read in from a file (LoadFile) or data is deleted.

Note: This method will be updated in later releases to include more validation.

Returns: The number of validation errors found

Example:

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

Reimplemented from trek::PacketItem.

Public Member Functions

Working With the Entire Packet

Detailed Description

Constructor & Destructor Documentation

◆ Packet()

◆ ~Packet()

Member Function Documentation

◆ AddData()

◆ AddHeader()

◆ AddIdentifier() [1/2]

◆ AddIdentifier() [2/2]

◆ AddTrailer()

◆ Build()

◆ ClearAllParameterValues()

◆ ClearGlobalPacketMap()

◆ CreateGlobalPacketMap()

◆ Extract()

◆ FindLastParameter()

◆ FindParameter()

◆ GetChecksumParameter()

◆ GetChecksumParameterInfo()

◆ GetCounterParameter()

◆ GetCounterParameterInfo() [1/2]

◆ GetCounterParameterInfo() [2/2]

◆ GetFullyQualifiedNames()

◆ GetHeaderLengthInBits()

◆ GetHeaderLengthInBytes()

◆ GetIdentifierInfo() [1/3]

◆ GetIdentifierInfo() [2/3]

◆ GetIdentifierInfo() [3/3]

◆ GetIdentifierList()

◆ GetLengthInBits()

◆ GetLengthInBytes()

◆ GetLengthParameter()

◆ GetLengthParameterInfo()

◆ GetMaximumLengthInBits()

◆ GetParameterList()

◆ GetSortedParameterList()

◆ GetTimeStampParameter()

◆ GetTimeStampParameterInfo()

◆ GetValidationErrors()

◆ HasChecksumError()

◆ HasDataZone()

◆ HasHeaderZone()

◆ HasLengthError()

◆ HasModifiableData()

◆ HasTrailerZone()

◆ HasVariableLengthData()

◆ Init()

◆ IsComplete()

◆ IsModifiable()

◆ LoadFile()

◆ PrintDefinition()

◆ PrintPacket()

◆ PrintValues()

◆ RemoveAllIdentifiers()

◆ RemoveData()

◆ RemoveHeader()

◆ RemoveIdentifier()

◆ RemoveTrailer()

◆ SaveFile()

◆ SetChecksumParameter()

◆ SetCounterParameter()

◆ SetLengthParameter()

◆ SetModifiableFlagForAllParameters()

◆ SetTimeStampOffset()

◆ SetTimeStampParameter()

◆ UpdateExpectedValue()

◆ Validate()