Tag Parser: TagParser::OggIterator Class Reference

Tag Parser 12.5.3 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
Public Member Functions | List of all members
TagParser::OggIterator Class Reference

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.
void | clear (std::istream &stream, std::uint64_t startOffset, std::uint64_t streamSize)
| Sets the stream and related parameters and clears all available pages.
std::istream & | stream ()
| Returns the stream.
void | setStream (std::istream &stream)
| Sets the stream.
std::uint64_t | startOffset () const
| Returns the start offset (which has been specified when constructing the iterator).
std::uint64_t | streamSize () const
| Returns the stream size (which has been specified when constructing the iterator).
void | reset ()
| Resets the iterator to point at the first segment of the first page (matching the filter if set).
void | nextPage ()
| Increases the current position by one page.
void | nextSegment ()
| Increases the current position by one segment.
void | previousPage ()
| Decreases the current position by one page.
void | previousSegment ()
| Decreases the current position by one segment.
const std::vector< OggPage > & | pages () const
| Returns a vector of containing the Ogg pages that have been fetched yet.
std::vector< OggPage > & | pages ()
| Returns a vector of containing the Ogg pages that have been fetched yet.
const OggPage & | currentPage () const
| Returns the current Ogg page.
std::uint64_t | currentPageOffset () const
| Returns the start offset of the current Ogg page.
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.
void | setPageIndex (std::vector< OggPage >::size_type index)
| Sets the current page index.
void | setSegmentIndex (std::vector< std::uint32_t >::size_type index)
| Sets the current segment index.
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.
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.
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.
std::uint64_t | tellg () const
| Same as currentCharacterOffset(); only provided for compliance with std::istream.
std::uint32_t | currentSegmentSize () const
| Returns the size of the current segment.
std::uint64_t | remainingBytesInCurrentSegment () const
| Returns the number of bytes left to read in the current segment.
std::uint64_t | bytesReadFromCurrentSegment () const
| Returns the number of bytes read from the current segment.
void | setFilter (std::uint32_t streamSerialId)
| Allows to filter pages by the specified streamSerialId.
void | removeFilter ()
| Removes a previously set filter.
bool | isLastPageFetched () const
| Returns whether the last page has already been fetched.
void | read (char *buffer, std::size_t count)
| Reads count bytes from the Ogg stream and writes it to the specified buffer.
std::size_t | readAll (char *buffer, std::size_t max)
| Reads all bytes from the Ogg stream and writes it to the specified buffer.
void | ignore (std::size_t count=1)
| Advances the position of the next character to be read from the Ogg stream by count bytes.
bool | bytesRemaining (std::size_t atLeast) const
| Returns whether there are atLeast bytes remaining.
bool | resyncAt (std::uint64_t offset)
| Fetches the next page at the specified offset.
| operator bool () const
| Returns an indication whether the iterator is valid.
OggIterator & | operator++ ()
| Increments the current position by one segment if the iterator is valid; otherwise nothing happens.
OggIterator | operator++ (int)
| Increments the current position by one segment if the iterator is valid; otherwise nothing happens.
OggIterator & | operator-- ()
| Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.
OggIterator | operator-- (int)
| Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.

## Detailed Description

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.

## Constructor & Destructor Documentation

## ◆ OggIterator()

TagParser::OggIterator::OggIterator | ( | std::istream & | stream,
|  | std::uint64_t | startOffset,
|  | std::uint64_t | streamSize )
| inline

Constructs a new iterator for the specified stream of streamSize bytes at the specified startOffset.

Definition at line 73 of file oggiterator.h.

## Member Function Documentation

## ◆ bytesReadFromCurrentSegment()

uint64_t TagParser::OggIterator::bytesReadFromCurrentSegment | ( |  | ) | const
| inline

Returns the number of bytes read from the current segment.

Definition at line 256 of file oggiterator.h.

## ◆ bytesRemaining()

bool TagParser::OggIterator::bytesRemaining | ( | std::size_t | atLeast | ) | const
| inline

Returns whether there are atLeast bytes remaining.

Deprecated
  Remove this unused function in v11.

Definition at line 296 of file oggiterator.h.

## ◆ clear()

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.

Remarks
  Invalidates the iterator. Use reset() to continue iteration.

Definition at line 32 of file oggiterator.cpp.

## ◆ currentCharacterOffset()

std::uint64_t TagParser::OggIterator::currentCharacterOffset | ( |  | ) | const
| inline

