|
Tide 0.1.0
|
|
Tide 0.1.0
|
The Element interface, a basic interface to an element object. More...
#include <tide/element.h>
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_ |
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.
| tide::Element::Element | ( | tide::ids::ID | id | ) |
Create a new Element.
| [in] | id | The element's ID, as an unsigned integer up to 28 bits. |
| InvalidEBMLID | if the provided ID is invalid. |
| virtual tide::Element::~Element | ( | ) | [inline, virtual] |
| 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().
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:
IDs are divided into four classes:
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 >.
| 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.
| 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.
| ReadError | if an error occurs reading data. |
| BadBodySize | if the size read from the element's header doesn't match its actual size. Only occurs with master elements. |
| InvalidChildID | if a child element is found in the body of a master element to which it doesn't belong. |
| MissingChild | if a child element that must be present in a master element is not found. |
| ValueOutOfRange | if a child element is read with a value that is out of range. |
| ValueSizeOutOfRange | if 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).
| [in] | input | The input byte stream containing the element's body data. |
| [in] | size | The size of the body data. The stream must not be read beyond this number of bytes. |
| ReadError | if an error occurs reading data. |
| BadBodySize | if the size read from the element's header doesn't match its actual size. Only occurs with master elements. |
| InvalidChildID | if a child element is found in the body of a master element to which it doesn't belong. |
| MissingChild | if a child element that must be present in a master element is not found. |
| ValueOutOfRange | if a child element is read with a value that is out of range. |
| ValueSizeOutOfRange | if 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.
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.
| [in] | output | The destination byte stream to write to. |
| WriteError | if 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.
| WriteError | if 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.
| [in] | output | The destination byte stream to write to. |
| WriteError | if 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.
| WriteError | if an error occurs writing data. |
Reimplemented in tide::Cluster, and tide::Segment.
tide::ids::ID tide::Element::id_ [protected] |
std::streampos tide::Element::offset_ [protected] |
Reimplemented in tide::SeekElement.
1.7.3
