A JP2_Box contains JP2 file format box data. More...

#include <JP2_Box.hh>

Collaboration diagram for JP2_Box:

Public Types
typedef std::vector< JP2_Box * >	JP2_Box_List
	List of JP2 boxes. More...

Public Member Functions
	JP2_Box ()
	Construct a JP2_Box with no data content. More...

	JP2_Box (unsigned int box_type, const unsigned char *data=NULL, unsigned int amount=0)
	Construct a JP2_Box of some type and with optional data content. More...

	JP2_Box (unsigned int box_type, const std::string &text)
	Construct a JP2_Box of some type with text content. More...

virtual	~JP2_Box ()
	Destroy this JP2_Box. More...

std::string	type_name () const
	Get the type name of the box. More...

JP2_Box &	type_name (const std::string &name)
	Set the type name of the box. More...

unsigned int	type_code () const
	Get the type code of the box. More...

JP2_Box &	type_code (unsigned int box_type)
	Set the type code of the box. More...

unsigned int	content_amount () const
	Get the box data content amount. More...

unsigned char *	content () const
	Get the box data content. More...

JP2_Box &	content (const unsigned char *data, unsigned int amount=0)
	Set the box data content. More...

JP2_Box &	content (const std::string &text)
	Set the box data content. More...

bool	locally_owned_content () const
	Test if the box data content buffer is locally owned. More...

JP2_Box &	attach_content (unsigned char *data, unsigned int amount=0)
	Set the box data content. More...

JP2_Box &	append_content (const unsigned char *data, unsigned int amount)
	Append data to the box data content. More...

JP2_Box &	append_content (const std::string &text)
	Append text to the box data content. More...

JP2_Box &	add (JP2_Box *sub_box)
	Add a sub-box to this box. More...

JP2_Box &	add (JP2_Box &sub_box)
	Add a sub-box to this box. More...

bool	remove (JP2_Box *sub_box)
	Remove a sub-box from this box. More...

JP2_Box_List &	sub_boxes ()
	Get the list of sub-boxes contained in this box. More...

JP2_Box *	container () const
	Get the container of this box. More...

Static Public Member Functions
static std::string	type_name (unsigned int box_type)
	Convert a JP2 box type code to a string. More...

static unsigned int	type_code (const std::string &name)
	Convert a JP2 box type string to an integer code. More...

Static Public Attributes
static const char *const	ID
	Class identification name with source code version and date. More...

static const unsigned int	UUID_BOX_TYPE = 0x75756964
	UUID box type. More...

static const unsigned int	UUID_SIZE = 16
	Size of the UUID data content. More...

static const unsigned int	UUID_INFO_BOX_TYPE = 0x75696E66
	UUID Info box type. More...

static const unsigned int	UUID_LIST_BOX_TYPE = 0x756C7374
	UUID List box type. More...

static const unsigned int	URL_BOX_TYPE = 0x75726C20
	URL box type. More...

static const unsigned int	XML_BOX_TYPE = 0x786D6C20
	XML box type. More...

static const unsigned int	ASSOCIATION_BOX_TYPE = 0X61736F63
	Association box type. More...

static const unsigned int	LABEL_BOX_TYPE = 0X6C626C20
	Label box type. More...

static const unsigned int	INTELLECTUAL_PROPERTY_BOX_TYPE = 0x6A703269
	Intellectual Property box type. More...

Protected Attributes
unsigned int	Type
	The JP2 box type code. More...

unsigned char *	Content
	The data content buffer. More...

unsigned int	Content_Amount
	The amount (bytes) of content data. More...

bool	Locally_Owned_Content
	Flag for a locally owned data content buffer. More...

JP2_Box *	Container
	Pointer to the JP2_Box that contains this box. More...

JP2_Box_List	Sub_Boxes
	List of boxes contained in this box. More...

Detailed Description

A JP2_Box contains JP2 file format box data.

Author: Bradford Castalia; UA/HiROC

Version: 1.4

