1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : wheeler@kde.org 4 ***************************************************************************/ 5 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. * 10 * * 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. * 15 * * 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., 51 Franklin Street, Fifth Floor, Boston, MA * 19 * 02110-1301 USA * 20 * * 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 ***************************************************************************/ 25 26 #ifndef TAGLIB_OGGPAGEHEADER_H 27 #define TAGLIB_OGGPAGEHEADER_H 28 29 #include "tlist.h" 30 #include "tbytevector.h" 31 #include "taglib_export.h" 32 33 namespace TagLib { 34 35 namespace Ogg { 36 37 class File; 38 39 //! An implementation of the page headers associated with each Ogg::Page 40 41 /*! 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 44 * to the codecs. 45 */ 46 47 class TAGLIB_EXPORT PageHeader 48 { 49 public: 50 /*! 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 53 * later. 54 */ 55 PageHeader(File *file = 0, long pageOffset = -1); 56 57 /*! 58 * Deletes this instance of the PageHeader. 59 */ 60 virtual ~PageHeader(); 61 62 /*! 63 * Returns true if the header parsed properly and is valid. 64 */ 65 bool isValid() const; 66 67 /*! 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. 71 * 72 * \see setPacketSizes() 73 */ 74 List<int> packetSizes() const; 75 76 /*! 77 * Sets the sizes of the packets in this page to \a sizes. Internally this 78 * updates the lacing values in the header. 79 * 80 * \see packetSizes() 81 */ 82 void setPacketSizes(const List<int> &sizes); 83 84 /*! 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. 88 * 89 * \see lastPacketCompleted() 90 * \see setFirstPacketContinued() 91 */ 92 bool firstPacketContinued() const; 93 94 /*! 95 * Sets the internal flag indicating if the first packet in this page is 96 * continued to \a continued. 97 * 98 * \see firstPacketContinued() 99 */ 100 void setFirstPacketContinued(bool continued); 101 102 /*! 103 * Returns true if the last packet of this page is completely contained in 104 * this page. 105 * 106 * \see firstPacketContinued() 107 * \see setLastPacketCompleted() 108 */ 109 bool lastPacketCompleted() const; 110 111 /*! 112 * Sets the internal flag indicating if the last packet in this page is 113 * complete to \a completed. 114 * 115 * \see lastPacketCompleted() 116 */ 117 void setLastPacketCompleted(bool completed); 118 119 /*! 120 * This returns true if this is the first page of the Ogg (logical) stream. 121 * 122 * \see setFirstPageOfStream() 123 */ 124 bool firstPageOfStream() const; 125 126 /*! 127 * Marks this page as the first page of the Ogg stream. 128 * 129 * \see firstPageOfStream() 130 */ 131 void setFirstPageOfStream(bool first); 132 133 /*! 134 * This returns true if this is the last page of the Ogg (logical) stream. 135 * 136 * \see setLastPageOfStream() 137 */ 138 bool lastPageOfStream() const; 139 140 /*! 141 * Marks this page as the last page of the Ogg stream. 142 * 143 * \see lastPageOfStream() 144 */ 145 void setLastPageOfStream(bool last); 146 147 /*! 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. 151 * 152 * \see setAbsoluteGranularPosition() 153 */ 154 long long absoluteGranularPosition() const; 155 156 /*! 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. 160 * 161 * \see absoluteGranularPosition() 162 */ 163 void setAbsoluteGranularPosition(long long agp); 164 165 /*! 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. 169 * 170 * \see setStreamSerialNumber() 171 */ 172 unsigned int streamSerialNumber() const; 173 174 /*! 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 178 * stream. 179 * 180 * \see streamSerialNumber() 181 */ 182 void setStreamSerialNumber(unsigned int n); 183 184 /*! 185 * Returns the index of the page within the Ogg stream. This helps make it 186 * possible to determine if pages have been lost. 187 * 188 * \see setPageSequenceNumber() 189 */ 190 int pageSequenceNumber() const; 191 192 /*! 193 * Sets the page's position in the stream to \a sequenceNumber. 194 * 195 * \see pageSequenceNumber() 196 */ 197 void setPageSequenceNumber(int sequenceNumber); 198 199 /*! 200 * Returns the complete header size. 201 */ 202 int size() const; 203 204 /*! 205 * Returns the size of the data portion of the page -- i.e. the size of the 206 * page less the header size. 207 */ 208 int dataSize() const; 209 210 /*! 211 * Render the page header to binary data. 212 * 213 * \note The checksum -- bytes 22 - 25 -- will be left empty and must be 214 * filled in when rendering the entire page. 215 */ 216 ByteVector render() const; 217 218 private: 219 PageHeader(const PageHeader &); 220 PageHeader &operator=(const PageHeader &); 221 222 void read(Ogg::File *file, long pageOffset); 223 ByteVector lacingValues() const; 224 225 class PageHeaderPrivate; 226 PageHeaderPrivate *d; 227 }; 228 229 } 230 } 231 232 #endif 233