|
Tide 0.1.0
|
|
Tide 0.1.0
|
#include <tide/segment.h>
Public Member Functions | |
| Segment (std::streamsize pad_size=4096) | |
| Create a new segment element. | |
| std::streamsize | pad_size () const |
| Get the padding size. | |
| void | pad_size (std::streamsize pad_size) |
| Set the padding size. | |
| std::streamsize | size () const |
| Get the total size of the element. | |
| std::streamsize | finalise (std::iostream &stream) |
| Finalise writing of the segment. | |
| std::streamsize | to_segment_offset (std::streamsize stream_offset) |
| Calculate an offset within the segment. | |
| std::streamsize | to_stream_offset (std::streamsize seg_offset) |
| Calculate the offset in a stream of a position in the segment. | |
Public Attributes | |
| SeekHead | index |
| The segment index. | |
| SegmentInfo | info |
| The segment information. | |
Protected Member Functions | |
| std::streamsize | body_size () const |
| Get the size of the body of this element. | |
| std::streamsize | write_size (std::ostream &output) |
| Element size writing. | |
| std::streamsize | write_body (std::ostream &output) |
| Element body writing. | |
| std::streamsize | read_body (std::istream &input, std::streamsize size) |
| Element body loading. | |
Protected Attributes | |
| std::streamsize | pad_size_ |
| The size of the padding to place at the start of the file. | |
| std::streamsize | size_ |
| The size of the segment, as read from the file. | |
| bool | writing_ |
| If the segment is currently being written. | |
The Segment element.
A segment makes up the body of a Tide document. It is the only top-level element, excluding the EBMLHeader. All other Tide elements are contained within it. Usually, a Tide document contains a single segment.
The segment contains all the document's blocks (stored in clusters), and all relevant meta-data, such as document information, tags, attachments and cue points.
Because the body of a segment contains data that arrives at differing times, segments cannot be written in a single operation. Instead, a segment is opened for writing by calling write(), which provides it with its target output byte stream. This prepares the byte stream for the segment to be written. Once writing is complete, the segment is finalised by calling finalise(). Finalising a segment completes it, writing such things as the segment's final size into the output stream.
Likewise, segments are not read in a single operation. Trying to do so for any reasonably-sized file would require a significant quantity of memory and be inefficient. Instead, the segment is opened for reading by calling the read() method, which prepares the segment for reading by the meta-seek element (if present) and filling in the index table. The child elements are then read directly from the file as needed. The segment does not need to be closed once reading is complete.
| tide::Segment::Segment | ( | std::streamsize | pad_size = 4096 | ) |
Create a new segment element.
| [in] | pad_size | The size of the padding to place at the start of the segment when opening it for writing. |
| std::streamsize tide::Segment::body_size | ( | ) | const [inline, protected, virtual] |
Get the size of the body of this element.
This function will not return the actual size of the segment until either the segment is read from a Tide document or it is finalised in a Tide document.
Implements tide::Element.
| std::streamsize tide::Segment::finalise | ( | std::iostream & | stream | ) |
Finalise writing of the segment.
Calculates the total size of the segment and writes it into the segment header, followed by writing in the SeekHead element as the first child of the Segment, thus finalising the segment.
The write pointer in stream must be positioned at the first byte after the last byte of the segment before this method is called.
| [in] | stream | The byte stream to write the segment to. |
| NotWriting | if the segment has not yet been opened for writing by calling write(). |
| std::streamsize tide::Segment::pad_size | ( | ) | const [inline] |
Get the padding size.
When the segment is opened for writing, it places a certain quantity of padding at the start of the segment using a Void element. This padding is over-written during finalisation with the SeekHead and SegmentInfo elements. The length of the padding is controlled by this property. Setting it to a value that is too small for one or both of the SeekHead and SegmentInfo elements will result in those that don't fit being written at the end of the segment. In the case of the SeekHead, this can significantly degrade start-up performance when reading the segment.
| void tide::Segment::pad_size | ( | std::streamsize | pad_size | ) | [inline] |
| std::streamsize tide::Segment::read_body | ( | std::istream & | input, |
| std::streamsize | size | ||
| ) | [protected, virtual] |
Element body loading.
This function does not actually read the body of the segment. Instead, it reads some of the level 1 elements and validates that the segment is usable:
When this function returns, the stream's read pointer will be placed at the end of the SegmentInformation element, unless the SeekHead element occurs after it, in which case it will be placed at the end of the SeekHead element.
| MultipleSeekHeads | if the segment has more than one index. |
| NoSegmentInfo | if the SegmentInfo element is not found. |
| NoTracks | if the Tracks element is not found. |
| NoClusters | if at least one Cluster element is not found. |
Implements tide::Element.
| std::streamsize tide::Segment::size | ( | ) | const [virtual] |
Get the total size of the element.
Reimplemented from tide::Element.
| std::streamsize tide::Segment::to_segment_offset | ( | std::streamsize | stream_offset | ) |
Calculate an offset within the segment.
This function turns an offset in the output stream into an offset in this segment, which is necessary for the index.
| std::streamsize tide::Segment::to_stream_offset | ( | std::streamsize | seg_offset | ) |
Calculate the offset in a stream of a position in the segment.
This function turns an offset within the segment into an absolute position in a byte stream.
| std::streamsize tide::Segment::write_body | ( | std::ostream & | output | ) | [protected, virtual] |
Element body writing.
This function, which opens up a segment for writing, does not actually write any final content. Instead, it preserves a chunk of space at the beginning of the file using a Void element for the SeekHead and SegmentInfo elements to be written into by finalise().
The size of space reserved is controlled by pad_size().
Implements tide::Element.
| std::streamsize tide::Segment::write_size | ( | std::ostream & | output | ) | [protected, virtual] |
Element size writing.
Reimplemented from tide::Element.
The segment index.
All known level 1 elements are included in this index. It is a mapping from element ID (the key) to position, in bytes, in the segment (the value). The first level 1 element has a position of 0. An ID may occur multiple times.
There may be additional level 1 elements that are not mentioned in this index. Typically, all but the first cluster are not found in the index.
std::streamsize tide::Segment::pad_size_ [protected] |
std::streamsize tide::Segment::size_ [protected] |
bool tide::Segment::writing_ [protected] |
1.7.3