Member Typedef Documentation

◆ JP2_Box_List

typedef std::vector<JP2_Box*> JP2_Box_List

List of JP2 boxes.

Constructor & Destructor Documentation

◆ JP2_Box() [1/3]

JP2_Box ( )

Construct a JP2_Box with no data content.

Construct JP2_Box with no content.

◆ JP2_Box() [2/3]

JP2_Box	(	unsigned int	box_type,
		const unsigned char *	data = `NULL`,
		unsigned int	amount = `0`
	)

explicit

Construct a JP2_Box of some type and with optional data content.

Parameters

box_type	The 32-bit integer box type code value.
amount	The number of data content bytes. If zero the box will be emptied and the data will be ignored.
data	A pointer (const unsigned char) to the data content. N.B.: The data will be copied to a {locally owned data} buffer. If NULL the box will be emptied and the amount will be ignored. invalid_argument If a type code byte value does not correspond to a printable character (<32 or >126). length_error If insufficient memory is available to allocate the data content buffer. content(unsigned int, const unsigned char)

References box_name(), box_type(), JP2_Box::content(), and JP2_Box::type_code().

◆ JP2_Box() [3/3]

JP2_Box	(	unsigned int	box_type,
		const std::string &	text
	)

explicit

Construct a JP2_Box of some type with text content.

Parameters

box_type	The 32-bit integer box type code value.
text	The text string to be set as the box content.

See also: content(const std::string&)

References box_name(), box_type(), JP2_Box::content(), and JP2_Box::type_code().

◆ ~JP2_Box()

~JP2_Box ( )

virtual

Destroy this JP2_Box.

Any locally owned content data is freed.

References JP2_Box::Content, JP2_Box::Locally_Owned_Content, and JP2_Box::Sub_Boxes.

Member Function Documentation

◆ type_name() [1/3]

std::string type_name ( ) const

inline

Get the type name of the box.

The type name is the string representation of the type code bytes that are stored as the second value of each JP2 box.

Returns: The type name of the box. This will be the empty string if the box is undefined.

Exceptions

invalid_argument If the type code is an invalid value.

See also: type_name(unsigned int)

References JP2_Box::Type.

Referenced by JP2_Box::add(), JP2_Box::append_content(), and JP2_Box::type_code().

◆ type_name() [2/3]

JP2_Box & type_name ( const std::string & name )

Set the type name of the box.

Parameters

name	The type name to be applied to the JP2 box.

Returns: This JP2_Box.

Exceptions

invalid_argument If the string does not contain exactly four characters or any character is not printable (<32 or >126).

See also: type_code(const std::string&)

References JP2_Box::Type, and JP2_Box::type_code().

◆ type_code() [1/3]

unsigned int type_code ( ) const

inline

Get the type code of the box.

The type code is the second value of each JP2 box.

Returns: The JP2 box type code value. This will be zero if the box is undefined.

References JP2_Box::Type.

Referenced by JP2_Box::JP2_Box(), JP2_Box::type_name(), and JP2_Encoder::write_user_boxes().

◆ type_code() [2/3]

JP2_Box & type_code ( unsigned int box_type )

Set the type code of the box.

Parameters

box_type The 32-bit integer box type code value.

Returns: This JP2_Box.

Exceptions

invalid_argument If a type code byte value does not correspond to a printable character (<32 or >126).

References box_type(), JP2_Box::Type, and JP2_Box::type_name().

◆ content_amount()

unsigned int content_amount ( ) const

inline

Get the box data content amount.

The box data content amount is the size of the content buffer, in bytes.

Returns: The size of the box data content data buffer, in bytes. This will be zero if the box has no data content.

References JP2_Box::Content_Amount.

◆ content() [1/3]

unsigned char* content ( ) const

inline

Get the box data content.

Returns: A pointer to the box data content as an unsigned char*. Caution: The box data content is not copied.

References JP2_Box::Content.

Referenced by JP2_Box::append_content(), JP2_Box::content(), and JP2_Box::JP2_Box().

