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 &);
added
removed
Frameworks/taglib/taglib/taglib/mpeg/id3v2/id3v2frame.h
