Tide 0.1.0
Public Member Functions | Protected Member Functions | Protected Attributes

tide::Element Class Reference

The Element interface, a basic interface to an element object. More...

#include <tide/element.h>

Inheritance diagram for tide::Element:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 Element (tide::ids::ID id)
 Create a new Element.
virtual ~Element ()
 Destructor.
uint32_t id () const
 Get the element's ID.
std::streampos offset () const
 Get the element's offset in the byte stream.
virtual std::streamsize size () const
 Get the total size of the element.
virtual std::streamsize write (std::ostream &output)
 Element writing.
virtual std::streamsize read (std::istream &input)
 Element reading.

Protected Member Functions

virtual std::streamsize body_size () const =0
 Get the size of the body of this element.
std::streamsize write_id (std::ostream &output)
 Element ID writing.
virtual std::streamsize write_size (std::ostream &output)
 Element size writing.
virtual std::streamsize write_body (std::ostream &output)=0
 Element body writing.
virtual std::streamsize read_body (std::istream &input, std::streamsize size)=0
 Element body reading implementation.

Protected Attributes

tide::ids::ID id_
std::streampos offset_

Detailed Description

The Element interface, a basic interface to an element object.

Tide objects store their data in elements. Like in XML, the elements form a tree of information. Each element contains a single value and zero or more sub-elements. Each element has a unique ID within the format.

This interface provides the most basic element facilities. It provides the element's ID and an abstract interface to read and write elements to a byte stream.

Definition at line 55 of file element.h.


Constructor & Destructor Documentation

tide::Element::Element ( tide::ids::ID  id)

Create a new Element.

Parameters:
[in]idThe element's ID, as an unsigned integer up to 28 bits.
Exceptions:
InvalidEBMLIDif the provided ID is invalid.
virtual tide::Element::~Element ( ) [inline, virtual]

Destructor.

Definition at line 67 of file element.h.


Member Function Documentation

virtual std::streamsize tide::Element::body_size ( ) const [protected, pure virtual]

Get the size of the body of this element.

Returns the size, in bytes, required to store this element's body. This does not include the space required by the ID or the data size value.

See also size().

Returns:
The size of the element's body, in bytes.

Implemented in tide::BinaryElement, tide::BlockAdditions, tide::BlockGroup, tide::Cluster, tide::DateElement, tide::EBMLElement, tide::FloatElement, tide::IntElement, tide::SeekHead, tide::SeekElement, tide::Segment, tide::SegmentInfo, tide::StringElement, tide::TrackEntry, tide::TrackJoinBlocks, tide::Tracks, and tide::UIntElement.

uint32_t tide::Element::id ( ) const [inline]

Get the element's ID.

The element's ID is an unsigned integer with a maximum size of 28 bits. Some IDs are invalid:

  • 0
  • 0xFF
  • 0xFFFF
  • 0xFFFFFF
  • 0xFFFFFFFF
  • 0x100000000 or greater

IDs are divided into four classes:

  • Class A (0 to 2^7 - 1)
  • Class B (2^7 to 2^14 - 1)
  • Class C (2^14 to 2^21 - 1)
  • Class D (2^21 to 2^28 - 1)

In some storage types, such as EBML file storage, the higher classes use more storage space and so are more likely to be unique within the file. This allows them to be used for synchronisation in the event of file corruption. To take advantage of this, you should use higher IDs for elements that occur less frequently, such as the top-level elements.

Reimplemented in tide::PrimitiveElement< T >, tide::PrimitiveElement< std::vector< char > >, tide::PrimitiveElement< int64_t >, tide::PrimitiveElement< double >, tide::PrimitiveElement< std::string >, and tide::PrimitiveElement< uint64_t >.

Definition at line 93 of file element.h.

std::streampos tide::Element::offset ( ) const [inline]

Get the element's offset in the byte stream.

If the element has been written, or was read from a byte stream, this value will contain its position in that stream. It is updated every time the element is read or written, so reading from one offset and then writing to another will change the stored offset.

If the offset is std::numeric_limits<std::streampos>::max(), then the element has not yet been read or written.

Reimplemented in tide::SeekElement.

Definition at line 106 of file element.h.

virtual std::streamsize tide::Element::read ( std::istream &  input) [virtual]

Element reading.

Reads the element from a byte stream providing a std::istream interface.

