Tag Parser  6.5.1
C++ library for reading and writing MP4 (iTunes), ID3, Vorbis, Opus, FLAC and Matroska tags
tag.h
Go to the documentation of this file.
1 #ifndef TAG_H
2 #define TAG_H
3 
4 #include "./statusprovider.h"
5 #include "./tagvalue.h"
6 #include "./tagtarget.h"
7 
8 #include <c++utilities/conversion/types.h>
9 #include <c++utilities/io/binaryreader.h>
10 
11 #include <type_traits>
12 #include <string>
13 
14 namespace Media {
15 
21 enum class TagType : unsigned int
22 {
23  Unspecified = 0x00,
24  Id3v1Tag = 0x01,
25  Id3v2Tag = 0x02,
26  Mp4Tag = 0x04,
27  MatroskaTag = 0x08,
28  VorbisComment = 0x10,
29  OggVorbisComment = 0x20
30 };
31 
42 enum class KnownField : unsigned int
43 {
44  Invalid = static_cast<unsigned int>(-1),
45  Title = 0,
46  Album,
47  Artist,
48  Genre,
49  Year,
50  Comment,
51  Bpm,
52  Bps,
53  Lyricist,
55  DiskPosition,
56  PartNumber,
57  TotalParts,
58  Encoder,
59  RecordDate,
60  Performers,
61  Length,
62  Language,
64  Lyrics,
66  Grouping,
67  RecordLabel,
68  Cover,
69  Composer,
70  Rating,
71  Description,
72  Vendor
73 };
74 
79 
84 
88 constexpr unsigned int knownFieldArraySize = static_cast<unsigned int>(lastKnownField) + 1;
89 
94 {
95  return field == lastKnownField ? KnownField::Invalid : static_cast<KnownField>(static_cast<int>(field) + 1);
96 }
97 
99 {
100 public:
101  virtual ~Tag();
102 
103  virtual TagType type() const;
104  virtual const char *typeName() const;
105  std::string toString() const;
106  virtual TagTextEncoding proposedTextEncoding() const;
107  virtual bool canEncodingBeUsed(TagTextEncoding encoding) const;
108  virtual const TagValue &value(KnownField field) const = 0;
109  virtual std::vector<const TagValue *> values(KnownField field) const;
110  virtual bool setValue(KnownField field, const TagValue &value) = 0;
111  virtual bool setValues(KnownField field, const std::vector<TagValue> &values);
112  virtual bool hasField(KnownField field) const = 0;
113  virtual void removeAllFields() = 0;
114  const std::string &version() const;
115  uint32 size() const;
116  virtual bool supportsTarget() const;
117  const TagTarget &target() const;
118  void setTarget(const TagTarget &target);
119  virtual TagTargetLevel targetLevel() const;
120  const char *targetLevelName() const;
121  bool isTargetingLevel(TagTargetLevel tagTargetLevel) const;
122  std::string targetString() const;
123  virtual unsigned int fieldCount() const = 0;
124  virtual bool supportsField(KnownField field) const = 0;
125  virtual TagDataType proposedDataType(KnownField field) const;
126  virtual bool supportsDescription(KnownField field) const;
127  virtual bool supportsMimeType(KnownField field) const;
128  virtual unsigned int insertValues(const Tag &from, bool overwrite);
129  virtual void ensureTextValuesAreProperlyEncoded() = 0;
130 // Tag *parent() const;
131 // bool setParent(Tag *tag);
132 // Tag *nestedTag(size_t index) const;
133 // size_t nestedTagCount() const;
134 // const std::vector<Tag *> nestedTags() const;
135 // virtual bool supportsNestedTags() const;
136 // virtual bool supportsChild(Tag *child);
137 
138 protected:
139  Tag();
140 
141  std::string m_version;
142  uint32 m_size;
144 // Tag *m_parent;
145 // std::vector<Tag *> m_nestedTags;
146 };
147 
154 inline TagType Tag::type() const
155 {
156  return TagType::Unspecified;
157 }
158 
165 inline const char *Tag::typeName() const
166 {
167  return "unspecified";
168 }
169 
184 {
186 }
187 
202 inline bool Tag::canEncodingBeUsed(TagTextEncoding encoding) const
203 {
204  return encoding == proposedTextEncoding();
205 }
206 
211 inline const std::string &Tag::version() const
212 {
213  return m_version;
214 }
215 
220 inline uint32 Tag::size() const
221 {
222  return m_size;
223 }
224 
234 inline bool Tag::supportsTarget() const
235 {
236  return false;
237 }
238 
245 inline const TagTarget &Tag::target() const
246 {
247  return m_target;
248 }
249 
259 inline void Tag::setTarget(const TagTarget &target)
260 {
261  m_target = target;
262 }
263 
269 {
271 }
272 
277 inline const char *Tag::targetLevelName() const
278 {
279  return supportsTarget() ? tagTargetLevelName(targetLevel()) : nullptr;
280 }
281 
287 inline bool Tag::isTargetingLevel(TagTargetLevel tagTargetLevel) const
288 {
289  return !supportsTarget() || static_cast<byte>(targetLevel()) >= static_cast<byte>(tagTargetLevel);
290 }
291 
295 inline std::string Tag::targetString() const
296 {
297  return target().toString(targetLevel());
298 }
299 
315 {
316  switch(field) {
317  case KnownField::Bpm:
318  case KnownField::Bps:
319  case KnownField::Rating:
322  return TagDataType::Integer;
323  case KnownField::Cover:
324  return TagDataType::Picture;
325  case KnownField::Length:
326  return TagDataType::TimeSpan;
330  case KnownField::Genre:
332  default:
333  return TagDataType::Text;
334  }
335 }
336 
347 {
348  return false;
349 }
350 
361 {
362  return false;
363 }
364 
366 // * \brief Returns the parent of the tag.
367 // */
368 //inline Tag *Tag::parent() const
369 //{
370 // return m_parent;
371 //}
372 
374 // * \brief Returns the nested tags.
375 // */
376 //inline const std::vector<Tag *> Tag::nestedTags() const
377 //{
378 // return m_nestedTags;
379 //}
380 
382 // * \brief Returns whether the tag supports nested tags (generally).
383 // */
384 //inline bool Tag::supportsNestedTags() const
385 //{
386 // return false;
387 //}
388 
390 // * \brief Returns whether \a child might be added as nested tag.
391 // *
392 // * The default implementation returns true when nested tag are
393 // * generally supported and the \a child is of the same type
394 // * as this tag.
395 // */
396 //inline bool Tag::supportsChild(Tag *child)
397 //{
398 // return supportsNestedTags() && type() == child->type();
399 //}
400 
402 // * \brief Returns the nested tag with the specified \a index.
403 // */
404 //inline Tag *Tag::nestedTag(size_t ) const
405 //{
406 // return nullptr;
407 //}
408 
410 // * \brief Returns the number of nested tags.
411 // */
412 //inline size_t Tag::nestedTagCount() const
413 //{
414 // return 0;
415 //}
416 
417 }
418 
419 #endif // TAG_H
std::string targetString() const
Returns the string representation for the assigned tag target.
Definition: tag.h:295
The TagValue class wraps values of different types.
Definition: tagvalue.h:64
const TagTarget & target() const
Returns the target of tag.
Definition: tag.h:245
std::string m_version
Definition: tag.h:141
virtual bool supportsDescription(KnownField field) const
Returns an indications whether the specified field supports descriptions.
Definition: tag.h:346
virtual TagTargetLevel targetLevel() const
Returns the name of the current tag target level.
Definition: tag.h:268
Implementation of Media::Tag for Vorbis comments.
Definition: vorbiscomment.h:15
TAG_PARSER_EXPORT const char * tagTargetLevelName(TagTargetLevel tagTargetLevel)
Returns a string representation for the specified tagTargetLevel.
Definition: tagtarget.cpp:17
bool isTargetingLevel(TagTargetLevel tagTargetLevel) const
Returns whether the tag is targeting the specified tagTargetLevel.
Definition: tag.h:287
constexpr KnownField nextKnownField(KnownField field)
Returns the next known field.
Definition: tag.h:93
const std::string & version() const
Returns the version of the tag as std::string.
Definition: tag.h:211
KnownField
Specifies the field.
Definition: tag.h:42
Specialization of Media::VorbisComment for Vorbis comments inside an OGG stream.
Definition: oggcontainer.h:68
virtual TagTextEncoding proposedTextEncoding() const
Returns the proposed text encoding.
Definition: tag.h:183
constexpr KnownField lastKnownField
The last valid entry in the Media::KnownField enum.
Definition: tag.h:83
virtual bool canEncodingBeUsed(TagTextEncoding encoding) const
Returns an indication whether the specified encoding can be used to provide string values for the tag...
Definition: tag.h:202
TagTextEncoding
Specifies the text encoding.
Definition: tagvalue.h:22
uint32 m_size
Definition: tag.h:142
uint32 size() const
Returns the size of the tag in bytes.
Definition: tag.h:220
const char * targetLevelName() const
Returns the name of the current target level.
Definition: tag.h:277
TagTargetLevel
The TagTargetLevel enum specifies tag target levels.
Definition: tagtarget.h:17
constexpr KnownField firstKnownField
The first valid entry in the Media::KnownField enum.
Definition: tag.h:78
Implementation of Media::Tag for the MP4 container.
Definition: mp4tag.h:90
constexpr unsigned int knownFieldArraySize
The number of valid entries in the Media::KnownField enum.
Definition: tag.h:88
virtual TagType type() const
Returns the type of the tag as Media::TagType.
Definition: tag.h:154
The Tag class is used to store, read and write tag information.
Definition: tag.h:98
virtual bool supportsTarget() const
Returns an indication whether a target is supported by the tag.
Definition: tag.h:234
std::string toString(const std::function< TagTargetLevel(uint64)> &tagTargetMapping) const
Returns the string representation of the current instance.
Definition: tagtarget.h:218
virtual const char * typeName() const
Returns the type name of the tag as C-style string.
Definition: tag.h:165
Implementation of Media::Tag for ID3v2 tags.
Definition: id3v2tag.h:55
Implementation of Media::Tag for ID3v1 tags.
Definition: id3v1tag.h:9
TagType
Specifies the tag type.
Definition: tag.h:21
void setTarget(const TagTarget &target)
Sets the target of tag.
Definition: tag.h:259
TagDataType
Specifies the data type.
Definition: tagvalue.h:51
virtual bool supportsMimeType(KnownField field) const
Returns an indications whether the specified field supports mime types.
Definition: tag.h:360
Implementation of Media::Tag for the Matroska container.
Definition: matroskatag.h:50
virtual TagDataType proposedDataType(KnownField field) const
Returns the proposed data type for the specified field as TagDataType.
Definition: tag.h:314
The TagTarget class specifies the target of a tag.
Definition: tagtarget.h:31
Contains all classes and functions of the TagInfo library.
Definition: exceptions.h:9
The StatusProvider class acts as a base class for objects providing status information.
TagTarget m_target
Definition: tag.h:143
#define TAG_PARSER_EXPORT
Marks the symbol to be exported by the tagparser library.
TAG_PARSER_EXPORT const char * version()