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_RIFFFILE_H
27#define TAGLIB_RIFFFILE_H
28
29#include "taglib_export.h"
30#include "tfile.h"
31
32namespace TagLib {
33
34 //! An implementation of TagLib::File with RIFF specific methods
35
36 namespace RIFF {
37
38 //! An RIFF file class with some useful methods specific to RIFF
39
40 /*!
41 * This implements the generic TagLib::File API and additionally provides
42 * access to properties that are distinct to RIFF files, notably access
43 * to the different ID3 tags.
44 */
45
46 class TAGLIB_EXPORT File : public TagLib::File
47 {
48 public:
49 /*!
50 * Destroys this instance of the File.
51 */
52 virtual ~File();
53
54 protected:
55
56 enum Endianness { BigEndian, LittleEndian };
57
58 File(FileName file, Endianness endianness);
59 File(IOStream *stream, Endianness endianness);
60
61 /*!
62 * \return The size of the main RIFF chunk.
63 */
64 unsigned int riffSize() const;
65
66 /*!
67 * \return The number of chunks in the file.
68 */
69 unsigned int chunkCount() const;
70
71 /*!
72 * \return The offset within the file for the selected chunk number.
73 */
74 unsigned int chunkOffset(unsigned int i) const;
75
76 /*!
77 * \return The size of the chunk data.
78 */
79 unsigned int chunkDataSize(unsigned int i) const;
80
81 /*!
82 * \return The size of the padding after the chunk (can be either 0 or 1).
83 */
84 unsigned int chunkPadding(unsigned int i) const;
85
86 /*!
87 * \return The name of the specified chunk, for instance, "COMM" or "ID3 "
88 */
89 ByteVector chunkName(unsigned int i) const;
90
91 /*!
92 * Reads the chunk data from the file and returns it.
93 *
94 * \note This \e will move the read pointer for the file.
95 */
96 ByteVector chunkData(unsigned int i);
97
98 /*!
99 * Sets the data for the specified chunk to \a data.
100 *
101 * \warning This will update the file immediately.
102 */
103 void setChunkData(unsigned int i, const ByteVector &data);
104
105 /*!
106 * Sets the data for the chunk \a name to \a data. If a chunk with the
107 * given name already exists it will be overwritten, otherwise it will be
108 * created after the existing chunks.
109 *
110 * \warning This will update the file immediately.
111 */
112 void setChunkData(const ByteVector &name, const ByteVector &data);
113
114 /*!
115 * Sets the data for the chunk \a name to \a data. If a chunk with the
116 * given name already exists it will be overwritten, otherwise it will be
117 * created after the existing chunks.
118 *
119 * \note If \a alwaysCreate is true, a new chunk is created regardless of
120 * whether or not the chunk \a name exists. It should only be used for
121 * "LIST" chunks.
122 *
123 * \warning This will update the file immediately.
124 */
125 void setChunkData(const ByteVector &name, const ByteVector &data, bool alwaysCreate);
126
127 /*!
128 * Removes the specified chunk.
129 *
130 * \warning This will update the file immediately.
131 */
132 void removeChunk(unsigned int i);
133
134 /*!
135 * Removes the chunk \a name.
136 *
137 * \warning This will update the file immediately.
138 * \warning This removes all the chunks with the given name.
139 */
140 void removeChunk(const ByteVector &name);
141
142 private:
143 File(const File &);
144 File &operator=(const File &);
145
146 void read();
147 void writeChunk(const ByteVector &name, const ByteVector &data,
148 unsigned long offset, unsigned long replace = 0);
149
150 /*!
151 * Update the global RIFF size based on the current internal structure.
152 */
153 void updateGlobalSize();
154
155 class FilePrivate;
156 FilePrivate *d;
157 };
158 }
159}
160
161#endif
162