Tag Parser  9.1.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 TAG_PARSER_ID3V2FRAME_H
2 #define TAG_PARSER_ID3V2FRAME_H
3 
4 #include "./id3v2frameids.h"
5 
6 #include "../generictagfield.h"
7 #include "../tagvalue.h"
8 
9 #include <c++utilities/conversion/stringconversion.h>
10 #include <c++utilities/io/binaryreader.h>
11 #include <c++utilities/io/binarywriter.h>
12 
13 #include <iosfwd>
14 #include <string>
15 #include <vector>
16 
17 namespace TagParser {
18 
19 class Id3v2Frame;
20 class Diagnostics;
21 
23  friend class Id3v2Frame;
24 
25 public:
26  void make(CppUtilities::BinaryWriter &writer);
27  const Id3v2Frame &field() const;
28  const std::unique_ptr<char[]> &data() const;
29  std::uint32_t dataSize() const;
30  std::uint32_t requiredSize() const;
31 
32 private:
33  Id3v2FrameMaker(Id3v2Frame &frame, std::uint8_t version, Diagnostics &diag);
34  void makeSubstring(const TagValue &value, Diagnostics &diag, const std::string &context);
35 
36  Id3v2Frame &m_frame;
37  std::uint32_t m_frameId;
38  const std::uint8_t m_version;
39  std::unique_ptr<char[]> m_data;
40  std::uint32_t m_dataSize;
41  std::uint32_t m_decompressedSize;
42  std::uint32_t 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 std::uint32_t Id3v2FrameMaker::dataSize() const
65 {
66  return m_dataSize;
67 }
68 
72 inline std::uint32_t Id3v2FrameMaker::requiredSize() const
73 {
74  return m_requiredSize;
75 }
76 
81 public:
82  using IdentifierType = std::uint32_t;
83  using TypeInfoType = std::uint8_t;
84 };
85 
86 class TAG_PARSER_EXPORT Id3v2Frame : public TagField<Id3v2Frame> {
87  friend class TagField<Id3v2Frame>;
88  friend class Id3v2FrameMaker;
89 
90 public:
91  Id3v2Frame();
92  Id3v2Frame(const IdentifierType &id, const TagValue &value, std::uint8_t group = 0, std::uint16_t flag = 0);
93 
94  // parsing/making
95  void parse(CppUtilities::BinaryReader &reader, std::uint32_t version, std::uint32_t maximalSize, Diagnostics &diag);
96  Id3v2FrameMaker prepareMaking(std::uint8_t version, Diagnostics &diag);
97  void make(CppUtilities::BinaryWriter &writer, std::uint8_t version, Diagnostics &diag);
98 
99  // member access
100  const std::vector<TagValue> &additionalValues() const;
101  std::vector<TagValue> &additionalValues();
102  bool isAdditionalTypeInfoUsed() const;
103  bool isValid() const;
104  bool hasPaddingReached() const;
105  std::uint16_t flag() const;
106  void setFlag(std::uint16_t value);
107  std::uint32_t totalSize() const;
108  std::uint32_t dataSize() const;
109  bool toDiscardWhenUnknownAndTagIsAltered() const;
110  bool toDiscardWhenUnknownAndFileIsAltered() const;
111  bool isReadOnly() const;
112  bool isCompressed() const;
113  bool isEncrypted() const;
114  bool hasGroupInformation() const;
115  bool isUnsynchronized() const;
116  bool hasDataLengthIndicator() const;
117  std::uint8_t group() const;
118  void setGroup(std::uint8_t value);
119  std::uint32_t parsedVersion() const;
120  bool supportsNestedFields() const;
121 
122  // parsing helper
123  TagTextEncoding parseTextEncodingByte(std::uint8_t textEncodingByte, Diagnostics &diag);
124  std::tuple<const char *, std::size_t, const char *> parseSubstring(
125  const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
126  std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
127  std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
128  void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag);
129  void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag);
130  void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue, Diagnostics &diag);
131  void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, Diagnostics &diag);
132 
133  // making helper
134  static std::uint8_t makeTextEncodingByte(TagTextEncoding textEncoding);
135  static std::size_t makeBom(char *buffer, TagTextEncoding encoding);
136  static void makeLegacyPicture(
137  std::unique_ptr<char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo, Diagnostics &diag);
138  static void makePicture(std::unique_ptr<char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo,
139  std::uint8_t version, Diagnostics &diag);
140  static void makeComment(
141  std::unique_ptr<char[]> &buffer, std::uint32_t &bufferSize, const TagValue &comment, std::uint8_t version, Diagnostics &diag);
142 
143  static IdentifierType fieldIdFromString(const char *idString, std::size_t idStringSize = std::string::npos);
144  static std::string fieldIdToString(IdentifierType id);
145 
146 private:
147  void reset();
148  std::string ignoreAdditionalValuesDiagMsg() const;
149 
150  std::vector<TagValue> m_additionalValues;
151  std::uint32_t m_parsedVersion;
152  std::uint32_t m_dataSize;
153  std::uint32_t m_totalSize;
154  std::uint16_t m_flag;
155  std::uint8_t m_group;
156  bool m_padding;
157 };
158 
163 inline const std::vector<TagValue> &Id3v2Frame::additionalValues() const
164 {
165  return m_additionalValues;
166 }
167 
172 inline std::vector<TagValue> &Id3v2Frame::additionalValues()
173 {
174  return m_additionalValues;
175 }
176 
181 {
182  return id() == Id3v2FrameIds::lCover || id() == Id3v2FrameIds::sCover;
183 }
184 
188 inline bool Id3v2Frame::isValid() const
189 {
190  return !(id() == 0 || value().isEmpty() || m_padding);
191 }
192 
196 inline bool Id3v2Frame::hasPaddingReached() const
197 {
198  return m_padding;
199 }
200 
204 inline std::uint16_t Id3v2Frame::flag() const
205 {
206  return m_flag;
207 }
208 
212 inline void Id3v2Frame::setFlag(std::uint16_t value)
213 {
214  m_flag = value;
215 }
216 
220 inline std::uint32_t Id3v2Frame::totalSize() const
221 {
222  return m_totalSize;
223 }
224 
228 inline std::uint32_t Id3v2Frame::dataSize() const
229 {
230  return m_dataSize;
231 }
232 
237 {
238  return m_flag & 0x8000;
239 }
240 
245 {
246  return m_flag & 0x4000;
247 }
248 
252 inline bool Id3v2Frame::isReadOnly() const
253 {
254  return m_flag & 0x2000;
255 }
256 
260 inline bool Id3v2Frame::isCompressed() const
261 {
262  return m_parsedVersion >= 4 ? m_flag & 0x8 : m_flag & 0x80;
263 }
264 
269 inline bool Id3v2Frame::isEncrypted() const
270 {
271  return m_parsedVersion >= 4 ? m_flag & 0x4 : m_flag & 0x40;
272 }
273 
278 {
279  return m_parsedVersion >= 4 ? m_flag & 0x40 : m_flag & 0x20;
280 }
281 
285 inline bool Id3v2Frame::isUnsynchronized() const
286 {
287  return m_parsedVersion >= 4 ? m_flag & 0x2 : false;
288 }
289 
294 {
295  return m_parsedVersion >= 4 ? m_flag & 0x1 : isCompressed();
296 }
297 
302 inline std::uint8_t Id3v2Frame::group() const
303 {
304  return m_group;
305 }
306 
310 inline void Id3v2Frame::setGroup(std::uint8_t value)
311 {
312  m_group = value;
313 }
314 
318 inline std::uint32_t Id3v2Frame::parsedVersion() const
319 {
320  return m_parsedVersion;
321 }
322 
327 {
328  return true;
329 }
330 
334 inline Id3v2Frame::IdentifierType Id3v2Frame::fieldIdFromString(const char *idString, std::size_t idStringSize)
335 {
336  switch (idStringSize != std::string::npos ? idStringSize : std::strlen(idString)) {
337  case 3:
338  return CppUtilities::BE::toUInt24(idString);
339  case 4:
340  return CppUtilities::BE::toUInt32(idString);
341  default:
342  throw CppUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
343  }
344 }
345 
350 {
351  return CppUtilities::interpretIntegerAsString<std::uint32_t>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
352 }
353 
354 } // namespace TagParser
355 
356 #endif // TAG_PARSER_ID3V2FRAME_H
TagParser::Id3v2Frame::toDiscardWhenUnknownAndFileIsAltered
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:244
TagParser::Id3v2Frame::setFlag
void setFlag(std::uint16_t value)
Sets the flags.
Definition: id3v2frame.h:212
TagParser::TagFieldTraits< Id3v2Frame >::TypeInfoType
std::uint8_t TypeInfoType
Definition: id3v2frame.h:83
TagParser::Id3v2FrameIds::lCover
Definition: id3v2frameids.h:23
TagParser::Id3v2Frame
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition: id3v2frame.h:86
TagParser::TagFieldTraits
Defines traits for the specified ImplementationType.
Definition: generictagfield.h:16
TagParser::TagFieldTraits< Id3v2Frame >::IdentifierType
std::uint32_t IdentifierType
Definition: id3v2frame.h:82
TagParser::TagTextEncoding
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:25
TagParser::Id3v2FrameMaker
The Id3v2FrameMaker class helps making ID3v2 frames. It allows to calculate the required size.
Definition: id3v2frame.h:22
TagParser::Id3v2Frame::isAdditionalTypeInfoUsed
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition: id3v2frame.h:180
id3v2frameids.h
TagParser::Id3v2Frame::hasPaddingReached
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:196
TagParser::Id3v2Frame::hasGroupInformation
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition: id3v2frame.h:277
TagParser::Id3v2Frame::additionalValues
const std::vector< TagValue > & additionalValues() const
Returns additional values.
Definition: id3v2frame.h:163
TagParser::Id3v2Frame::parsedVersion
std::uint32_t parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition: id3v2frame.h:318
TagParser::Id3v2Frame::fieldIdToString
static std::string fieldIdToString(IdentifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:349
TagParser::Id3v2FrameIds::isLongId
constexpr bool isLongId(std::uint32_t id)
Returns an indication whether the specified id is a long frame id.
Definition: id3v2frameids.h:71
TagParser::VorbisCommentIds::version
constexpr const TAG_PARSER_EXPORT char * version()
Definition: vorbiscommentids.h:33
TagParser::Diagnostics
The Diagnostics class is a container for DiagMessage.
Definition: diagnostics.h:156
TagParser::Id3v2FrameIds::sCover
Definition: id3v2frameids.h:49
TagParser
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TagParser::Id3v2FrameMaker::requiredSize
std::uint32_t requiredSize() const
Returns number of bytes which will be written when making the frame.
Definition: id3v2frame.h:72
TagParser::TagField::id
const IdentifierType & id() const
Returns the id of the current TagField.
Definition: generictagfield.h:115
TagParser::Id3v2Frame::isEncrypted
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:269
TagParser::Id3v2Frame::hasDataLengthIndicator
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:293
TagParser::Id3v2Frame::isValid
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:188
TagParser::Id3v2Frame::toDiscardWhenUnknownAndTagIsAltered
bool toDiscardWhenUnknownAndTagIsAltered() const
Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered.
Definition: id3v2frame.h:236
TagParser::TagField
The TagField class is used by FieldMapBasedTag to store the fields.
Definition: generictagfield.h:8
TagParser::Id3v2Frame::supportsNestedFields
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition: id3v2frame.h:326
TagParser::TagValue::isEmpty
bool isEmpty() const
Returns whether an empty value is assigned.
Definition: tagvalue.h:449
TagParser::Id3v2Frame::isCompressed
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:260
TagParser::TagField::value
TagValue & value()
Returns the value of the current TagField.
Definition: generictagfield.h:144
TagParser::Id3v2Frame::fieldIdFromString
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:334
TagParser::Id3v2Frame::totalSize
std::uint32_t totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:220
TagParser::Id3v2FrameMaker::dataSize
std::uint32_t dataSize() const
Returns the size of the array returned by data().
Definition: id3v2frame.h:64
TagParser::Id3v2Frame::dataSize
std::uint32_t dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:228
TagParser::Id3v2Frame::setGroup
void setGroup(std::uint8_t value)
Sets the group information.
Definition: id3v2frame.h:310
TagParser::TagValue
The TagValue class wraps values of different types. It is meant to be assigned to a tag field.
Definition: tagvalue.h:75
TagParser::MatroskaTagIds::comment
constexpr const TAG_PARSER_EXPORT char * comment()
Definition: matroskatagid.h:309
TagParser::Id3v2Frame::isUnsynchronized
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:285
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TagParser::Id3v2FrameMaker::data
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition: id3v2frame.h:56
TagParser::Id3v2Frame::flag
std::uint16_t flag() const
Returns the flags.
Definition: id3v2frame.h:204
TagParser::Id3v2Frame::isReadOnly
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:252
TagParser::TagField::IdentifierType
typename TagFieldTraits< ImplementationType >::IdentifierType IdentifierType
Definition: generictagfield.h:34
TagParser::Id3v2Frame::group
std::uint8_t group() const
Returns the group.
Definition: id3v2frame.h:302
TagParser::Id3v2FrameMaker::field
const Id3v2Frame & field() const
Returns the associated frame.
Definition: id3v2frame.h:48