Tag Parser: id3/id3v2frame.h Source File

Tag Parser 12.5.3 C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags

Loading...
Searching...
No Matches
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
17namespace TagParser {
18
19class Id3v2Frame;
20class Diagnostics;
21
22 class TAG_PARSER_EXPORT Id3v2FrameMaker {
23 friend class Id3v2Frame;
24
25public:
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
32private:
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
80 template <> class TAG_PARSER_EXPORT TagFieldTraits<Id3v2Frame> {
81public:
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
90public:
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
146private:
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
181 inline bool Id3v2Frame::isAdditionalTypeInfoUsed() const
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
237 inline bool Id3v2Frame::toDiscardWhenUnknownAndTagIsAltered() const
238{
239 return m_flag & 0x8000;
240}
241
245 inline bool Id3v2Frame::toDiscardWhenUnknownAndFileIsAltered() const
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
278 inline bool Id3v2Frame::hasGroupInformation() const
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
294 inline bool Id3v2Frame::hasDataLengthIndicator() const
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
327 inline bool Id3v2Frame::supportsNestedFields() const
328{
329 return true;
330}
331
335 inline Id3v2Frame::IdentifierType Id3v2Frame::fieldIdFromString(std::string_view idString)
336{
337 switch (idString.size()) {
338 case 3:
339 return CppUtilities::BE::toUInt24(idString.data());
340 case 4:
341 return CppUtilities::BE::toInt<std::uint32_t>(idString.data());
342 default:
343 throw CppUtilities::ConversionException("ID3v2 ID must be 3 or 4 chars");
344 }
345}
346
350 inline std::string Id3v2Frame::fieldIdToString(Id3v2Frame::IdentifierType id)
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
TagParser::Diagnostics
The Diagnostics class is a container for DiagMessage.
Definition diagnostics.h:156
TagParser::Id3v2FrameMaker::dataSize
std::uint32_t dataSize() const
Returns the size of the array returned by data().
Definition id3v2frame.h:64
TagParser::Id3v2FrameMaker::data
const std::unique_ptr< char[]> & data() const
Returns the frame data.
Definition id3v2frame.h:56
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::Id3v2FrameMaker::field
const Id3v2Frame & field() const
Returns the associated frame.
Definition id3v2frame.h:48
TagParser::Id3v2FrameMaker::make
void make(CppUtilities::BinaryWriter &writer)
Saves the frame (specified when constructing the object) using the specified writer.
Definition id3v2frame.cpp:834
TagParser::Id3v2FrameMaker::Id3v2Frame
friend class Id3v2Frame
Definition id3v2frame.h:23
TagParser::Id3v2Frame
The Id3v2Frame class is used by Id3v2Tag to store the fields.
Definition id3v2frame.h:86
TagParser::Id3v2Frame::isEncrypted
bool isEncrypted() const
Returns whether the frame is encrypted.
Definition id3v2frame.h:270
TagParser::Id3v2Frame::makeBom
static std::size_t makeBom(char *buffer, TagTextEncoding encoding)
Writes the BOM for the specified encoding to the specified buffer.
Definition id3v2frame.cpp:1127
TagParser::Id3v2Frame::dataSize
std::uint32_t dataSize() const
Returns the size of the data stored in the frame in bytes.
Definition id3v2frame.h:229
TagParser::Id3v2Frame::makeTextEncodingByte
static std::uint8_t makeTextEncodingByte(TagTextEncoding textEncoding)
Returns a text encoding byte for the specified textEncoding.
Definition id3v2frame.cpp:888
TagParser::Id3v2Frame::parsedVersion
std::uint32_t parsedVersion() const
Returns the version of the frame (read when parsing the frame).
Definition id3v2frame.h:319
TagParser::Id3v2Frame::isReadOnly
bool isReadOnly() const
Returns whether the frame is flagged as read-only.
Definition id3v2frame.h:253
TagParser::Id3v2Frame::parseString
std::string parseString(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
Parses a substring from the specified buffer.
Definition id3v2frame.cpp:991
TagParser::Id3v2Frame::parseBom
void parseBom(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, Diagnostics &diag)
Parses a byte order mark from the specified buffer.
Definition id3v2frame.cpp:1015
TagParser::Id3v2Frame::makeComment
static void makeComment(std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &comment, std::uint8_t version, Diagnostics &diag)
Writes the specified comment to the specified buffer.
Definition id3v2frame.cpp:1283
TagParser::Id3v2Frame::fieldIdFromString
static IdentifierType fieldIdFromString(std::string_view idString)
Converts the specified ID string representation to an actual ID.
Definition id3v2frame.h:335
TagParser::Id3v2Frame::parseLegacyPicture
void parseLegacyPicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag)
Parses the ID3v2.2 picture from the specified buffer.
Definition id3v2frame.cpp:1041
TagParser::Id3v2Frame::parsePicture
void parsePicture(const char *buffer, std::size_t maxSize, TagValue &tagValue, std::uint8_t &typeInfo, Diagnostics &diag)
Parses the ID3v2.3 picture from the specified buffer.
Definition id3v2frame.cpp:1067
TagParser::Id3v2Frame::parse
void parse(CppUtilities::BinaryReader &reader, std::uint32_t version, std::uint32_t maximalSize, Diagnostics &diag)
Parses a frame from the stream read using the specified reader.
Definition id3v2frame.cpp:151
TagParser::Id3v2Frame::supportsNestedFields
bool supportsNestedFields() const
Returns whether nested fields are supported.
Definition id3v2frame.h:327
TagParser::Id3v2Frame::hasDataLengthIndicator
bool hasDataLengthIndicator() const
Returns whether the frame has a data length indicator.
Definition id3v2frame.h:294
TagParser::Id3v2Frame::additionalValues
const std::vector< TagValue > & additionalValues() const
Returns additional values.
Definition id3v2frame.h:164
TagParser::Id3v2Frame::toDiscardWhenUnknownAndFileIsAltered
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
TagParser::Id3v2Frame::parseSubstring
std::tuple< const char *, std::size_t, const char * > parseSubstring(const char *buffer, std::size_t maxSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
Parses a substring from the specified buffer.
Definition id3v2frame.cpp:918
TagParser::Id3v2Frame::hasGroupInformation
bool hasGroupInformation() const
Returns whether the frame contains group information.
Definition id3v2frame.h:278
TagParser::Id3v2Frame::isAdditionalTypeInfoUsed
bool isAdditionalTypeInfoUsed() const
Returns whether the instance uses the additional type info.
Definition id3v2frame.h:181
TagParser::Id3v2Frame::flag
std::uint16_t flag() const
Returns the flags.
Definition id3v2frame.h:205
TagParser::Id3v2Frame::setGroup
void setGroup(std::uint8_t value)
Sets the group information.
Definition id3v2frame.h:311
TagParser::Id3v2Frame::toDiscardWhenUnknownAndTagIsAltered
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
TagParser::Id3v2Frame::Id3v2Frame
Id3v2Frame()
Constructs a new Id3v2Frame.
Definition id3v2frame.cpp:40
TagParser::Id3v2Frame::isUnsynchronized
bool isUnsynchronized() const
Returns whether the frame is unsynchronized.
Definition id3v2frame.h:286
TagParser::Id3v2Frame::totalSize
std::uint32_t totalSize() const
Returns the total size of the frame in bytes.
Definition id3v2frame.h:221
TagParser::Id3v2Frame::isCompressed
bool isCompressed() const
Returns whether the frame is compressed.
Definition id3v2frame.h:261
TagParser::Id3v2Frame::makePicture
static void makePicture(std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo, std::uint8_t version, Diagnostics &diag)
Writes the specified picture to the specified buffer.
Definition id3v2frame.cpp:1214
TagParser::Id3v2Frame::fieldIdToString
static std::string fieldIdToString(IdentifierType id)
Returns the string representation for the specified id.
Definition id3v2frame.h:350
TagParser::Id3v2Frame::parseTextEncodingByte
TagTextEncoding parseTextEncodingByte(std::uint8_t textEncodingByte, Diagnostics &diag)
Returns the text encoding for the specified textEncodingByte.
Definition id3v2frame.cpp:867
TagParser::Id3v2Frame::prepareMaking
Id3v2FrameMaker prepareMaking(std::uint8_t version, Diagnostics &diag)
Prepares making.
Definition id3v2frame.cpp:423
TagParser::Id3v2Frame::parseComment
void parseComment(const char *buffer, std::size_t maxSize, TagValue &tagValue, Diagnostics &diag)
Parses the comment/unsynchronized lyrics from the specified buffer.
Definition id3v2frame.cpp:1101
TagParser::Id3v2Frame::makeLegacyPicture
static void makeLegacyPicture(std::unique_ptr< char[]> &buffer, std::uint32_t &bufferSize, const TagValue &picture, std::uint8_t typeInfo, Diagnostics &diag)
Writes the specified picture to the specified buffer (ID3v2.2 compatible).
Definition id3v2frame.cpp:1144
TagParser::Id3v2Frame::parseWideString
std::u16string parseWideString(const char *buffer, std::size_t dataSize, TagTextEncoding &encoding, bool addWarnings, Diagnostics &diag)
Parses a substring from the specified buffer.
Definition id3v2frame.cpp:1003
TagParser::Id3v2Frame::hasPaddingReached
bool hasPaddingReached() const
Returns whether the padding has reached.
Definition id3v2frame.h:197
TagParser::Id3v2Frame::setFlag
void setFlag(std::uint16_t value)
Sets the flags.
Definition id3v2frame.h:213
TagParser::Id3v2Frame::make
void make(CppUtilities::BinaryWriter &writer, std::uint8_t version, Diagnostics &diag)
Writes the frame to a stream using the specified writer and the specified ID3v2 version.
Definition id3v2frame.cpp:436
TagParser::Id3v2Frame::Id3v2FrameMaker
friend class Id3v2FrameMaker
Definition id3v2frame.h:88
TagParser::Id3v2Frame::isValid
bool isValid() const
Returns whether the frame is valid.
Definition id3v2frame.h:189
TagParser::Id3v2Frame::group
std::uint8_t group() const
Returns the group.
Definition id3v2frame.h:303
TagParser::TagFieldTraits< Id3v2Frame >::IdentifierType
std::uint32_t IdentifierType
Definition id3v2frame.h:82
TagParser::TagFieldTraits< Id3v2Frame >::TypeInfoType
std::uint8_t TypeInfoType
Definition id3v2frame.h:83
TagParser::TagFieldTraits
Defines traits for the specified ImplementationType.
Definition generictagfield.h:16
TagParser::TagField< Id3v2Frame >::TagField
TagField()
Definition generictagfield.h:84
TagParser::TagField< Id3v2Frame >::IdentifierType
typename TagFieldTraits< Id3v2Frame >::IdentifierType IdentifierType
Definition generictagfield.h:33
TagParser::TagField< Id3v2Frame >::typeInfo
const TypeInfoType & typeInfo() const
Definition generictagfield.h:188
TagParser::TagField< Id3v2Frame >::id
IdentifierType & id()
Definition generictagfield.h:116
TagParser::TagField< Id3v2Frame >::value
TagValue & value()
Definition generictagfield.h:156
TagParser::TagValue
The TagValue class wraps values of different types.
Definition tagvalue.h:147
TagParser::TagValue::isEmpty
bool isEmpty() const
Returns whether no or an empty value is assigned.
Definition tagvalue.h:490
generictagfield.h
TAG_PARSER_EXPORT
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
Definition global.h:14
id3v2frameids.h
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:118
TagParser::Id3v2FrameIds::lCover
@ lCover
Definition id3v2frameids.h:32
TagParser::Id3v2FrameIds::sCover
@ sCover
Definition id3v2frameids.h:80
TagParser
Contains all classes and functions of the TagInfo library.
Definition aaccodebook.h:10
TagParser::TagTextEncoding
TagTextEncoding
Specifies the text encoding.
Definition tagvalue.h:29
tagvalue.h