Tag Parser  7.1.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
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, uint64 startOffset, uint64 streamSize)
 Constructs a new iterator for the specified stream of streamSize bytes at the specified startOffset. More...
 
void clear (std::istream &stream, uint64 startOffset, uint64 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...
 
uint64 startOffset () const
 Returns the start offset (which has been specified when constructing the iterator). More...
 
uint64 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 OggPagecurrentPage () const
 Returns the current OGG page. More...
 
uint64 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< uint32 >::size_type index)
 Sets the current segment index. More...
 
std::vector< uint32 >::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...
 
uint64 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...
 
uint64 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...
 
uint64 tellg () const
 Same as currentCharacterOffset(); only provided for compliance with std::istream. More...
 
uint32 currentSegmentSize () const
 Returns the size of the current segment. More...
 
void setFilter (uint32 streamSerialId)
 Allows to filter pages by the specified streamSerialId. More...
 
void removeFilter ()
 Removes a previously set filter. More...
 
bool areAllPagesFetched () const
 Returns an indication whether all pages have 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...
 
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 (uint64 offset)
 Fetches the next page at the specified offset. More...
 
 operator bool () const
 Returns an indication whether the iterator is valid. More...
 
OggIteratoroperator++ ()
 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...
 
OggIteratoroperator-- ()
 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...
 

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,
uint64  startOffset,
uint64  streamSize 
)
inline

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

Definition at line 70 of file oggiterator.h.

Member Function Documentation

◆ areAllPagesFetched()

bool TagParser::OggIterator::areAllPagesFetched ( ) const
inline

Returns an indication whether all pages have been fetched.

This means that for each page in the stream in the specified range (stream and range have been specified when constructing the iterator) an OggPage instance has been created and pushed to pages(). This is independend from the current iterator position. Fetched pages remain after resetting the iterator.

Remarks
This is also true if pages in the middle of the file have been omitted because it is actually just checked whether the last page has been fetched.
Todo:
Rename to isLastPageFetched() in next major release.

Definition at line 268 of file oggiterator.h.

◆ bytesRemaining()

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

Returns whether there are atLeast bytes remaining.

Definition at line 276 of file oggiterator.h.

◆ clear()

void TagParser::OggIterator::clear ( std::istream &  stream,
uint64  startOffset,
uint64  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()

uint64 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 211 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 131 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 163 of file oggiterator.h.

◆ currentPageOffset()

uint64 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 140 of file oggiterator.h.

◆ currentSegmentIndex()

std::vector< uint32 >::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 193 of file oggiterator.h.

◆ currentSegmentOffset()

uint64 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 202 of file oggiterator.h.

◆ currentSegmentSize()

uint32 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 229 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
Throwsa TruncatedDataException if the end of the stream is exceeded.
See also
currentCharacterOffset()
read()

Definition at line 199 of file oggiterator.cpp.

◆ 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.

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 reseted using the reset() method.

Some methods cause undefined behaviour if called on an invalid iterator.

Definition at line 155 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 284 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 293 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 303 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 312 of file oggiterator.h.

◆ pages()

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 122 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
Throwsa 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()

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()

Definition at line 169 of file oggiterator.cpp.

◆ removeFilter()

void TagParser::OggIterator::removeFilter ( )
inline

Removes a previously set filter.

See also
setFilter()

Definition at line 252 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 accessable 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 ( uint64  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 occured.

Regardless of the current iterator position, this method will assume the page at offset comes after the last known page. Hence offset must be greather 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
Throwsstd::ios_base::failure when an IO error occurs.
ThrowsFailure when a parsing error occurs.

Definition at line 238 of file oggiterator.cpp.

◆ setFilter()

void TagParser::OggIterator::setFilter ( uint32  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 242 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 172 of file oggiterator.h.

◆ setSegmentIndex()

void TagParser::OggIterator::setSegmentIndex ( std::vector< uint32 >::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 184 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 98 of file oggiterator.h.

◆ startOffset()

uint64 TagParser::OggIterator::startOffset ( ) const
inline

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

Definition at line 106 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 88 of file oggiterator.h.

◆ streamSize()

uint64 TagParser::OggIterator::streamSize ( ) const
inline

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

Definition at line 114 of file oggiterator.h.

◆ tellg()

uint64 TagParser::OggIterator::tellg ( ) const
inline

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

Definition at line 219 of file oggiterator.h.


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