Tag Parser  6.2.2
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
id3v2frame.h
Go to the documentation of this file.
1 #ifndef ID3V2FRAME_H
2 #define ID3V2FRAME_H
3 
4 #include "./id3v2frameids.h"
5 
6 #include "../generictagfield.h"
7 #include "../tagvalue.h"
8 #include "../statusprovider.h"
9 
10 #include <c++utilities/io/binaryreader.h>
11 #include <c++utilities/io/binarywriter.h>
12 #include <c++utilities/conversion/stringconversion.h>
13 
14 #include <string>
15 #include <iosfwd>
16 #include <vector>
17 
18 namespace Media
19 {
20 
21 class Id3v2Frame;
22 
24 {
25  friend class Id3v2Frame;
26 
27 public:
28  void make(IoUtilities::BinaryWriter &writer);
29  const Id3v2Frame &field() const;
30  const std::unique_ptr<char[]> &data() const;
31  uint32 dataSize() const;
32  uint32 requiredSize() const;
33 
34 private:
35  Id3v2FrameMaker(Id3v2Frame &frame, const byte version);
36  Id3v2Frame &m_frame;
37  uint32 m_frameId;
38  const byte m_version;
39  std::unique_ptr<char[]> m_data;
40  uint32 m_dataSize;
41  uint32 m_decompressedSize;
42  uint32 m_requiredSize;
43 };
44 
48 inline const Id3v2Frame &Id3v2FrameMaker::field() const
49 {
50  return m_frame;
51 }
52 
56 inline const std::unique_ptr<char[]> &Id3v2FrameMaker::data() const
57 {
58  return m_data;
59 }
60 
64 inline uint32 Id3v2FrameMaker::dataSize() const
65 {
66  return m_dataSize;
67 }
68 
72 inline uint32 Id3v2FrameMaker::requiredSize() const
73 {
74  return m_requiredSize;
75 }
76 
80 template <>
82 {
83 public:
87  typedef uint32 identifierType;
88 
92  typedef byte typeInfoType;
93 
98 };
99 
100 class TAG_PARSER_EXPORT Id3v2Frame : public TagField<Id3v2Frame>, public StatusProvider
101 {
102  friend class TagField<Id3v2Frame>;
103  friend class Id3v2FrameMaker; // FIXME: remove when making methods public in next minor release
104 
105 public:
106  Id3v2Frame();
107  Id3v2Frame(const identifierType &id, const TagValue &value, const byte group = 0, const int16 flag = 0);
108 
109  // parsing/making
110  void parse(IoUtilities::BinaryReader &reader, const uint32 version, const uint32 maximalSize = 0);
111  Id3v2FrameMaker prepareMaking(const uint32 version);
112  void make(IoUtilities::BinaryWriter &writer, const uint32 version);
113 
114  // member access
115  bool isAdditionalTypeInfoUsed() const;
116  bool isValid() const;
117  bool hasPaddingReached() const;
118  std::string frameIdString() const;
119  uint16 flag() const;
120  void setFlag(uint16 value);
121  uint32 totalSize() const;
122  uint32 dataSize() const;
123  bool toDiscardWhenUnknownAndTagIsAltered() const;
124  bool toDiscardWhenUnknownAndFileIsAltered() const;
125  bool isReadOnly() const;
126  bool isCompressed() const;
127  bool isEncrypted() const;
128  bool hasGroupInformation() const;
129  bool isUnsynchronized() const;
130  bool hasDataLengthIndicator() const;
131  byte group() const;
132  void setGroup(byte value);
133  int32 parsedVersion() const;
134  bool supportsNestedFields() const;
135 
136  // parsing helper
137  TagTextEncoding parseTextEncodingByte(byte textEncodingByte);
138  std::tuple<const char *, size_t, const char *> parseSubstring(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
139  std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
140  std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings = false);
141  void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
142  void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
143  void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue);
144  void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding);
145 
146  // making helper
147  byte makeTextEncodingByte(TagTextEncoding textEncoding);
148  void makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding);
149  void makeEncodingAndData(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t m_dataSize);
150  void makeLegacyPicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
151  void makePicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
152  void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment);
153 
154  static identifierType fieldIdFromString(const char *idString, std::size_t idStringSize = std::string::npos);
155  static std::string fieldIdToString(identifierType id);
156 
157 protected:
158  void cleared();
159 
160 private:
161  // FIXME: add to public API in next minor release
162  void makeCommentConsideringVersion(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte version);
163  std::size_t makeBom(char *buffer, TagTextEncoding encoding);
164 
165  uint16 m_flag;
166  byte m_group;
167  uint32 m_parsedVersion;
168  uint32 m_dataSize;
169  uint32 m_totalSize;
170  bool m_padding;
171 };
172 
177 {
178  return id() == Id3v2FrameIds::lCover || id() == Id3v2FrameIds::sCover;
179 }
180 
184 inline bool Id3v2Frame::isValid() const
185 {
186  return !(id() == 0 || value().isEmpty() || m_padding);
187 }
188 
192 inline bool Id3v2Frame::hasPaddingReached() const
193 {
194  return m_padding;
195 }
196 
201 inline std::string Id3v2Frame::frameIdString() const
202 {
203  return idToString();
204 }
205 
209 inline uint16 Id3v2Frame::flag() const
210 {
211  return m_flag;
212 }
213 
217 inline void Id3v2Frame::setFlag(uint16 value)
218 {
219  m_flag = value;
220 }
221 
225 inline uint32 Id3v2Frame::totalSize() const
226 {
227  return m_totalSize;
228 }
229 
233 inline uint32 Id3v2Frame::dataSize() const
234 {
235  return m_dataSize;
236 }
237 
242 {
243  return m_flag & 0x8000;
244 }
245 
250 {
251  return m_flag & 0x4000;
252 }
253 
257 inline bool Id3v2Frame::isReadOnly() const
258 {
259  return m_flag & 0x2000;
260 }
261 
265 inline bool Id3v2Frame::isCompressed() const
266 {
267  return m_parsedVersion >= 4 ? m_flag & 0x8 : m_flag & 0x80;
268 }
269 
274 inline bool Id3v2Frame::isEncrypted() const
275 {
276  return m_parsedVersion >= 4 ? m_flag & 0x4 : m_flag & 0x40;
277 }
278 
283 {
284  return m_parsedVersion >= 4 ? m_flag & 0x40 : m_flag & 0x20;
285 }
286 
290 inline bool Id3v2Frame::isUnsynchronized() const
291 {
292  return m_parsedVersion >= 4 ? m_flag & 0x2 : false;
293 }
294 
299 {
300  return m_parsedVersion >= 4 ? m_flag & 0x1 : isCompressed();
301 }
302 
307 inline byte Id3v2Frame::group() const
308 {
309  return m_group;
310 }
311 
315 inline void Id3v2Frame::setGroup(byte value)
316 {
317  m_group = value;
318 }
319 
323 inline int32 Id3v2Frame::parsedVersion() const
324 {
325  return m_parsedVersion;
326 }
327 
332 {
333  return true;
334 }
335 
339 inline Id3v2Frame::identifierType Id3v2Frame::fieldIdFromString(const char *idString, std::size_t idStringSize)
340 {
341  switch(idStringSize != std::string::npos ? idStringSize : std::strlen(idString)) {
342  case 3:
343  return ConversionUtilities::BE::toUInt24(idString);
344  case 4:
345  return ConversionUtilities::BE::toUInt32(idString);
346  default:
347  throw ConversionUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
348  }
349 }
350 
355 {
356  return ConversionUtilities::interpretIntegerAsString<uint32>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
357 }
358 
359 }
360 
361 #endif // ID3V2FRAME_H
The TagValue class wraps values of different types.
Definition: tagvalue.h:63
byte typeInfoType
The type info is stored using bytes.
Definition: id3v2frame.h:92
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition: id3v2frame.h:176
TagFieldTraits< Id3v2Frame >::identifierType identifierType
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:257
uint32 dataSize() const
Returns the size of the array returned by data().
Definition: id3v2frame.h:64
bool isLongId(uint32 id)
Returns an indication whether the specified id is a long frame id.
Definition: id3v2frameids.h:68
void setFlag(uint16 value)
Sets the flags.
Definition: id3v2frame.h:217
static std::string fieldIdToString(identifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:354
Defines traits for the specified ImplementationType.
uint32 totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:225
uint32 identifierType
Fields in an ID3 tag are identified by 32-bit unsigned integers.
Definition: id3v2frame.h:87
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition: id3v2frame.h:331
Id3v2Frame implementationType
The implementation type is Id3v2Frame.
Definition: id3v2frame.h:97
byte group() const
Returns the group.
Definition: id3v2frame.h:307
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:21
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:298
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:265
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:290
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition: id3v2frame.h:100
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition: id3v2frame.h:282
std::string frameIdString() const
Returns the frame ID as string.
Definition: id3v2frame.h:201
bool toDiscardWhenUnknownAndFileIsAltered() const
Returns whether the frame is flaged to be discarded when it is unknown and the file (but NOT the tag)...
Definition: id3v2frame.h:249
bool toDiscardWhenUnknownAndTagIsAltered() const
Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered...
Definition: id3v2frame.h:241
void setGroup(byte value)
Sets the group information.
Definition: id3v2frame.h:315
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:192
static identifierType fieldIdFromString(const char *idString, std::size_t idStringSize=std::string::npos)
Converts the specified ID string representation to an actual ID.
Definition: id3v2frame.h:339
The TagField class is used by FieldMapBasedTag to store the fields.
int32 parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition: id3v2frame.h:323
uint32 dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:233
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:274
The Id3v2FrameMaker class helps making ID3v2 frames.
Definition: id3v2frame.h:23
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:184
Contains all classes and functions of the TagInfo library.
Definition: exceptions.h:9
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition: id3v2frame.h:56
The StatusProvider class acts as a base class for objects providing status information.
uint16 flag() const
Returns the flags.
Definition: id3v2frame.h:209
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TAG_PARSER_EXPORT const char * comment()
uint32 requiredSize() const
Returns number of bytes which will be written when making the frame.
Definition: id3v2frame.h:72
TAG_PARSER_EXPORT const char * version()
const Id3v2Frame & field() const
Returns the associated frame.
Definition: id3v2frame.h:48