Returns the offset of the current character in the input stream if the iterator is valid; otherwise an undefined offset is returned.

See also
  currentSegmentOffset()

Definition at line 222 of file oggiterator.h.

## ◆ currentPage()

const OggPage & TagParser::OggIterator::currentPage | ( |  | ) | const
| inline

Returns the current Ogg page.

Remarks
  Calling this method when the iterator is invalid causes undefined behaviour.

Definition at line 142 of file oggiterator.h.

## ◆ currentPageIndex()

std::vector< OggPage >::size_type TagParser::OggIterator::currentPageIndex | ( |  | ) | const
| inline

Returns the index of the current page if the iterator is valid; otherwise an undefined index is returned.

Definition at line 174 of file oggiterator.h.

## ◆ currentPageOffset()

std::uint64_t TagParser::OggIterator::currentPageOffset | ( |  | ) | const
| inline

Returns the start offset of the current Ogg page.

Remarks
  Calling this method when the iterator is invalid causes undefined behaviour.

Definition at line 151 of file oggiterator.h.

## ◆ currentSegmentIndex()

std::vector< std::uint32_t >::size_type TagParser::OggIterator::currentSegmentIndex | ( |  | ) | const
| 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 204 of file oggiterator.h.

## ◆ currentSegmentOffset()

std::uint64_t TagParser::OggIterator::currentSegmentOffset | ( |  | ) | const
| inline

Returns the start offset of the current segment in the input stream if the iterator is valid; otherwise an undefined offset is returned.

See also
  currentCharacterOffset()

Definition at line 213 of file oggiterator.h.

## ◆ currentSegmentSize()

std::uint32_t TagParser::OggIterator::currentSegmentSize | ( |  | ) | const
| 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 240 of file oggiterator.h.

## ◆ ignore()

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.

Remarks
  - Might increase the current page index and/or the current segment index.
  - Page headers are skipped (this is the whole purpose of this method).
  - Seeking backward is not implemented yet since there is currently no use for such a method.

Exceptions

  Throws | a TruncatedDataException if the end of the stream is exceeded.

See also
  currentCharacterOffset()
  read()

Definition at line 199 of file oggiterator.cpp.

## ◆ isLastPageFetched()

bool TagParser::OggIterator::isLastPageFetched | ( |  | ) | const
| inline

Returns whether the last page has already been fetched.

Definition at line 287 of file oggiterator.h.

## ◆ nextPage()

void TagParser::OggIterator::nextPage | ( |  | ) |

Increases the current position by one page.

Remarks
  The iterator must be valid. The iterator might be invalidated.

Definition at line 63 of file oggiterator.cpp.

## ◆ nextSegment()

void TagParser::OggIterator::nextSegment | ( |  | ) |

Increases the current position by one segment.

Enters the next page if the current segment is the last one in the current page.

Remarks
  The iterator must be valid. The iterator might be invalidated.

Definition at line 81 of file oggiterator.cpp.

## ◆ operator bool()

TagParser::OggIterator::operator bool | ( |  | ) | const
| 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 166 of file oggiterator.h.

## ◆ operator++() [1/2]

OggIterator & TagParser::OggIterator::operator++ | ( |  | ) |
| inline

Increments the current position by one segment if the iterator is valid; otherwise nothing happens.

Definition at line 304 of file oggiterator.h.

## ◆ operator++() [2/2]

OggIterator TagParser::OggIterator::operator++ | ( | int |  | ) |
| inline

Increments the current position by one segment if the iterator is valid; otherwise nothing happens.

Definition at line 313 of file oggiterator.h.

## ◆ operator--() [1/2]

OggIterator & TagParser::OggIterator::operator-- | ( |  | ) |
| inline

Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.

Definition at line 323 of file oggiterator.h.

## ◆ operator--() [2/2]

OggIterator TagParser::OggIterator::operator-- | ( | int |  | ) |
| inline

Decrements the current position by one segment if the iterator is valid; otherwise nothing happens.

Definition at line 332 of file oggiterator.h.

## ◆ pages() [1/2]

std::vector< OggPage > & TagParser::OggIterator::pages | ( |  | ) |
| inline

Returns a vector of containing the Ogg pages that have been fetched yet.

Definition at line 133 of file oggiterator.h.

## ◆ pages() [2/2]

const std::vector< OggPage > & TagParser::OggIterator::pages | ( |  | ) | const
| inline

Returns a vector of containing the Ogg pages that have been fetched yet.

Definition at line 125 of file oggiterator.h.

## ◆ previousPage()

void TagParser::OggIterator::previousPage | ( |  | ) |

Decreases the current position by one page.

Remarks
  The iterator must be valid. The iterator might be invalidated.

Definition at line 98 of file oggiterator.cpp.

## ◆ previousSegment()

void TagParser::OggIterator::previousSegment | ( |  | ) |

Decreases the current position by one segment.

Remarks
  The iterator must be valid. The iterator might be invalidated.

Definition at line 113 of file oggiterator.cpp.

## ◆ read()

void TagParser::OggIterator::read | ( | char * | buffer,
|  | std::size_t | count )

Reads count bytes from the Ogg stream and writes it to the specified buffer.

Remarks
  - Might increase the current page index and/or the current segment index.
  - Page headers are skipped (this is the whole purpose of this method).

Exceptions

  Throws | a TruncatedDataException if the end of the stream is reached before count bytes have been read.

See also
  readAll()
  currentCharacterOffset()
  seekForward()

Definition at line 134 of file oggiterator.cpp.

## ◆ readAll()

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.

Remarks
  - Might increase the current page index and/or the current segment index.
  - Page headers are skipped (this is the whole purpose of this method).
  - Does not write more than max bytes to the buffer.

Returns
  Returns the number of bytes read from the Ogg stream. This might be less than max in case not that many bytes were available.

See also
  read()
  currentCharacterOffset()
  seekForward()

Deprecated
  Remove this unused function in v11.

Definition at line 169 of file oggiterator.cpp.

## ◆ remainingBytesInCurrentSegment()

std::uint64_t TagParser::OggIterator::remainingBytesInCurrentSegment | ( |  | ) | const
| inline

Returns the number of bytes left to read in the current segment.

Definition at line 248 of file oggiterator.h.

## ◆ removeFilter()

void TagParser::OggIterator::removeFilter | ( |  | ) |
| inline

Removes a previously set filter.

See also
  setFilter()

Definition at line 279 of file oggiterator.h.

## ◆ reset()

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.

## ◆ resyncAt()

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

- find the last page faster by skipping pages in the middle (last page is required for calculating the files duration).
- recover parsing after after an error occurred.

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.

Returns
  Returns an indication whether a page could be found.

Exceptions

  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.

## ◆ setFilter()

void TagParser::OggIterator::setFilter | ( | std::uint32_t | streamSerialId | ) |
| 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.

See also
  removeFilter()

Definition at line 269 of file oggiterator.h.

## ◆ setPageIndex()

void TagParser::OggIterator::setPageIndex | ( | std::vector< OggPage >::size_type | index | ) |
| inline

Sets the current page index.

Remarks
  This method should never be called with an index out of range (which is defined by the number of fetched pages), since this would cause undefined behaviour.

Definition at line 183 of file oggiterator.h.

## ◆ setSegmentIndex()

void TagParser::OggIterator::setSegmentIndex | ( | std::vector< std::uint32_t >::size_type | index | ) |
| 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 195 of file oggiterator.h.

## ◆ setStream()

void TagParser::OggIterator::setStream | ( | std::istream & | stream | ) |
| inline

Sets the stream.

Remarks
  The new stream must have the same data as the old stream to keep the iterator in a sane state.

See also
  stream()

Definition at line 101 of file oggiterator.h.

## ◆ startOffset()

std::uint64_t TagParser::OggIterator::startOffset | ( |  | ) | const
| inline

Returns the start offset (which has been specified when constructing the iterator).

Definition at line 109 of file oggiterator.h.

## ◆ stream()

std::istream & TagParser::OggIterator::stream | ( |  | ) |
| inline

Returns the stream.

The stream has been specified when constructing the iterator and might be changed using the setStream() methods.

Definition at line 91 of file oggiterator.h.

## ◆ streamSize()

std::uint64_t TagParser::OggIterator::streamSize | ( |  | ) | const
| inline

Returns the stream size (which has been specified when constructing the iterator).

Definition at line 117 of file oggiterator.h.

## ◆ tellg()

std::uint64_t TagParser::OggIterator::tellg | ( |  | ) | const
| inline

Same as currentCharacterOffset(); only provided for compliance with std::istream.

Definition at line 230 of file oggiterator.h.

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

- ogg/oggiterator.h
- ogg/oggiterator.cpp