Tag Parser
10.0.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
|
The OggIterator class helps iterating through all segments of an OGG bitstream. More...
#include <oggiterator.h>
Public Member Functions | |
OggIterator (std::istream &stream, std::uint64_t startOffset, std::uint64_t streamSize) | |
Constructs a new iterator for the specified stream of streamSize bytes at the specified startOffset. More... | |
void | clear (std::istream &stream, std::uint64_t startOffset, std::uint64_t streamSize) |
Sets the stream and related parameters and clears all available pages. More... | |
std::istream & | stream () |
Returns the stream. More... | |
void | setStream (std::istream &stream) |
Sets the stream. More... | |
std::uint64_t | startOffset () const |
Returns the start offset (which has been specified when constructing the iterator). More... | |
std::uint64_t | streamSize () const |
Returns the stream size (which has been specified when constructing the iterator). More... | |
void | reset () |
Resets the iterator to point at the first segment of the first page (matching the filter if set). More... | |
void | nextPage () |
Increases the current position by one page. More... | |
void | nextSegment () |
Increases the current position by one segment. More... | |
void | previousPage () |
Decreases the current position by one page. More... | |
void | previousSegment () |
Decreases the current position by one segment. More... | |
const std::vector< OggPage > & | pages () const |
Returns a vector of containing the OGG pages that have been fetched yet. More... | |
const OggPage & | currentPage () const |
Returns the current OGG page. More... | |
std::uint64_t | currentPageOffset () const |
Returns the start offset of the current OGG page. More... | |
std::vector< OggPage >::size_type | currentPageIndex () const |
Returns the index of the current page if the iterator is valid; otherwise an undefined index is returned. More... | |
void | setPageIndex (std::vector< OggPage >::size_type index) |
Sets the current page index. More... | |
void | setSegmentIndex (std::vector< std::uint32_t >::size_type index) |
Sets the current segment index. More... | |
std::vector< std::uint32_t >::size_type | currentSegmentIndex () const |
Returns the index of the current segment (in the current page) if the iterator is valid; otherwise an undefined index is returned. More... | |
std::uint64_t | currentSegmentOffset () const |
Returns the start offset of the current segment in the input stream if the iterator is valid; otherwise an undefined offset is returned. More... | |
std::uint64_t | currentCharacterOffset () const |
Returns the offset of the current character in the input stream if the iterator is valid; otherwise an undefined offset is returned. More... | |
std::uint64_t | tellg () const |
Same as currentCharacterOffset(); only provided for compliance with std::istream. More... | |
std::uint32_t | currentSegmentSize () const |
Returns the size of the current segment. More... | |
void | setFilter (std::uint32_t streamSerialId) |
Allows to filter pages by the specified streamSerialId. More... | |
void | removeFilter () |
Removes a previously set filter. More... | |
bool | isLastPageFetched () const |
Returns whether the last page has already been fetched. More... | |
void | read (char *buffer, std::size_t count) |
Reads count bytes from the OGG stream and writes it to the specified buffer. More... | |
std::size_t | readAll (char *buffer, std::size_t max) |
Reads all bytes from the OGG stream and writes it to the specified buffer. More... | |
void | ignore (std::size_t count=1) |
Advances the position of the next character to be read from the OGG stream by count bytes. More... | |
bool | bytesRemaining (std::size_t atLeast) const |
Returns whether there are atLeast bytes remaining. More... | |
bool | resyncAt (std::uint64_t offset) |
Fetches the next page at the specified offset. More... | |
operator bool () const | |
Returns an indication whether the iterator is valid. More... | |
OggIterator & | operator++ () |
Increments the current position by one segment if the iterator is valid; otherwise nothing happens. More... | |
OggIterator | operator++ (int) |
Increments the current position by one segment if the iterator is valid; otherwise nothing happens. More... | |
OggIterator & | operator-- () |
Decrements the current position by one segment if the iterator is valid; otherwise nothing happens. More... | |
OggIterator | operator-- (int) |
Decrements the current position by one segment if the iterator is valid; otherwise nothing happens. More... | |
The OggIterator class helps iterating through all segments of an OGG bitstream.
If an OggIterator has just been constructed it is invalid. To fetch the first page from the stream call the reset() method. The iterator will now point to the first segment of the first page.
To go on call the appropriate methods. Parsing exceptions and IO exceptions might occur during iteration.
The internal buffer of OGG pages might be accessed using the pages() method.
Definition at line 11 of file oggiterator.h.
|
inline |
Constructs a new iterator for the specified stream of streamSize bytes at the specified startOffset.
Definition at line 70 of file oggiterator.h.
|
inline |
Returns whether there are atLeast bytes remaining.
Definition at line 268 of file oggiterator.h.
void TagParser::OggIterator::clear | ( | std::istream & | stream, |
std::uint64_t | startOffset, | ||
std::uint64_t | streamSize | ||
) |
Sets the stream and related parameters and clears all available pages.
Definition at line 32 of file oggiterator.cpp.
|
inline |
Returns the offset of the current character in the input stream if the iterator is valid; otherwise an undefined offset is returned.
Definition at line 211 of file oggiterator.h.
|
inline |
Returns the current OGG page.
Definition at line 131 of file oggiterator.h.
|
inline |
Returns the index of the current page if the iterator is valid; otherwise an undefined index is returned.
Definition at line 163 of file oggiterator.h.
|
inline |
Returns the start offset of the current OGG page.
Definition at line 140 of file oggiterator.h.
|
inline |
Returns the index of the current segment (in the current page) if the iterator is valid; otherwise an undefined index is returned.
Definition at line 193 of file oggiterator.h.
|
inline |
Returns the start offset of the current segment in the input stream if the iterator is valid; otherwise an undefined offset is returned.
Definition at line 202 of file oggiterator.h.
|
inline |
Returns the size of the current segment.
This method should never be called on an invalid iterator, since this causes undefined behaviour.
Definition at line 229 of file oggiterator.h.
void TagParser::OggIterator::ignore | ( | std::size_t | count = 1 | ) |
Advances the position of the next character to be read from the OGG stream by count bytes.
Throws | a TruncatedDataException if the end of the stream is exceeded. |
Definition at line 198 of file oggiterator.cpp.
|
inline |
Returns whether the last page has already been fetched.
Definition at line 260 of file oggiterator.h.
void TagParser::OggIterator::nextPage | ( | ) |
Increases the current position by one page.
Definition at line 63 of file oggiterator.cpp.
void TagParser::OggIterator::nextSegment | ( | ) |
Increases the current position by one segment.
Definition at line 81 of file oggiterator.cpp.
|
inline |
Returns an indication whether the iterator is valid.
The iterator is invalid when it has just been constructed. Incrementing and decrementing might cause invalidation.
If the iterator is invalid, it can be reset using the reset() method.
Some methods cause undefined behaviour if called on an invalid iterator.
Definition at line 155 of file oggiterator.h.
|
inline |
Increments the current position by one segment if the iterator is valid; otherwise nothing happens.
Definition at line 276 of file oggiterator.h.
|
inline |
Increments the current position by one segment if the iterator is valid; otherwise nothing happens.
Definition at line 285 of file oggiterator.h.
|
inline |
Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.
Definition at line 295 of file oggiterator.h.
|
inline |
Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.
Definition at line 304 of file oggiterator.h.
|
inline |
Returns a vector of containing the OGG pages that have been fetched yet.
Definition at line 122 of file oggiterator.h.
void TagParser::OggIterator::previousPage | ( | ) |
Decreases the current position by one page.
Definition at line 98 of file oggiterator.cpp.
void TagParser::OggIterator::previousSegment | ( | ) |
Decreases the current position by one segment.
Definition at line 113 of file oggiterator.cpp.
void TagParser::OggIterator::read | ( | char * | buffer, |
std::size_t | count | ||
) |
Reads count bytes from the OGG stream and writes it to the specified buffer.
Throws | a TruncatedDataException if the end of the stream is reached before count bytes have been read. |
Definition at line 134 of file oggiterator.cpp.
std::size_t TagParser::OggIterator::readAll | ( | char * | buffer, |
std::size_t | max | ||
) |
Reads all bytes from the OGG stream and writes it to the specified buffer.
Definition at line 168 of file oggiterator.cpp.
|
inline |
void TagParser::OggIterator::reset | ( | ) |
Resets the iterator to point at the first segment of the first page (matching the filter if set).
Fetched pages (directly accessible through the page() method) remain after resetting the iterator. Use clear() to clear all pages.
Definition at line 46 of file oggiterator.cpp.
bool TagParser::OggIterator::resyncAt | ( | std::uint64_t | offset | ) |
Fetches the next page at the specified offset.
This allows to omit parts of a file which is useful to
Regardless of the current iterator position, this method will assume the page at offset comes after the last known page. Hence offset must be greater than OggPage::startOffset() + OggPage::totalSize() of the last known page. This is checked by the method.
If the OGG capture pattern is not present at offset, up to 65307 bytes (max. size of an OGG page) are skipped. So in a valid stream, this method will always succeed if offset is less than the stream size minus 65307.
If a page could be found, it is appended to pages() and the iterator position is set to the first segment of that page. If no page could be found, this method does not alter the iterator.
Throws | std::ios_base::failure when an IO error occurs. |
Throws | Failure when a parsing error occurs. |
Definition at line 237 of file oggiterator.cpp.
|
inline |
Allows to filter pages by the specified streamSerialId.
Pages which do not match the specified streamSerialId will be skipped when getting the previous or the next page.
Definition at line 242 of file oggiterator.h.
|
inline |
Sets the current page index.
Definition at line 172 of file oggiterator.h.
|
inline |
Sets the current segment index.
This method should never be called with an index out of range (which is defined by the number of segments in the current page), since this causes undefined behaviour.
Definition at line 184 of file oggiterator.h.
|
inline |
Sets the stream.
Definition at line 98 of file oggiterator.h.
|
inline |
Returns the start offset (which has been specified when constructing the iterator).
Definition at line 106 of file oggiterator.h.
|
inline |
Returns the stream.
The stream has been specified when constructing the iterator and might be changed using the setStream() methods.
Definition at line 88 of file oggiterator.h.
|
inline |
Returns the stream size (which has been specified when constructing the iterator).
Definition at line 114 of file oggiterator.h.
|
inline |
Same as currentCharacterOffset(); only provided for compliance with std::istream.
Definition at line 219 of file oggiterator.h.