TagLib API Documentation
Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
TagLib::Ogg::Page Class Reference

An implementation of Ogg pages. More...

#include <oggpage.h>

Public Types

enum  ContainsPacketFlags { DoesNotContainPacket = 0x0000 , CompletePacket = 0x0001 , BeginsWithPacket = 0x0002 , EndsWithPacket = 0x0004 }
 
enum  PaginationStrategy { SinglePagePerGroup , Repaginate }
 

Public Member Functions

 Page (File *file, offset_t pageOffset)
 
 ~Page ()
 
 Page (const Page &)=delete
 
Pageoperator= (const Page &)=delete
 
offset_t fileOffset () const
 
const PageHeaderheader () const
 
int pageSequenceNumber () const
 
void setPageSequenceNumber (int sequenceNumber)
 
int firstPacketIndex () const
 
void setFirstPacketIndex (int index)
 
ContainsPacketFlags containsPacket (int index) const
 
unsigned int packetCount () const
 
ByteVectorList packets () const
 
int size () const
 
ByteVector render () const
 

Static Public Member Functions

static List< Page * > paginate (const ByteVectorList &packets, PaginationStrategy strategy, unsigned int streamSerialNumber, int firstPage, bool firstPacketContinued=false, bool lastPacketCompleted=true, bool containsLastPacket=false)
 

Protected Member Functions

 Page (const ByteVectorList &packets, unsigned int streamSerialNumber, int pageNumber, bool firstPacketContinued=false, bool lastPacketCompleted=true, bool containsLastPacket=false)
 

Detailed Description

An implementation of Ogg pages.

This is an implementation of the pages that make up an Ogg stream. This handles parsing pages and breaking them down into packets and handles the details of packets spanning multiple pages and pages that contain multiple packets.

In most Xiph.org formats the comments are found in the first few packets, this however is a reasonably complete implementation of Ogg pages that could potentially be useful for non-metadata purposes.

Member Enumeration Documentation

◆ ContainsPacketFlags

When checking to see if a page contains a given packet this set of flags represents the possible values for that packet's status in the page.

See also
containsPacket()
Enumerator
DoesNotContainPacket 

No part of the packet is contained in the page.

CompletePacket 

The packet is wholly contained in the page.

BeginsWithPacket 

The page starts with the given packet.

EndsWithPacket 

The page ends with the given packet.

◆ PaginationStrategy

Defines a strategy for pagination, or grouping pages into Ogg packets, for use with pagination methods.

Note
Yes, I'm aware that this is not a canonical "Strategy Pattern", the term was simply convenient.
Enumerator
SinglePagePerGroup 

Attempt to put the specified set of packets into a single Ogg packet. If the sum of the packet data is greater than will fit into a single Ogg page – 65280 bytes – this will fall back to repagination using the recommended page sizes.

Repaginate 

Split the packet or group of packets into pages that conform to the sizes recommended in the Ogg standard.

Constructor & Destructor Documentation

◆ Page() [1/3]

TagLib::Ogg::Page::Page ( File file,
offset_t  pageOffset 
)

Read an Ogg page from the file at the position pageOffset.

◆ ~Page()

TagLib::Ogg::Page::~Page ( )

◆ Page() [2/3]

TagLib::Ogg::Page::Page ( const Page )
delete

◆ Page() [3/3]

TagLib::Ogg::Page::Page ( const ByteVectorList packets,
unsigned int  streamSerialNumber,
int  pageNumber,
bool  firstPacketContinued = false,
bool  lastPacketCompleted = true,
bool  containsLastPacket = false 
)
protected

Creates an Ogg packet based on the data in packets. The page number for each page will be set to pageNumber.

Member Function Documentation

◆ containsPacket()

ContainsPacketFlags TagLib::Ogg::Page::containsPacket ( int  index) const

Checks to see if the specified packet is contained in the current page.

See also
ContainsPacketFlags

◆ fileOffset()

offset_t TagLib::Ogg::Page::fileOffset ( ) const

Returns the page's position within the file (in bytes).

◆ firstPacketIndex()

int TagLib::Ogg::Page::firstPacketIndex ( ) const

Returns the index of the first packet wholly or partially contained in this page.

See also
setFirstPacketIndex()

◆ header()

const PageHeader * TagLib::Ogg::Page::header ( ) const

Returns a pointer to the header for this page. This pointer will become invalid when the page is deleted.

◆ operator=()

Page & TagLib::Ogg::Page::operator= ( const Page )
delete

◆ packetCount()

unsigned int TagLib::Ogg::Page::packetCount ( ) const

Returns the number of packets (whole or partial) in this page.

◆ packets()

ByteVectorList TagLib::Ogg::Page::packets ( ) const

Returns a list of the packets in this page.

Note
Either or both the first and last packets may be only partial.
See also
PageHeader::firstPacketContinued()

◆ pageSequenceNumber()

int TagLib::Ogg::Page::pageSequenceNumber ( ) const

Returns the index of the page within the Ogg stream. This helps make it possible to determine if pages have been lost.

See also
setPageSequenceNumber()

◆ paginate()

static List< Page * > TagLib::Ogg::Page::paginate ( const ByteVectorList packets,
PaginationStrategy  strategy,
unsigned int  streamSerialNumber,
int  firstPage,
bool  firstPacketContinued = false,
bool  lastPacketCompleted = true,
bool  containsLastPacket = false 
)
static

Pack packets into Ogg pages using the strategy for pagination. The page number indicator inside of the rendered packets will start with firstPage and be incremented for each page rendered. containsLastPacket should be set to true if packets contains the last page in the stream and will set the appropriate flag in the last rendered Ogg page's header. streamSerialNumber should be set to the serial number for this stream.

Note
The "absolute granule position" is currently always zeroed using this method as this suffices for the comment headers.
Warning
The pages returned by this method must be deleted by the user. You can use List<T>::setAutoDelete(true) to set these pages to be automatically deleted when this list passes out of scope.
See also
PaginationStrategy
List::setAutoDelete()

◆ render()

ByteVector TagLib::Ogg::Page::render ( ) const

◆ setFirstPacketIndex()

void TagLib::Ogg::Page::setFirstPacketIndex ( int  index)

Sets the index of the first packet in the page.

See also
firstPacketIndex()

◆ setPageSequenceNumber()

void TagLib::Ogg::Page::setPageSequenceNumber ( int  sequenceNumber)

Sets the page's position in the stream to sequenceNumber.

See also
pageSequenceNumber()

◆ size()

int TagLib::Ogg::Page::size ( ) const

Returns the size of the page in bytes.


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