◆ content() [2/3]

JP2_Box & content	(	const unsigned char *	data,
		unsigned int	amount = `0`
	)

Set the box data content.

Any current content is replaced.

Parameters

data A pointer (const unsigned char*) to the data content. N.B.: The data will be copied to a {locally owned content} buffer. If NULL the box will be emptied and the amount will be ignored. amount The number of data bytes. If zero the box will be emptied and the data will be ignored. This JP2_Box. length_error If insufficient memory is available to allocate the data content buffer. attach_content(unsigned int, unsigned char*)

References JP2_Box::Content, JP2_Box::Content_Amount, JP2_Box::ID, and JP2_Box::Locally_Owned_Content.

◆ content() [3/3]

JP2_Box & content ( const std::string & text )

Set the box data content.

Any current content is replaced.

The characters of the string, plus a terminating zero-value character, are copied into the box content.

Parameters

text	The text string to be set as the box content.

Returns: This JP2_Box.

Exceptions

length_error If insufficient memory is available to allocate the data content buffer.

See also: content(unsigned int, const unsigned char*)

References JP2_Box::content().

◆ locally_owned_content()

bool locally_owned_content ( ) const

inline

Test if the box data content buffer is locally owned.

A locally owned data content buffer has been allocated by the JP2_Box and will be deleted when the JP2_Box is destroyed. If the data content buffer was attached to the JP2_Box it is externally owned and will not be deleted when the JP2_Box is destroyed; in this case it is the responsibility of the data buffer owner to ensure that the buffer remains valid until the JP2_Box will no longer be used.

N.B.: Data content that is not locally owned will not be freed when the JP2_Box is destroyed.

Returns: true if the data content buffer is locally owned, false otherwise.

References JP2_Box::Locally_Owned_Content.

◆ attach_content()

JP2_Box & attach_content	(	unsigned char *	data,
		unsigned int	amount = `0`
	)

Set the box data content.

Any current content is replaced.

Parameters

data	A pointer (const unsigned char) to the data content. N.B.*: The data data will not be copied. If NULL the box will be emptied and the amount will be ignored.
amount	The number of data bytes. If zero the box will be emptied and the data will be ignored.

Returns: This JP2_Box.

See also: content(unsigned int, const unsigned char*)

References JP2_Box::Content, JP2_Box::Content_Amount, and JP2_Box::Locally_Owned_Content.

◆ append_content() [1/2]

JP2_Box & append_content	(	const unsigned char *	data,
		unsigned int	amount
	)

Append data to the box data content.

N.B.: Data can only be appended to locally owned content.

A new data content buffer is provided that is the size of the current content amount plus the amount of new data. The current content and new data are copied into the new buffer. The previous buffer is deleted, the new buffer becomes the current content and content amount is updated.

Parameters

amount	The number of data bytes. If zero nothing is done.
data	A pointer (const unsigned char*) to the additional data content. If NULL nothing is done.

Returns: This JP2_Box.

Exceptions

logic_error	If there is a non-zero amount of content that is not locally owned.
length_error	If insufficient memory is available to allocate the data content buffer.

References box_type(), JP2_Box::content(), JP2_Box::Content, JP2_Box::Content_Amount, JP2_Box::ID, JP2_Box::Locally_Owned_Content, and JP2_Box::type_name().

Referenced by JP2_Box::append_content(), and PDS_Projection_Data::JP2_GeoTIFF().

◆ append_content() [2/2]

JP2_Box & append_content ( const std::string & text )

Append text to the box data content.

N.B.: Data can only be appended to locally owned content.

The characters of the text string, plus a terminating null character, are appended to the current box content.

Parameters

text	The text string to be appended to the box content.

Returns: This JP2_Box.

References JP2_Box::append_content().

◆ add() [1/2]

JP2_Box & add ( JP2_Box * sub_box )

Add a sub-box to this box.

If the sub-box is contained in another box it is {remove}d from its container() container}. The sub-box is added to the end of the list of sub_boxes() sub-boxes} and its container() container} is set to this JP2_Box. sub_box A pointer to the JP2_Box that is to be added to this box. If NULL nothing is done. This JP2_Box. invalid_argument If the sub-box is this JP2_Box. remove(JP2_Box*)

References box_name(), JP2_Box::Container, JP2_Box::ID, JP2_Box::remove(), JP2_Box::Sub_Boxes, JP2_Box::Type, and JP2_Box::type_name().

Referenced by JP2_Box::add(), and PDS_Projection_Data::JP2_GML().

◆ add() [2/2]

JP2_Box& add ( JP2_Box & sub_box )

inline

Add a sub-box to this box.

Parameters

sub_box A pointer to the JP2_Box that is to be added to this box. If NULL nothing is done.

Returns: This JP2_Box.

Exceptions

invalid_argument If the sub-box is this JP2_Box.

See also: add(JP2_Box*)

References JP2_Box::add().

◆ remove()

bool remove ( JP2_Box * sub_box )

Remove a sub-box from this box.

If the sub-box is found in the list of sub-boxes it is removed from the list and its container is set to NULL.

Parameters

sub_box A pointer to the JP2_Box that is to be removed from this box. A NULL argument is allowed and will be used to remove a NULL entry if one is present, however this should not occur if the add method is always used to add sub-boxes to the box.

Returns: true if the sub-box was removed, or false if the sub-box was not found in this box.

See also: add(JP2_Box*)

References JP2_Box::Container, and JP2_Box::Sub_Boxes.

Referenced by JP2_Box::add().

◆ sub_boxes()

JP2_Box_List& sub_boxes ( )

inline

Get the list of sub-boxes contained in this box.

Caution: The JP2_Box_List is a vector of JP2_Box pointers which can be manipulated (re-ordered, etc.) as desired, however adding and removing entries should only be done with the add and remove methods to maintain the correct container relationships.

Returns: A reference to the JP2_Box_List for this box.

References JP2_Box::Sub_Boxes.

◆ container()

JP2_Box* container ( ) const

inline

Get the container of this box.

Returns: A pointer to the JP2_Box that has this box in its list of sub-boxes. This will be NULL if this box is not contained in another box.

References JP2_Box::Container.

◆ type_name() [3/3]

std::string type_name ( unsigned int box_type )

static

Convert a JP2 box type code to a string.

Each byte, starting with the most significant byte, of the type value is appended as a character to a string.

Parameters

box_type The box type code value to be converted.

Returns: The string repesentation of the type value.

Exceptions

invalid_argument If a type code byte value does not correspond to a printable character (<32 or >126).

See also: type_code(const std::string)

References box_type(), and JP2_Box::ID.

◆ type_code() [3/3]

unsigned int type_code ( const std::string & name )

static

Convert a JP2 box type string to an integer code.

Each character of the string is placed as a byte value in the corresponding location of the type code, starting with the most significant byte.

Parameters

name	The type name string to be converted.

Returns: The integer type code value.

Exceptions

invalid_argument If the string does not contain exactly four characters or any character is not printable (<32 or >126).

See also: type_name(unsigned int)

References JP2_Box::ID.

Member Data Documentation

◆ ID

const char *const ID

static

Initial value:

=

"UA::HiRISE::JP2_Box (1.6 2010/11/24 03:32:14)"

Class identification name with source code version and date.

Referenced by JP2_Box::add(), JP2_Box::append_content(), JP2_Box::content(), JP2_Box::type_code(), and JP2_Box::type_name().

◆ UUID_BOX_TYPE

const unsigned int UUID_BOX_TYPE = 0x75756964

static

UUID box type.

Referenced by PDS_Projection_Data::JP2_GeoTIFF().

◆ UUID_SIZE

const unsigned int UUID_SIZE = 16

static

Size of the UUID data content.

◆ UUID_INFO_BOX_TYPE

const unsigned int UUID_INFO_BOX_TYPE = 0x75696E66

static

UUID Info box type.

◆ UUID_LIST_BOX_TYPE

const unsigned int UUID_LIST_BOX_TYPE = 0x756C7374

static

UUID List box type.

◆ URL_BOX_TYPE

const unsigned int URL_BOX_TYPE = 0x75726C20

static

URL box type.

◆ XML_BOX_TYPE

const unsigned int XML_BOX_TYPE = 0x786D6C20

static

XML box type.

Referenced by PDS_Projection_Data::JP2_GML().

◆ ASSOCIATION_BOX_TYPE

const unsigned int ASSOCIATION_BOX_TYPE = 0X61736F63

static

Association box type.

Referenced by PDS_Projection_Data::JP2_GML().

◆ LABEL_BOX_TYPE

const unsigned int LABEL_BOX_TYPE = 0X6C626C20

static

Label box type.

Referenced by PDS_Projection_Data::JP2_GML().

◆ INTELLECTUAL_PROPERTY_BOX_TYPE

const unsigned int INTELLECTUAL_PROPERTY_BOX_TYPE = 0x6A703269

static

Intellectual Property box type.

◆ Type

unsigned int Type

protected

The JP2 box type code.

Referenced by JP2_Box::add(), JP2_Box::type_code(), and JP2_Box::type_name().

◆ Content

unsigned char* Content

protected

The data content buffer.

Referenced by JP2_Box::append_content(), JP2_Box::attach_content(), JP2_Box::content(), and JP2_Box::~JP2_Box().

◆ Content_Amount

unsigned int Content_Amount

protected

The amount (bytes) of content data.

Referenced by JP2_Box::append_content(), JP2_Box::attach_content(), JP2_Box::content(), and JP2_Box::content_amount().

◆ Locally_Owned_Content

bool Locally_Owned_Content

protected

Flag for a locally owned data content buffer.

Referenced by JP2_Box::append_content(), JP2_Box::attach_content(), JP2_Box::content(), JP2_Box::locally_owned_content(), and JP2_Box::~JP2_Box().

◆ Container

JP2_Box* Container

protected

Pointer to the JP2_Box that contains this box.

Referenced by JP2_Box::add(), JP2_Box::container(), and JP2_Box::remove().

◆ Sub_Boxes

JP2_Box_List Sub_Boxes

protected

List of boxes contained in this box.

Referenced by JP2_Box::add(), JP2_Box::remove(), JP2_Box::sub_boxes(), and JP2_Box::~JP2_Box().

The documentation for this class was generated from the following files:

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ JP2_Box_List

Constructor & Destructor Documentation

◆ JP2_Box() [1/3]

◆ JP2_Box() [2/3]

◆ JP2_Box() [3/3]

◆ ~JP2_Box()

Member Function Documentation

◆ type_name() [1/3]

◆ type_name() [2/3]

◆ type_code() [1/3]

◆ type_code() [2/3]

◆ content_amount()

◆ content() [1/3]

◆ content() [2/3]

◆ content() [3/3]

◆ locally_owned_content()

◆ attach_content()

◆ append_content() [1/2]

◆ append_content() [2/2]

◆ add() [1/2]

◆ add() [2/2]

◆ remove()

◆ sub_boxes()

◆ container()

◆ type_name() [3/3]

◆ type_code() [3/3]

Member Data Documentation

◆ ID

◆ UUID_BOX_TYPE

◆ UUID_SIZE

◆ UUID_INFO_BOX_TYPE

◆ UUID_LIST_BOX_TYPE

◆ URL_BOX_TYPE

◆ XML_BOX_TYPE

◆ ASSOCIATION_BOX_TYPE

◆ LABEL_BOX_TYPE

◆ INTELLECTUAL_PROPERTY_BOX_TYPE

◆ Type

◆ Content

◆ Content_Amount

◆ Locally_Owned_Content

◆ Container

◆ Sub_Boxes