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.

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ OggIterator()

Member Function Documentation

◆ bytesReadFromCurrentSegment()

◆ bytesRemaining()

◆ clear()

◆ currentCharacterOffset()

◆ currentPage()

◆ currentPageIndex()

◆ currentPageOffset()

◆ currentSegmentIndex()

◆ currentSegmentOffset()

◆ currentSegmentSize()

◆ ignore()

◆ isLastPageFetched()

◆ nextPage()

◆ nextSegment()

◆ operator bool()

◆ operator++() [1/2]

◆ operator++() [2/2]

◆ operator--() [1/2]

◆ operator--() [2/2]

◆ pages() [1/2]

◆ pages() [2/2]

◆ previousPage()

◆ previousSegment()

◆ read()

◆ readAll()

◆ remainingBytesInCurrentSegment()

◆ removeFilter()

◆ reset()

◆ resyncAt()

◆ setFilter()

◆ setPageIndex()

◆ setSegmentIndex()

◆ setStream()

◆ startOffset()

◆ stream()

◆ streamSize()

◆ tellg()