Tag Parser  7.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(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  Id3v2Frame &m_frame;
35  uint32 m_frameId;
36  const byte m_version;
37  std::unique_ptr<char[]> m_data;
38  uint32 m_dataSize;
39  uint32 m_decompressedSize;
40  uint32 m_requiredSize;
41 };
42 
46 inline const Id3v2Frame &Id3v2FrameMaker::field() const
47 {
48  return m_frame;
49 }
50 
54 inline const std::unique_ptr<char[]> &Id3v2FrameMaker::data() const
55 {
56  return m_data;
57 }
58 
62 inline uint32 Id3v2FrameMaker::dataSize() const
63 {
64  return m_dataSize;
65 }
66 
70 inline uint32 Id3v2FrameMaker::requiredSize() const
71 {
72  return m_requiredSize;
73 }
74 
79 public:
80  typedef uint32 IdentifierType;
81  typedef byte TypeInfoType;
82 };
83 
84 class TAG_PARSER_EXPORT Id3v2Frame : public TagField<Id3v2Frame> {
85  friend class TagField<Id3v2Frame>;
86 
87 public:
88  Id3v2Frame();
89  Id3v2Frame(const IdentifierType &id, const TagValue &value, byte group = 0, uint16 flag = 0);
90 
91  // parsing/making
92  void parse(IoUtilities::BinaryReader &reader, uint32 version, uint32 maximalSize, Diagnostics &diag);
93  Id3v2FrameMaker prepareMaking(byte version, Diagnostics &diag);
94  void make(IoUtilities::BinaryWriter &writer, byte version, Diagnostics &diag);
95 
96  // member access
97  bool isAdditionalTypeInfoUsed() const;
98  bool isValid() const;
99  bool hasPaddingReached() const;
100  std::string frameIdString() const;
101  uint16 flag() const;
102  void setFlag(uint16 value);
103  uint32 totalSize() const;
104  uint32 dataSize() const;
105  bool toDiscardWhenUnknownAndTagIsAltered() const;
106  bool toDiscardWhenUnknownAndFileIsAltered() const;
107  bool isReadOnly() const;
108  bool isCompressed() const;
109  bool isEncrypted() const;
110  bool hasGroupInformation() const;
111  bool isUnsynchronized() const;
112  bool hasDataLengthIndicator() const;
113  byte group() const;
114  void setGroup(byte value);
115  uint32 parsedVersion() const;
116  bool supportsNestedFields() const;
117 
118  // parsing helper
119  TagTextEncoding parseTextEncodingByte(byte textEncodingByte, Diagnostics &diag);
120  std::tuple<const char *, size_t, const char *> parseSubstring(
121  const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
122  std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
123  std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag);
124  void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo, Diagnostics &diag);
125  void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, byte &typeInfo, Diagnostics &diag);
126  void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue, Diagnostics &diag);
127  void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, Diagnostics &diag);
128 
129  // making helper
130  byte makeTextEncodingByte(TagTextEncoding textEncoding);
131  std::size_t makeBom(char *buffer, TagTextEncoding encoding);
132  void makeString(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const std::string &value, TagTextEncoding encoding);
133  void makeEncodingAndData(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, TagTextEncoding encoding, const char *data, std::size_t m_dataSize);
134  void makeLegacyPicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo);
135  void makePicture(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &picture, byte typeInfo, byte version);
136  void makeComment(std::unique_ptr<char[]> &buffer, uint32 &bufferSize, const TagValue &comment, byte version, Diagnostics &diag);
137 
138  static IdentifierType fieldIdFromString(const char *idString, std::size_t idStringSize = std::string::npos);
139  static std::string fieldIdToString(IdentifierType id);
140 
141 private:
142  void reset();
143  uint32 m_parsedVersion;
144  uint32 m_dataSize;
145  uint32 m_totalSize;
146  uint16 m_flag;
147  byte m_group;
148  bool m_padding;
149 };
150 
155 {
156  return id() == Id3v2FrameIds::lCover || id() == Id3v2FrameIds::sCover;
157 }
158 
162 inline bool Id3v2Frame::isValid() const
163 {
164  return !(id() == 0 || value().isEmpty() || m_padding);
165 }
166 
170 inline bool Id3v2Frame::hasPaddingReached() const
171 {
172  return m_padding;
173 }
174 
179 inline std::string Id3v2Frame::frameIdString() const
180 {
181  return idToString();
182 }
183 
187 inline uint16 Id3v2Frame::flag() const
188 {
189  return m_flag;
190 }
191 
195 inline void Id3v2Frame::setFlag(uint16 value)
196 {
197  m_flag = value;
198 }
199 
203 inline uint32 Id3v2Frame::totalSize() const
204 {
205  return m_totalSize;
206 }
207 
211 inline uint32 Id3v2Frame::dataSize() const
212 {
213  return m_dataSize;
214 }
215 
220 {
221  return m_flag & 0x8000;
222 }
223 
228 {
229  return m_flag & 0x4000;
230 }
231 
235 inline bool Id3v2Frame::isReadOnly() const
236 {
237  return m_flag & 0x2000;
238 }
239 
243 inline bool Id3v2Frame::isCompressed() const
244 {
245  return m_parsedVersion >= 4 ? m_flag & 0x8 : m_flag & 0x80;
246 }
247 
252 inline bool Id3v2Frame::isEncrypted() const
253 {
254  return m_parsedVersion >= 4 ? m_flag & 0x4 : m_flag & 0x40;
255 }
256 
261 {
262  return m_parsedVersion >= 4 ? m_flag & 0x40 : m_flag & 0x20;
263 }
264 
268 inline bool Id3v2Frame::isUnsynchronized() const
269 {
270  return m_parsedVersion >= 4 ? m_flag & 0x2 : false;
271 }
272 
277 {
278  return m_parsedVersion >= 4 ? m_flag & 0x1 : isCompressed();
279 }
280 
285 inline byte Id3v2Frame::group() const
286 {
287  return m_group;
288 }
289 
293 inline void Id3v2Frame::setGroup(byte value)
294 {
295  m_group = value;
296 }
297 
301 inline uint32 Id3v2Frame::parsedVersion() const
302 {
303  return m_parsedVersion;
304 }
305 
310 {
311  return true;
312 }
313 
317 inline Id3v2Frame::IdentifierType Id3v2Frame::fieldIdFromString(const char *idString, std::size_t idStringSize)
318 {
319  switch (idStringSize != std::string::npos ? idStringSize : std::strlen(idString)) {
320  case 3:
321  return ConversionUtilities::BE::toUInt24(idString);
322  case 4:
323  return ConversionUtilities::BE::toUInt32(idString);
324  default:
325  throw ConversionUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
326  }
327 }
328 
333 {
334  return ConversionUtilities::interpretIntegerAsString<uint32>(id, Id3v2FrameIds::isLongId(id) ? 0 : 1);
335 }
336 
337 } // namespace TagParser
338 
339 #endif // TAG_PARSER_ID3V2FRAME_H
uint16 flag() const
Returns the flags.
Definition: id3v2frame.h:187
void setGroup(byte value)
Sets the group information.
Definition: id3v2frame.h:293
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition: id3v2frame.h:170
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition: id3v2frame.h:260
byte group() const
Returns the group.
Definition: id3v2frame.h:285
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition: id3v2frame.h:235
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition: id3v2frame.h:154
TAG_PARSER_EXPORT const char * version()
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition: id3v2frame.h:54
TagFieldTraits< Id3v2Frame >::IdentifierType IdentifierType
uint32 parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition: id3v2frame.h:301
static std::string fieldIdToString(IdentifierType id)
Returns the string representation for the specified id.
Definition: id3v2frame.h:332
TAG_PARSER_EXPORT const char * comment()
bool isCompressed() const
Returns whether the frame is compressed.
Definition: id3v2frame.h:243
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition: id3v2frame.h:276
bool isValid() const
Returns whether the frame is valid.
Definition: id3v2frame.h:162
bool isEmpty() const
Returns an indication whether an value is assigned.
Definition: tagvalue.h:367
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition: id3v2frame.h:309
bool isLongId(uint32 id)
Returns an indication whether the specified id is a long frame id.
Definition: id3v2frameids.h:68
bool toDiscardWhenUnknownAndTagIsAltered() const
Returns whether the frame is flaged to be discarded when it is unknown and the tag is altered...
Definition: id3v2frame.h:219
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition: id3v2frame.h:252
std::string frameIdString() const
Returns the frame ID as string.
Definition: id3v2frame.h:179
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:317
The TagField class is used by FieldMapBasedTag to store the fields.
const Id3v2Frame & field() const
Returns the associated frame.
Definition: id3v2frame.h:46
void setFlag(uint16 value)
Sets the flags.
Definition: id3v2frame.h:195
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:62
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition: id3v2frame.h:268
uint32 dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition: id3v2frame.h:211
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:22
uint32 requiredSize() const
Returns number of bytes which will be written when making the frame.
Definition: id3v2frame.h:70
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TagValue & value()
Returns the value of the current TagField.
uint32 totalSize() const
Returns the total size of the frame in bytes.
Definition: id3v2frame.h:203
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:227