git.maemo.org Git - someplayer/blob - src/taglib/ogg/oggpageheader.h

   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
  19  *   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       uint 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(uint 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();
 223       ByteVector lacingValues() const;
 224
 225       class PageHeaderPrivate;
 226       PageHeaderPrivate *d;
 227     };
 228
 229   }
 230 }
 231
 232 #endif