Tag Parser  8.0.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(IoUtilities::BinaryWriter &writer);
27  const Id3v2Frame &field() const;
28  const std::unique_ptr<char[]> &data() const;
29  uint32 dataSize() const;
30  uint32 requiredSize() const;
31 
32 private:
33  Id3v2FrameMaker(Id3v2Frame &frame, byte version, Diagnostics &diag);
34  void makeSubstring(const TagValue &value, Diagnostics &diag, const std::string &context);
35 
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 
81 public:
82  using IdentifierType = uint32;
83  using TypeInfoType = byte;
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, byte group = 0, uint16 flag = 0);
93 
94  // parsing/making
95  void parse(IoUtilities::BinaryReader &reader, uint32 version, uint32 maximalSize, Diagnostics &diag);
96  Id3v2FrameMaker prepareMaking(byte version, Diagnostics &diag);
97  void make(IoUtilities::BinaryWriter &writer, byte 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  uint16 flag() const;
106  void setFlag(uint16 value);
107  uint32 totalSize() const;
108  uint32 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  byte group() const;
118  void setGroup(byte value);
119  uint32 parsedVersion() const;
120  bool supportsNestedFields() const;
121 
122  // parsing helper
123  TagTextEncoding parseTextEncodingByte(byte 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, byte &typeInfo, Diagnostics &diag);
129  void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &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 byte makeTextEncodingByte(TagTextEncoding textEncoding);
135  static std::size_t makeBom(char *buffer, TagTextEncoding encoding);
136  static void makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding);
137  static void makeEncodingAndData(
138  std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t m_dataSize);
139  static void makeLegacyPicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
140  static void makePicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo, byte version);
141  static void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte 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  uint32 m_parsedVersion;
152  uint32 m_dataSize;
153  uint32 m_totalSize;
154  uint16 m_flag;
155  byte 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 uint16 Id3v2Frame::flag() const
205 {
206  return m_flag;
207 }
208 
212 inline void Id3v2Frame::setFlag(uint16 value)
213 {
214  m_flag = value;
215 }
216 
220 inline uint32 Id3v2Frame::totalSize() const
221 {
222  return m_totalSize;
223 }
224 
228 inline uint32 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 byte Id3v2Frame::group() const
303 {
304  return m_group;
305 }
306 
310 inline void Id3v2Frame::setGroup(byte value)
311 {
312  m_group = value;
313 }
314 
318 inline uint32 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 ConversionUtilities::BE::toUInt24(idString);
339  case 4:
340  return ConversionUtilities::BE::toUInt32(idString);
341  default:
342  throw ConversionUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
343  }
344 }
345 
350 {
351  return ConversionUtilities::interpretIntegerAsString<uint32>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
352 }
353 
354 } // namespace TagParser
355 
356 #endif // TAG_PARSER_ID3V2FRAME_H
uint16 flag() const
Returns the flags.
Definition: id3v2frame.h:204
void setGroup(byte value)
Sets the group information.
Definition: id3v2frame.h:310
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:196
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition: id3v2frame.h:277
byte group() const
Returns the group.
Definition: id3v2frame.h:302
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:252
constexpr TAG_PARSER_EXPORT const char * version()
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition: id3v2frame.h:180
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition: id3v2frame.h:56
Defines traits for the specified ImplementationType.
constexpr bool isLongId(uint32 id)
Returns an indication whether the specified id is a long frame id.
Definition: id3v2frameids.h:69
uint32 parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition: id3v2frame.h:318
static std::string fieldIdToString(IdentifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:349
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:260
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:293
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:188
const std::vector< TagValue > & additionalValues() const
Returns additional values.
Definition: id3v2frame.h:163
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition: id3v2frame.h:86
bool isEmpty() const
Returns an indication whether an value is assigned.
Definition: tagvalue.h:389
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition: id3v2frame.h:326
constexpr TAG_PARSER_EXPORT const char * comment()
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
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:269
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
The Id3v2FrameMaker class helps making ID3v2 frames.
Definition: id3v2frame.h:22
The TagField class is used by FieldMapBasedTag to store the fields.
const Id3v2Frame & field() const
Returns the associated frame.
Definition: id3v2frame.h:48
void setFlag(uint16 value)
Sets the flags.
Definition: id3v2frame.h:212
typename TagFieldTraits< ImplementationType >::IdentifierType IdentifierType
const IdentifierType & id() const
Returns the id of the current TagField.
uint32 dataSize() const
Returns the size of the array returned by data().
Definition: id3v2frame.h:64
The TagValue class wraps values of different types.
Definition: tagvalue.h:65
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:285
uint32 dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:228
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:24
uint32 requiredSize() const
Returns number of bytes which will be written when making the frame.
Definition: id3v2frame.h:72
Contains all classes and functions of the TagInfo library.
Definition: aaccodebook.h:9
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
The Diagnostics class is a container for DiagMessage.
Definition: diagnostics.h:156
TagValue & value()
Returns the value of the current TagField.
uint32 totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:220
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