Tag Parser  10.0.1
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(std::string_view idString);
144  static std::string fieldIdToString(IdentifierType id);
145 
146 private:
147  void internallyClearValue();
148  void internallyClearFurtherData();
149  std::string ignoreAdditionalValuesDiagMsg() const;
150 
151  std::vector<TagValue> m_additionalValues;
152  std::uint32_t m_parsedVersion;
153  std::uint32_t m_dataSize;
154  std::uint32_t m_totalSize;
155  std::uint16_t m_flag;
156  std::uint8_t m_group;
157  bool m_padding;
158 };
159 
164 inline const std::vector<TagValue> &Id3v2Frame::additionalValues() const
165 {
166  return m_additionalValues;
167 }
168 
173 inline std::vector<TagValue> &Id3v2Frame::additionalValues()
174 {
175  return m_additionalValues;
176 }
177 
182 {
183  return id() == Id3v2FrameIds::lCover || id() == Id3v2FrameIds::sCover;
184 }
185 
189 inline bool Id3v2Frame::isValid() const
190 {
191  return !(id() == 0 || value().isEmpty() || m_padding);
192 }
193 
197 inline bool Id3v2Frame::hasPaddingReached() const
198 {
199  return m_padding;
200 }
201 
205 inline std::uint16_t Id3v2Frame::flag() const
206 {
207  return m_flag;
208 }
209 
213 inline void Id3v2Frame::setFlag(std::uint16_t value)
214 {
215  m_flag = value;
216 }
217 
221 inline std::uint32_t Id3v2Frame::totalSize() const
222 {
223  return m_totalSize;
224 }
225 
229 inline std::uint32_t Id3v2Frame::dataSize() const
230 {
231  return m_dataSize;
232 }
233 
238 {
239  return m_flag & 0x8000;
240 }
241 
246 {
247  return m_flag & 0x4000;
248 }
249 
253 inline bool Id3v2Frame::isReadOnly() const
254 {
255  return m_flag & 0x2000;
256 }
257 
261 inline bool Id3v2Frame::isCompressed() const
262 {
263  return m_parsedVersion >= 4 ? m_flag & 0x8 : m_flag & 0x80;
264 }
265 
270 inline bool Id3v2Frame::isEncrypted() const
271 {
272  return m_parsedVersion >= 4 ? m_flag & 0x4 : m_flag & 0x40;
273 }
274 
279 {
280  return m_parsedVersion >= 4 ? m_flag & 0x40 : m_flag & 0x20;
281 }
282 
286 inline bool Id3v2Frame::isUnsynchronized() const
287 {
288  return m_parsedVersion >= 4 ? m_flag & 0x2 : false;
289 }
290 
295 {
296  return m_parsedVersion >= 4 ? m_flag & 0x1 : isCompressed();
297 }
298 
303 inline std::uint8_t Id3v2Frame::group() const
304 {
305  return m_group;
306 }
307 
311 inline void Id3v2Frame::setGroup(std::uint8_t value)
312 {
313  m_group = value;
314 }
315 
319 inline std::uint32_t Id3v2Frame::parsedVersion() const
320 {
321  return m_parsedVersion;
322 }
323 
328 {
329  return true;
330 }
331 
336 {
337  switch (idString.size()) {
338  case 3:
339  return CppUtilities::BE::toUInt24(idString.data());
340  case 4:
341  return CppUtilities::BE::toUInt32(idString.data());
342  default:
343  throw CppUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
344  }
345 }
346 
351 {
352  return CppUtilities::interpretIntegerAsString<std::uint32_t>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
353 }
354 
355 } // namespace TagParser
356 
357 #endif // TAG_PARSER_ID3V2FRAME_H
The Diagnostics class is a container for DiagMessage.
Definition: diagnostics.h:156
The Id3v2FrameMaker class helps making ID3v2 frames.
Definition: id3v2frame.h:22
std::uint32_t dataSize() const
Returns the size of the array returned by data().
Definition: id3v2frame.h:64
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition: id3v2frame.h:56
std::uint32_t requiredSize() const
Returns number of bytes which will be written when making the frame.
Definition: id3v2frame.h:72
const Id3v2Frame & field() const
Returns the associated frame.
Definition: id3v2frame.h:48
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition: id3v2frame.h:86
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:270
std::uint32_t dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:229
std::uint32_t parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition: id3v2frame.h:319
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:253
static IdentifierType fieldIdFromString(std::string_view idString)
Converts the specified ID string representation to an actual ID.
Definition: id3v2frame.h:335
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition: id3v2frame.h:327
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:294
const std::vector< TagValue > & additionalValues() const
Returns additional values.
Definition: id3v2frame.h:164
bool toDiscardWhenUnknownAndFileIsAltered() const
Returns whether the frame is flagged to be discarded when it is unknown and the file (but NOT the tag...
Definition: id3v2frame.h:245
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition: id3v2frame.h:278
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition: id3v2frame.h:181
std::uint16_t flag() const
Returns the flags.
Definition: id3v2frame.h:205
void setGroup(std::uint8_t value)
Sets the group information.
Definition: id3v2frame.h:311
bool toDiscardWhenUnknownAndTagIsAltered() const
Returns whether the frame is flagged to be discarded when it is unknown and the tag is altered.
Definition: id3v2frame.h:237
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:286
std::uint32_t totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:221
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:261
static std::string fieldIdToString(IdentifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:350
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:197
void setFlag(std::uint16_t value)
Sets the flags.
Definition: id3v2frame.h:213
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:189
std::uint8_t group() const
Returns the group.
Definition: id3v2frame.h:303
Defines traits for the specified ImplementationType.
The TagField class is used by FieldMapBasedTag to store the fields.
typename TagFieldTraits< Id3v2Frame >::IdentifierType IdentifierType
const IdentifierType & id() const
Returns the id of the current TagField.
TagValue & value()
Returns the value of the current TagField.
The TagValue class wraps values of different types.
Definition: tagvalue.h:95
bool isEmpty() const
Returns whether no or an empty value is assigned.
Definition: tagvalue.h:527
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
constexpr bool isLongId(std::uint32_t id)
Returns an indication whether the specified id is a long frame id.
Definition: id3v2frameids.h:85
constexpr TAG_PARSER_EXPORT std::string_view comment()
constexpr TAG_PARSER_EXPORT std::string_view version()
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:10
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:28