1 /***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
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. *
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. *
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 *
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 ***************************************************************************/
26 #ifndef TAGLIB_ID3V2FRAME_H
27 #define TAGLIB_ID3V2FRAME_H
30 #include "tbytevector.h"
31 #include "taglib_export.h"
42 //! ID3v2 frame implementation
45 * This class is the main ID3v2 frame implementation. In ID3v2, a tag is
46 * split between a collection of frames (which are in turn split into fields
47 * (Structure, <a href="id3v2-structure.html#4">4</a>)
48 * (<a href="id3v2-frames.html">Frames</a>). This class provides an API for
49 * gathering information about and modifying ID3v2 frames. Funtionallity
50 * specific to a given frame type is handed in one of the many subclasses.
53 class TAGLIB_EXPORT Frame
56 friend class FrameFactory;
60 * Destroys this Frame instance.
65 * Returns the Frame ID (Structure, <a href="id3v2-structure.html#4">4</a>)
66 * (Frames, <a href="id3v2-frames.html#4">4</a>)
68 ByteVector frameID() const;
71 * Returns the size of the frame.
76 * Returns the size of the frame header
78 * \deprecated This is only accurate for ID3v2.3 or ID3v2.4. Please use
79 * the call below which accepts an ID3v2 version number. In the next
80 * non-binary compatible release this will be made into a non-static
81 * member that checks the internal ID3v2 version.
83 static uint headerSize(); // BIC: remove and make non-static
86 * Returns the size of the frame header for the given ID3v2 version.
88 * \deprecated Please see the explanation above.
90 static uint headerSize(uint version); // BIC: remove and make non-static
93 * Sets the data that will be used as the frame. Since the length is not
94 * known before the frame has been parsed, this should just be a pointer to
95 * the first byte of the frame. It will determine the length internally
96 * and make that available through size().
98 void setData(const ByteVector &data);
101 * Set the text of frame in the sanest way possible. This should only be
102 * reimplemented in frames where there is some logical mapping to text.
104 * \note If the frame type supports multiple text encodings, this will not
105 * change the text encoding of the frame; the string will be converted to
106 * that frame's encoding. Please use the specific APIs of the frame types
107 * to set the encoding if that is desired.
109 virtual void setText(const String &text);
112 * This returns the textual representation of the data in the frame.
113 * Subclasses must reimplement this method to provide a string
114 * representation of the frame's data.
116 virtual String toString() const = 0;
119 * Render the frame back to its binary format in a ByteVector.
121 ByteVector render() const;
124 * Returns the text delimiter that is used between fields for the string
127 static ByteVector textDelimiter(String::Type t);
133 * Constructs an ID3v2 frame using \a data to read the header information.
134 * All other processing of \a data should be handled in a subclass.
136 * \note This need not contain anything more than a frame ID, but
137 * \e must constain at least that.
139 explicit Frame(const ByteVector &data);
142 * This creates an Frame using the header \a h.
144 * The ownership of this header will be assigned to the frame and the
145 * header will be deleted when the frame is destroyed.
150 * Returns a pointer to the frame header.
152 Header *header() const;
155 * Sets the header to \a h. If \a deleteCurrent is true, this will free
156 * the memory of the current header.
158 * The ownership of this header will be assigned to the frame and the
159 * header will be deleted when the frame is destroyed.
161 void setHeader(Header *h, bool deleteCurrent = true);
164 * Called by setData() to parse the frame data. It makes this information
165 * available through the public API.
167 void parse(const ByteVector &data);
170 * Called by parse() to parse the field data. It makes this information
171 * available through the public API. This must be overridden by the
174 virtual void parseFields(const ByteVector &data) = 0;
177 * Render the field data back to a binary format in a ByteVector. This
178 * must be overridden by subclasses.
180 virtual ByteVector renderFields() const = 0;
183 * Returns a ByteVector containing the field data given the frame data.
184 * This correctly adjusts for the header size plus any additional frame
185 * data that's specified in the frame header flags.
187 ByteVector fieldData(const ByteVector &frameData) const;
190 * Reads a String of type \a encodiong from the ByteVector \a data. If \a
191 * position is passed in it is used both as the starting point and is
192 * updated to replect the position just after the string that has been read.
193 * This is useful for reading strings sequentially.
195 String readStringField(const ByteVector &data, String::Type encoding,
199 * Checks a the list of string values to see if they can be used with the
200 * specified encoding and returns the recommended encoding.
202 static String::Type checkEncoding(const StringList &fields,
203 String::Type encoding);
206 Frame(const Frame &);
207 Frame &operator=(const Frame &);
210 friend class FramePrivate;
214 //! ID3v2 frame header implementation
217 * The ID3v2 Frame Header (Structure, <a href="id3v2-structure.html#4">4</a>)
219 * Every ID3v2::Frame has an associated header that gives some general
220 * properties of the frame and also makes it possible to identify the frame
223 * As such when reading an ID3v2 tag ID3v2::FrameFactory first creates the
224 * frame headers and then creates the appropriate Frame subclass based on
225 * the type and attaches the header.
228 class TAGLIB_EXPORT Frame::Header
232 * Construct a Frame Header based on \a data. \a data must at least
233 * contain a 4 byte frame ID, and optionally can contain flag data and the
234 * frame size. i.e. Just the frame id -- "TALB" -- is a valid value.
236 * \deprecated Please use the constructor below that accepts a version
239 Header(const ByteVector &data, bool synchSafeInts);
242 * Construct a Frame Header based on \a data. \a data must at least
243 * contain a 4 byte frame ID, and optionally can contain flag data and the
244 * frame size. i.e. Just the frame id -- "TALB" -- is a valid value.
246 * \a version should be the ID3v2 version of the tag.
248 explicit Header(const ByteVector &data, uint version = 4);
251 * Destroys this Header instance.
256 * Sets the data for the Header.
258 * \deprecated Please use the version below that accepts an ID3v2 version
261 void setData(const ByteVector &data, bool synchSafeInts);
264 * Sets the data for the Header. \a version should indicate the ID3v2
265 * version number of the tag that this frame is contained in.
267 void setData(const ByteVector &data, uint version = 4);
270 * Returns the Frame ID (Structure, <a href="id3v2-structure.html#4">4</a>)
271 * (Frames, <a href="id3v2-frames.html#4">4</a>)
273 ByteVector frameID() const;
276 * Sets the frame's ID to \a id. Only the first four bytes of \a id will
279 * \warning This method should in general be avoided. It exists simply to
280 * provide a mechanism for transforming frames from a deprecated frame type
281 * to a newer one -- i.e. TYER to TDRC from ID3v2.3 to ID3v2.4.
283 void setFrameID(const ByteVector &id);
286 * Returns the size of the frame data portion, as set when setData() was
287 * called or set explicitly via setFrameSize().
289 uint frameSize() const;
292 * Sets the size of the frame data portion.
294 void setFrameSize(uint size);
297 * Returns the ID3v2 version of the header (as passed in from the
298 * construction of the header).
300 uint version() const;
303 * Returns the size of the frame header in bytes.
305 * \deprecated Please use the version of this method that accepts a
306 * version. This is only accurate for ID3v2.3 and ID3v2.4. This will be
307 * removed in the next binary incompatible release (2.0) and will be
308 * replaced with a non-static method that checks the frame version.
313 * Returns the size of the frame header in bytes for the ID3v2 version
316 * \deprecated Please see the explanation in the version above.
318 static uint size(uint version);
321 * Returns true if the flag for tag alter preservation is set.
323 * The semantics are a little backwards from what would seem natural
324 * (setting the preservation flag to throw away the frame), but this
325 * follows the ID3v2 standard.
327 * \see setTagAlterPreservation()
329 bool tagAlterPreservation() const;
332 * Sets the flag for preservation of this frame if the tag is set. If
333 * this is set to true the frame will not be written when the tag is
336 * The semantics are a little backwards from what would seem natural
337 * (setting the preservation flag to throw away the frame), but this
338 * follows the ID3v2 standard.
340 * \see tagAlterPreservation()
342 void setTagAlterPreservation(bool discard);
345 * Returns true if the flag for file alter preservation is set.
347 * \note This flag is currently ignored internally in TagLib.
349 bool fileAlterPreservation() const;
352 * Returns true if the frame is meant to be read only.
354 * \note This flag is currently ignored internally in TagLib.
356 bool readOnly() const;
359 * Returns true if the flag for the grouping identifity is set.
361 * \note This flag is currently ignored internally in TagLib.
363 bool groupingIdentity() const;
366 * Returns true if compression is enabled for this frame.
368 * \note This flag is currently ignored internally in TagLib.
370 bool compression() const;
373 * Returns true if encryption is enabled for this frame.
375 * \note This flag is currently ignored internally in TagLib.
377 bool encryption() const;
379 #ifndef DO_NOT_DOCUMENT
380 bool unsycronisation() const;
384 * Returns true if unsynchronisation is enabled for this frame.
386 bool unsynchronisation() const;
389 * Returns true if the flag for a data length indicator is set.
391 bool dataLengthIndicator() const;
394 * Render the Header back to binary format in a ByteVector.
396 ByteVector render() const;
401 bool frameAlterPreservation() const;
404 Header(const Header &);
405 Header &operator=(const Header &);