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.
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_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] | 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. |
- Returns
- The number of bytes read.
- Exceptions
-
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 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.