1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
6 /***************************************************************************
7 * This library is free software; you can redistribute it and/or modify *
8 * it under the terms of the GNU Lesser General Public License version *
9 * 2.1 as published by the Free Software Foundation. *
11 * This library is distributed in the hope that it will be useful, but *
12 * WITHOUT ANY WARRANTY; without even the implied warranty of *
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14 * Lesser General Public License for more details. *
16 * You should have received a copy of the GNU Lesser General Public *
17 * License along with this library; if not, write to the Free Software *
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
21 * Alternatively, this file is available under the Mozilla Public *
22 * License Version 1.1. You may obtain a copy of the License at *
23 * http://www.mozilla.org/MPL/ *
24 ***************************************************************************/
26 #ifndef TAGLIB_OGGPAGEHEADER_H
27 #define TAGLIB_OGGPAGEHEADER_H
30 #include "tbytevector.h"
31 #include "taglib_export.h"
39 //! An implementation of the page headers associated with each Ogg::Page
42 * This class implements Ogg page headers which contain the information
43 * about Ogg pages needed to break them into packets which can be passed on
47 class TAGLIB_EXPORT PageHeader
51 * Reads a PageHeader from \a file starting at \a pageOffset. The defaults
52 * create a page with no (and as such, invalid) data that must be set
55 PageHeader(File *file = 0, long pageOffset = -1);
58 * Deletes this instance of the PageHeader.
60 virtual ~PageHeader();
63 * Returns true if the header parsed properly and is valid.
68 * Ogg pages contain a list of packets (which are used by the contained
69 * codecs). The sizes of these pages is encoded in the page header. This
70 * returns a list of the packet sizes in bytes.
72 * \see setPacketSizes()
74 List<int> packetSizes() const;
77 * Sets the sizes of the packets in this page to \a sizes. Internally this
78 * updates the lacing values in the header.
82 void setPacketSizes(const List<int> &sizes);
85 * Some packets can be <i>continued</i> across multiple pages. If the
86 * first packet in the current page is a continuation this will return
87 * true. If this is page starts with a new packet this will return false.
89 * \see lastPacketCompleted()
90 * \see setFirstPacketContinued()
92 bool firstPacketContinued() const;
95 * Sets the internal flag indicating if the first packet in this page is
96 * continued to \a continued.
98 * \see firstPacketContinued()
100 void setFirstPacketContinued(bool continued);
103 * Returns true if the last packet of this page is completely contained in
106 * \see firstPacketContinued()
107 * \see setLastPacketCompleted()
109 bool lastPacketCompleted() const;
112 * Sets the internal flag indicating if the last packet in this page is
113 * complete to \a completed.
115 * \see lastPacketCompleted()
117 void setLastPacketCompleted(bool completed);
120 * This returns true if this is the first page of the Ogg (logical) stream.
122 * \see setFirstPageOfStream()
124 bool firstPageOfStream() const;
127 * Marks this page as the first page of the Ogg stream.
129 * \see firstPageOfStream()
131 void setFirstPageOfStream(bool first);
134 * This returns true if this is the last page of the Ogg (logical) stream.
136 * \see setLastPageOfStream()
138 bool lastPageOfStream() const;
141 * Marks this page as the last page of the Ogg stream.
143 * \see lastPageOfStream()
145 void setLastPageOfStream(bool last);
148 * A special value of containing the position of the packet to be
149 * interpreted by the codec. In the case of Vorbis this contains the PCM
150 * value and is used to calculate the length of the stream.
152 * \see setAbsoluteGranularPosition()
154 long long absoluteGranularPosition() const;
157 * A special value of containing the position of the packet to be
158 * interpreted by the codec. It is only supported here so that it may be
159 * coppied from one page to another.
161 * \see absoluteGranularPosition()
163 void setAbsoluteGranularPosition(long long agp);
166 * Every Ogg logical stream is given a random serial number which is common
167 * to every page in that logical stream. This returns the serial number of
168 * the stream associated with this packet.
170 * \see setStreamSerialNumber()
172 uint streamSerialNumber() const;
175 * Every Ogg logical stream is given a random serial number which is common
176 * to every page in that logical stream. This sets this pages serial
177 * number. This method should be used when adding new pages to a logical
180 * \see streamSerialNumber()
182 void setStreamSerialNumber(uint n);
185 * Returns the index of the page within the Ogg stream. This helps make it
186 * possible to determine if pages have been lost.
188 * \see setPageSequenceNumber()
190 int pageSequenceNumber() const;
193 * Sets the page's position in the stream to \a sequenceNumber.
195 * \see pageSequenceNumber()
197 void setPageSequenceNumber(int sequenceNumber);
200 * Returns the complete header size.
205 * Returns the size of the data portion of the page -- i.e. the size of the
206 * page less the header size.
208 int dataSize() const;
211 * Render the page header to binary data.
213 * \note The checksum -- bytes 22 - 25 -- will be left empty and must be
214 * filled in when rendering the entire page.
216 ByteVector render() const;
219 PageHeader(const PageHeader &);
220 PageHeader &operator=(const PageHeader &);
223 ByteVector lacingValues() const;
225 class PageHeaderPrivate;
226 PageHeaderPrivate *d;