git.maemo.org Git - someplayer/blob - src/taglib/ogg/oggpage.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_OGGPAGE_H
  27 #define TAGLIB_OGGPAGE_H
  28
  29 #include "taglib_export.h"
  30 #include "tbytevectorlist.h"
  31
  32 namespace TagLib {
  33
  34   namespace Ogg {
  35
  36     class File;
  37     class PageHeader;
  38
  39     //! An implementation of Ogg pages
  40
  41     /*!
  42      * This is an implementation of the pages that make up an Ogg stream.
  43      * This handles parsing pages and breaking them down into packets and handles
  44      * the details of packets spanning multiple pages and pages that contiain
  45      * multiple packets.
  46      *
  47      * In most Xiph.org formats the comments are found in the first few packets,
  48      * this however is a reasonably complete implementation of Ogg pages that
  49      * could potentially be useful for non-meta data purposes.
  50      */
  51
  52     class TAGLIB_EXPORT Page
  53     {
  54     public:
  55       /*!
  56        * Read an Ogg page from the \a file at the position \a pageOffset.
  57        */
  58       Page(File *file, long pageOffset);
  59
  60       virtual ~Page();
  61
  62       /*!
  63        * Returns the page's position within the file (in bytes).
  64        */
  65       long fileOffset() const;
  66
  67       /*!
  68        * Returns a pointer to the header for this page.  This pointer will become
  69        * invalid when the page is deleted.
  70        */
  71       const PageHeader *header() const;
  72
  73       /*!
  74        * Returns a copy of the page with \a sequenceNumber set as sequence number.
  75        *
  76        * \see header()
  77        * \see PageHeader::setPageSequenceNumber()
  78        */
  79       Page* getCopyWithNewPageSequenceNumber(int sequenceNumber);
  80
  81       /*!
  82        * Returns the index of the first packet wholly or partially contained in
  83        * this page.
  84        *
  85        * \see setFirstPacketIndex()
  86        */
  87       int firstPacketIndex() const;
  88
  89       /*!
  90        * Sets the index of the first packet in the page.
  91        *
  92        * \see firstPacketIndex()
  93        */
  94       void setFirstPacketIndex(int index);
  95
  96       /*!
  97        * When checking to see if a page contains a given packet this set of flags
  98        * represents the possible values for that packets status in the page.
  99        *
 100        * \see containsPacket()
 101        */
 102       enum ContainsPacketFlags {
 103         //! No part of the packet is contained in the page
 104         DoesNotContainPacket = 0x0000,
 105         //! The packet is wholly contained in the page
 106         CompletePacket       = 0x0001,
 107         //! The page starts with the given packet
 108         BeginsWithPacket     = 0x0002,
 109         //! The page ends with the given packet
 110         EndsWithPacket       = 0x0004
 111       };
 112
 113       /*!
 114        * Checks to see if the specified \a packet is contained in the current
 115        * page.
 116        *
 117        * \see ContainsPacketFlags
 118        */
 119       ContainsPacketFlags containsPacket(int index) const;
 120
 121       /*!
 122        * Returns the number of packets (whole or partial) in this page.
 123        */
 124       uint packetCount() const;
 125
 126       /*!
 127        * Returns a list of the packets in this page.
 128        *
 129        * \note Either or both the first and last packets may be only partial.
 130        * \see PageHeader::firstPacketContinued()
 131        */
 132       ByteVectorList packets() const;
 133
 134       /*!
 135        * Returns the size of the page in bytes.
 136        */
 137       int size() const;
 138
 139       ByteVector render() const;
 140
 141       /*!
 142        * Defines a strategy for pagination, or grouping pages into Ogg packets,
 143        * for use with pagination methods.
 144        *
 145        * \note Yes, I'm aware that this is not a canonical "Strategy Pattern",
 146        * the term was simply convenient.
 147        */
 148       enum PaginationStrategy {
 149         /*!
 150          * Attempt to put the specified set of packets into a single Ogg packet.
 151          * If the sum of the packet data is greater than will fit into a single
 152          * Ogg page -- 65280 bytes -- this will fall back to repagination using
 153          * the recommended page sizes.
 154          */
 155         SinglePagePerGroup,
 156         /*!
 157          * Split the packet or group of packets into pages that conform to the
 158          * sizes recommended in the Ogg standard.
 159          */
 160         Repaginate
 161       };
 162
 163       /*!
 164        * Pack \a packets into Ogg pages using the \a strategy for pagination.
 165        * The page number indicater inside of the rendered packets will start
 166        * with \a firstPage and be incremented for each page rendered.
 167        * \a containsLastPacket should be set to true if \a packets contains the
 168        * last page in the stream and will set the appropriate flag in the last
 169        * rendered Ogg page's header.  \a streamSerialNumber should be set to
 170        * the serial number for this stream.
 171        *
 172        * \note The "absolute granule position" is currently always zeroed using
 173        * this method as this suffices for the comment headers.
 174        *
 175        * \warning The pages returned by this method must be deleted by the user.
 176        * You can use List<T>::setAutoDelete(true) to set these pages to be
 177        * automatically deleted when this list passes out of scope.
 178        *
 179        * \see PaginationStrategy
 180        * \see List::setAutoDelete()
 181        */
 182       static List<Page *> paginate(const ByteVectorList &packets,
 183                                    PaginationStrategy strategy,
 184                                    uint streamSerialNumber,
 185                                    int firstPage,
 186                                    bool firstPacketContinued = false,
 187                                    bool lastPacketCompleted = true,
 188                                    bool containsLastPacket = false);
 189
 190     protected:
 191       /*!
 192        * Creates an Ogg packet based on the data in \a packets.  The page number
 193        * for each page will be set to \a pageNumber.
 194        */
 195       Page(const ByteVectorList &packets,
 196            uint streamSerialNumber,
 197            int pageNumber,
 198            bool firstPacketContinued = false,
 199            bool lastPacketCompleted = true,
 200            bool containsLastPacket = false);
 201
 202     private:
 203       Page(const Page &);
 204       Page &operator=(const Page &);
 205
 206       class PagePrivate;
 207       PagePrivate *d;
 208     };
 209   }
 210 }
 211 #endif