Tag Parser  6.3.0
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
Public Member Functions | List of all members
Media::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...
 
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...
 
 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()

Media::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 69 of file oggiterator.h.

Member Function Documentation

◆ areAllPagesFetched()

bool Media::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.

Definition at line 254 of file oggiterator.h.

◆ bytesRemaining()

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

Returns whether there are atLeast bytes remaining.

Definition at line 262 of file oggiterator.h.

◆ clear()

void Media::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 28 of file oggiterator.cpp.

◆ currentCharacterOffset()

uint64 Media::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 201 of file oggiterator.h.

◆ currentPage()

const OggPage & Media::OggIterator::currentPage ( ) const
inline

Returns the current OGG page.

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

Definition at line 129 of file oggiterator.h.

◆ currentPageIndex()

std::vector< OggPage >::size_type Media::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 152 of file oggiterator.h.

◆ currentSegmentIndex()

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

◆ currentSegmentOffset()

uint64 Media::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 192 of file oggiterator.h.

◆ currentSegmentSize()

uint32 Media::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 219 of file oggiterator.h.

◆ ignore()

void Media::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 193 of file oggiterator.cpp.

◆ nextPage()

void Media::OggIterator::nextPage ( )

Increases the current position by one page.

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

Definition at line 59 of file oggiterator.cpp.

◆ nextSegment()

void Media::OggIterator::nextSegment ( )

Increases the current position by one segment.

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

Definition at line 77 of file oggiterator.cpp.

◆ operator bool()

Media::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 might cause undefined behaviour if called on an invalid iterator.

Definition at line 144 of file oggiterator.h.

◆ operator++() [1/2]

OggIterator & Media::OggIterator::operator++ ( )
inline

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

Definition at line 270 of file oggiterator.h.

◆ operator++() [2/2]

OggIterator Media::OggIterator::operator++ ( int  )
inline

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

Definition at line 279 of file oggiterator.h.

◆ operator--() [1/2]

OggIterator & Media::OggIterator::operator-- ( )
inline

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

Definition at line 289 of file oggiterator.h.

◆ operator--() [2/2]

OggIterator Media::OggIterator::operator-- ( int  )
inline

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

Definition at line 298 of file oggiterator.h.

◆ pages()

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

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

Definition at line 120 of file oggiterator.h.

◆ previousPage()

void Media::OggIterator::previousPage ( )

Decreases the current position by one page.

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

Definition at line 94 of file oggiterator.cpp.

◆ previousSegment()

void Media::OggIterator::previousSegment ( )

Decreases the current position by one segment.

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

Definition at line 109 of file oggiterator.cpp.

◆ read()

void Media::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 130 of file oggiterator.cpp.

◆ readAll()

size_t Media::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 read more than max bytes from the buffer.
See also
read()
currentCharacterOffset()
seekForward()

Definition at line 163 of file oggiterator.cpp.

◆ removeFilter()

void Media::OggIterator::removeFilter ( )
inline

Removes a previously set filter.

See also
setFilter()

Definition at line 242 of file oggiterator.h.

◆ reset()

void Media::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 42 of file oggiterator.cpp.

◆ setFilter()

void Media::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 232 of file oggiterator.h.

◆ setPageIndex()

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

Sets the current page index.

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

Definition at line 162 of file oggiterator.h.

◆ setSegmentIndex()

void Media::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 174 of file oggiterator.h.

◆ setStream()

void Media::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 96 of file oggiterator.h.

◆ startOffset()

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

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

Definition at line 104 of file oggiterator.h.

◆ stream()

std::istream & Media::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 86 of file oggiterator.h.

◆ streamSize()

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

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

Definition at line 112 of file oggiterator.h.

◆ tellg()

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

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

Definition at line 209 of file oggiterator.h.


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