This method assumes that the Element ID has already been read (and thus used to construct the Element instance doing the reading), which means that the file's read pointer should be positioned at the first byte of the element's size.

Returns:
The number of bytes read.
Exceptions:
ReadErrorif an error occurs reading data.
BadBodySizeif the size read from the element's header doesn't match its actual size. Only occurs with master elements.
InvalidChildIDif a child element is found in the body of a master element to which it doesn't belong.
MissingChildif a child element that must be present in a master element is not found.
ValueOutOfRangeif a child element is read with a value that is out of range.
ValueSizeOutOfRangeif a child element is read with a size that is not in the allowable range of sizes.

Reimplemented in tide::Cluster, and tide::VoidElement.

virtual std::streamsize tide::Element::read_body ( std::istream &  input,
std::streamsize  size 
) [protected, pure virtual]

Element body reading implementation.

Implementations of the Element interface should implement this function to read the body of the element. When this function is called, the read pointer in the byte stream will be positioned at the first byte of the element's body (i.e. immediately after the element's size value).

Parameters:
[in]inputThe input byte stream containing the element's body data.
[in]sizeThe size of the body data. The stream must not be read beyond this number of bytes.
Returns:
The number of bytes read.
Exceptions:
ReadErrorif an error occurs reading data.
BadBodySizeif the size read from the element's header doesn't match its actual size. Only occurs with master elements.
InvalidChildIDif a child element is found in the body of a master element to which it doesn't belong.
MissingChildif a child element that must be present in a master element is not found.
ValueOutOfRangeif a child element is read with a value that is out of range.
ValueSizeOutOfRangeif a child element is read with a size that is not in the allowable range of sizes.

Implemented in tide::BinaryElement, tide::BlockAdditions, tide::BlockGroup, tide::Cluster, tide::DateElement, tide::EBMLElement, tide::FloatElement, tide::IntElement, tide::SeekHead, tide::SeekElement, tide::Segment, tide::SegmentInfo, tide::StringElement, tide::TrackEntry, tide::TrackJoinBlocks, tide::Tracks, and tide::UIntElement.

virtual std::streamsize tide::Element::size ( ) const [virtual]

Get the total size of the element.

Returns the size, in bytes, required to store this entire element, including its ID, data size value and body.

Returns:
The size of the entire element, in bytes.

Reimplemented in tide::Cluster, tide::Segment, and tide::VoidElement.

virtual std::streamsize tide::Element::write ( std::ostream &  output) [virtual]

Element writing.

Writes the entire element, including its ID, body size and body data, to a byte stream providing a std::ostream interface.

Parameters:
[in]outputThe destination byte stream to write to.
Returns:
The number of bytes written.
Exceptions:
WriteErrorif an error occurs writing data.

Reimplemented in tide::VoidElement.

virtual std::streamsize tide::Element::write_body ( std::ostream &  output) [protected, pure virtual]

Element body writing.

Writes the element's body to a byte stream providing a std::ostream interface.

Returns:
The number of bytes written.
Exceptions:
WriteErrorif an error occurs writing data.

Implemented in tide::BinaryElement, tide::BlockAdditions, tide::BlockGroup, tide::Cluster, tide::DateElement, tide::EBMLElement, tide::FloatElement, tide::IntElement, tide::SeekHead, tide::SeekElement, tide::Segment, tide::SegmentInfo, tide::StringElement, tide::TrackEntry, tide::TrackJoinBlocks, tide::Tracks, tide::UIntElement, and tide::VoidElement.

std::streamsize tide::Element::write_id ( std::ostream &  output) [protected]

Element ID writing.

Writes the element's EBML ID to a byte stream providing a std::ostream interface. Up to 4 bytes may be written.

Parameters:
[in]outputThe destination byte stream to write to.
Returns:
The number of bytes written.
Exceptions:
WriteErrorif an error occurs writing data.
virtual std::streamsize tide::Element::write_size ( std::ostream &  output) [protected, virtual]

Element size writing.

Writes the element's size to a byte stream providing a std::ostream interface.

Returns:
The number of bytes written.
Exceptions:
WriteErrorif an error occurs writing data.

Reimplemented in tide::Cluster, and tide::Segment.


Member Data Documentation

Definition at line 155 of file element.h.

std::streampos tide::Element::offset_ [protected]

Reimplemented in tide::SeekElement.

Definition at line 156 of file element.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines