Tawara  0.1.0
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
tawara::Element Class Referenceabstract

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

#include <tawara/element.h>

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

Public Member Functions

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

Protected Member Functions

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

Protected Attributes

tawara::ids::ID id_
 
std::streampos offset_
 

Detailed Description

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

Tawara 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 66 of file element.h.

Constructor & Destructor Documentation

tawara::Element::Element ( tawara::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 tawara::Element::~Element ( )
inlinevirtual

Destructor.

Definition at line 78 of file element.h.

Member Function Documentation

virtual std::streamsize tawara::Element::body_size ( ) const
protectedpure 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 tawara::Segment, tawara::Cues, tawara::TrackEntry, tawara::BlockGroup, tawara::Attachments, tawara::CuePoint, tawara::Cluster, tawara::SegmentInfo, tawara::Tracks, tawara::SeekHead, tawara::BlockAdditions, tawara::EBMLElement, tawara::AttachedFile, tawara::TrackJoinBlocks, tawara::CueTrackPosition, tawara::FloatElement, tawara::StringElement, tawara::SeekElement, tawara::DateElement, tawara::IntElement, tawara::UIntElement, and tawara::BinaryElement.

uint32_t tawara::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.

Definition at line 104 of file element.h.

std::streampos tawara::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.

Definition at line 117 of file element.h.

virtual std::streamsize tawara::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 tawara::Cluster, and tawara::VoidElement.

virtual std::streamsize tawara::Element::read_body ( std::istream &  input,
std::streamsize  size 
)
protectedpure 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 tawara::Segment, tawara::Cues, tawara::TrackEntry, tawara::BlockGroup, tawara::CuePoint, tawara::Attachments, tawara::Cluster, tawara::SegmentInfo, tawara::Tracks, tawara::SeekHead, tawara::BlockAdditions, tawara::EBMLElement, tawara::AttachedFile, tawara::TrackJoinBlocks, tawara::CueTrackPosition, tawara::FloatElement, tawara::StringElement, tawara::SeekElement, tawara::DateElement, tawara::IntElement, tawara::UIntElement, and tawara::BinaryElement.

virtual std::streamsize tawara::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 tawara::Segment, tawara::Cluster, and tawara::VoidElement.

virtual std::streamsize tawara::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 tawara::FileCluster, and tawara::VoidElement.

virtual std::streamsize tawara::Element::write_body ( std::ostream &  output)
protectedpure virtual
std::streamsize tawara::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 tawara::Element::write_size ( std::ostream &  output)
protectedvirtual

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 tawara::Segment, and tawara::Cluster.

Member Data Documentation

tawara::ids::ID tawara::Element::id_
protected

Definition at line 166 of file element.h.

std::streampos tawara::Element::offset_
protected

Definition at line 167 of file element.h.


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