Tag Parser  6.4.0
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 
104 public:
105  Id3v2Frame();
106  Id3v2Frame(const identifierType &id, const TagValue &value, const byte group = 0, const int16 flag = 0);
107 
108  // parsing/making
109  void parse(IoUtilities::BinaryReader &reader, const uint32 version, const uint32 maximalSize = 0);
110  Id3v2FrameMaker prepareMaking(const uint32 version);
111  void make(IoUtilities::BinaryWriter &writer, const uint32 version);
112 
113  // member access
114  bool isAdditionalTypeInfoUsed() const;
115  bool isValid() const;
116  bool hasPaddingReached() const;
117  std::string frameIdString() const;
118  uint16 flag() const;
119  void setFlag(uint16 value);
120  uint32 totalSize() const;
121  uint32 dataSize() const;
122  bool toDiscardWhenUnknownAndTagIsAltered() const;
123  bool toDiscardWhenUnknownAndFileIsAltered() const;
124  bool isReadOnly() const;
125  bool isCompressed() const;
126  bool isEncrypted() const;
127  bool hasGroupInformation() const;
128  bool isUnsynchronized() const;
129  bool hasDataLengthIndicator() const;
130  byte group() const;
131  void setGroup(byte value);
132  int32 parsedVersion() const;
133  bool supportsNestedFields() const;
134 
135  // parsing helper
136  TagTextEncoding parseTextEncodingByte(byte textEncodingByte);
137  std::tuple<const char *, size_t, const char *> parseSubstring(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
138  std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings = false);
139  std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings = false);
140  void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
141  void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo);
142  void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue);
143  void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding);
144 
145  // making helper
146  byte makeTextEncodingByte(TagTextEncoding textEncoding);
147  std::size_t makeBom(char *buffer, TagTextEncoding encoding);
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 makePictureConsideringVersion(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo, byte version);
153  void makeCommentConsideringVersion(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte version);
154  void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment);
155 
156  static identifierType fieldIdFromString(const char *idString, std::size_t idStringSize = std::string::npos);
157  static std::string fieldIdToString(identifierType id);
158 
159 protected:
160  void cleared();
161 
162 private:
163  uint16 m_flag;
164  byte m_group;
165  uint32 m_parsedVersion;
166  uint32 m_dataSize;
167  uint32 m_totalSize;
168  bool m_padding;
169 };
170 
175 {
176  return id() == Id3v2FrameIds::lCover || id() == Id3v2FrameIds::sCover;
177 }
178 
182 inline bool Id3v2Frame::isValid() const
183 {
184  return !(id() == 0 || value().isEmpty() || m_padding);
185 }
186 
190 inline bool Id3v2Frame::hasPaddingReached() const
191 {
192  return m_padding;
193 }
194 
199 inline std::string Id3v2Frame::frameIdString() const
200 {
201  return idToString();
202 }
203 
207 inline uint16 Id3v2Frame::flag() const
208 {
209  return m_flag;
210 }
211 
215 inline void Id3v2Frame::setFlag(uint16 value)
216 {
217  m_flag = value;
218 }
219 
223 inline uint32 Id3v2Frame::totalSize() const
224 {
225  return m_totalSize;
226 }
227 
231 inline uint32 Id3v2Frame::dataSize() const
232 {
233  return m_dataSize;
234 }
235 
240 {
241  return m_flag & 0x8000;
242 }
243 
248 {
249  return m_flag & 0x4000;
250 }
251 
255 inline bool Id3v2Frame::isReadOnly() const
256 {
257  return m_flag & 0x2000;
258 }
259 
263 inline bool Id3v2Frame::isCompressed() const
264 {
265  return m_parsedVersion >= 4 ? m_flag & 0x8 : m_flag & 0x80;
266 }
267 
272 inline bool Id3v2Frame::isEncrypted() const
273 {
274  return m_parsedVersion >= 4 ? m_flag & 0x4 : m_flag & 0x40;
275 }
276 
281 {
282  return m_parsedVersion >= 4 ? m_flag & 0x40 : m_flag & 0x20;
283 }
284 
288 inline bool Id3v2Frame::isUnsynchronized() const
289 {
290  return m_parsedVersion >= 4 ? m_flag & 0x2 : false;
291 }
292 
297 {
298  return m_parsedVersion >= 4 ? m_flag & 0x1 : isCompressed();
299 }
300 
305 inline byte Id3v2Frame::group() const
306 {
307  return m_group;
308 }
309 
313 inline void Id3v2Frame::setGroup(byte value)
314 {
315  m_group = value;
316 }
317 
321 inline int32 Id3v2Frame::parsedVersion() const
322 {
323  return m_parsedVersion;
324 }
325 
330 {
331  return true;
332 }
333 
337 inline Id3v2Frame::identifierType Id3v2Frame::fieldIdFromString(const char *idString, std::size_t idStringSize)
338 {
339  switch(idStringSize != std::string::npos ? idStringSize : std::strlen(idString)) {
340  case 3:
341  return ConversionUtilities::BE::toUInt24(idString);
342  case 4:
343  return ConversionUtilities::BE::toUInt32(idString);
344  default:
345  throw ConversionUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
346  }
347 }
348 
353 {
354  return ConversionUtilities::interpretIntegerAsString<uint32>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
355 }
356 
357 }
358 
359 #endif // ID3V2FRAME_H
The TagValue class wraps values of different types.
Definition: tagvalue.h:64
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:174
TagFieldTraits< Id3v2Frame >::identifierType identifierType
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:255
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:215
static std::string fieldIdToString(identifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:352
Defines traits for the specified ImplementationType.
uint32 totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:223
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:329
Id3v2Frame implementationType
The implementation type is Id3v2Frame.
Definition: id3v2frame.h:97
byte group() const
Returns the group.
Definition: id3v2frame.h:305
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:22
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:296
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:263
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:288
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:280
std::string frameIdString() const
Returns the frame ID as string.
Definition: id3v2frame.h:199
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:247
bool toDiscardWhenUnknownAndTagIsAltered() const
Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered...
Definition: id3v2frame.h:239
void setGroup(byte value)
Sets the group information.
Definition: id3v2frame.h:313
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:190
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:337
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:321
uint32 dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:231
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:272
The Id3v2FrameMaker class helps making ID3v2 frames.
Definition: id3v2frame.h:23
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:182
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:207
#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