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#include "taglib_export.h"
27#include "tfile.h"
28#include "tbytevectorlist.h"
29
30#ifndef TAGLIB_OGGFILE_H
31#define TAGLIB_OGGFILE_H
32
33namespace TagLib {
34
35 //! A namespace for the classes used by Ogg-based metadata files
36
37 namespace Ogg {
38
39 class PageHeader;
40
41 //! An implementation of TagLib::File with some helpers for Ogg based formats
42
43 /*!
44 * This is an implementation of Ogg file page and packet rendering and is of
45 * use to Ogg based formats. While the API is small this handles the
46 * non-trivial details of breaking up an Ogg stream into packets and makes
47 * these available (via subclassing) to the codec meta data implementations.
48 */
49
50 class TAGLIB_EXPORT File : public TagLib::File
51 {
52 public:
53 virtual ~File();
54
55 /*!
56 * Returns the packet contents for the i-th packet (starting from zero)
57 * in the Ogg bitstream.
58 *
59 * \warning This requires reading at least the packet header for every page
60 * up to the requested page.
61 */
62 ByteVector packet(unsigned int i);
63
64 /*!
65 * Sets the packet with index \a i to the value \a p.
66 */
67 void setPacket(unsigned int i, const ByteVector &p);
68
69 /*!
70 * Returns a pointer to the PageHeader for the first page in the stream or
71 * null if the page could not be found.
72 */
73 const PageHeader *firstPageHeader();
74
75 /*!
76 * Returns a pointer to the PageHeader for the last page in the stream or
77 * null if the page could not be found.
78 */
79 const PageHeader *lastPageHeader();
80
81 virtual bool save();
82
83 protected:
84 /*!
85 * Constructs an Ogg file from \a file.
86 *
87 * \note This constructor is protected since Ogg::File shouldn't be
88 * instantiated directly but rather should be used through the codec
89 * specific subclasses.
90 */
91 File(FileName file);
92
93 /*!
94 * Constructs an Ogg file from \a stream.
95 *
96 * \note This constructor is protected since Ogg::File shouldn't be
97 * instantiated directly but rather should be used through the codec
98 * specific subclasses.
99 *
100 * \note TagLib will *not* take ownership of the stream, the caller is
101 * responsible for deleting it after the File object.
102 */
103 File(IOStream *stream);
104
105 private:
106 File(const File &);
107 File &operator=(const File &);
108
109 /*!
110 * Reads the pages from the beginning of the file until enough to compose
111 * the requested packet.
112 */
113 bool readPages(unsigned int i);
114
115 /*!
116 * Writes the requested packet to the file.
117 */
118 void writePacket(unsigned int i, const ByteVector &packet);
119
120 class FilePrivate;
121 FilePrivate *d;
122 };
123
124 }
125}
126
127#endif
128