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_ID3V2HEADER_H
27#define TAGLIB_ID3V2HEADER_H
28
29#include "tbytevector.h"
30#include "taglib_export.h"
31
32namespace TagLib {
33
34 namespace ID3v2 {
35
36 //! An implementation of ID3v2 headers
37
38 /*!
39 * This class implements ID3v2 headers. It attempts to follow, both
40 * semantically and programmatically, the structure specified in
41 * the ID3v2 standard. The API is based on the properties of ID3v2 headers
42 * specified there. If any of the terms used in this documentation are
43 * unclear please check the specification in the linked section.
44 * (Structure, <a href="id3v2-structure.html#3.1">3.1</a>)
45 */
46
47 class TAGLIB_EXPORT Header
48 {
49 public:
50 /*!
51 * Constructs an empty ID3v2 header.
52 */
53 Header();
54
55 /*!
56 * Constructs an ID3v2 header based on \a data. parse() is called
57 * immediately.
58 */
59 Header(const ByteVector &data);
60
61 /*!
62 * Destroys the header.
63 */
64 virtual ~Header();
65
66 /*!
67 * Returns the major version number. (Note: This is the 4, not the 2 in
68 * ID3v2.4.0. The 2 is implied.)
69 */
70 unsigned int majorVersion() const;
71
72 /*!
73 * Set the the major version number to \a version. (Note: This is
74 * the 4, not the 2 in ID3v2.4.0. The 2 is implied.)
75 * \see majorVersion()
76 *
77 * \note This is used by the internal parser; this will not change the
78 * version which is written and in general should not be called by API
79 * users.
80 */
81 void setMajorVersion(unsigned int version);
82
83 /*!
84 * Returns the revision number. (Note: This is the 0, not the 4 in
85 * ID3v2.4.0. The 2 is implied.)
86 */
87 unsigned int revisionNumber() const;
88
89 /*!
90 * Returns true if unsynchronisation has been applied to all frames.
91 */
92 bool unsynchronisation() const;
93
94 /*!
95 * Returns true if an extended header is present in the tag.
96 */
97 bool extendedHeader() const;
98
99 /*!
100 * Returns true if the experimental indicator flag is set.
101 */
102 bool experimentalIndicator() const;
103
104 /*!
105 * Returns true if a footer is present in the tag.
106 */
107 bool footerPresent() const;
108 /*!
109 * Returns the tag size in bytes. This is the size of the frame content.
110 * The size of the \e entire tag will be this plus the header size (10
111 * bytes) and, if present, the footer size (potentially another 10 bytes).
112 *
113 * \note This is the value as read from the header to which TagLib attempts
114 * to provide an API to; it was not a design decision on the part of TagLib
115 * to not include the mentioned portions of the tag in the \e size.
116 *
117 * \see completeTagSize()
118 */
119 unsigned int tagSize() const;
120
121 /*!
122 * Returns the tag size, including the header and, if present, the footer
123 * size.
124 *
125 * \see tagSize()
126 */
127 unsigned int completeTagSize() const;
128
129 /*!
130 * Set the tag size to \a s.
131 * \see tagSize()
132 */
133 void setTagSize(unsigned int s);
134
135 /*!
136 * Returns the size of the header. Presently this is always 10 bytes.
137 */
138 static unsigned int size();
139
140 /*!
141 * Returns the string used to identify and ID3v2 tag inside of a file.
142 * Presently this is always "ID3".
143 */
144 static ByteVector fileIdentifier();
145
146 /*!
147 * Sets the data that will be used as the header. 10 bytes, starting from
148 * the beginning of \a data are used.
149 */
150 void setData(const ByteVector &data);
151
152 /*!
153 * Renders the Header back to binary format.
154 */
155 ByteVector render() const;
156
157 protected:
158 /*!
159 * Called by setData() to parse the header data. It makes this information
160 * available through the public API.
161 */
162 void parse(const ByteVector &data);
163
164 private:
165 Header(const Header &);
166 Header &operator=(const Header &);
167
168 class HeaderPrivate;
169 HeaderPrivate *d;
170 };
171
172 }
173}
174
175#endif
176