1
/***************************************************************************
2
copyright : (C) 2002 - 2008 by Scott Wheeler
3
email : wheeler@kde.org
4
***************************************************************************/
6
/***************************************************************************
7
* This library is free software; you can redistribute it and/or modify *
8
* it under the terms of the GNU Lesser General Public License version *
9
* 2.1 as published by the Free Software Foundation. *
11
* This library is distributed in the hope that it will be useful, but *
12
* WITHOUT ANY WARRANTY; without even the implied warranty of *
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14
* Lesser General Public License for more details. *
16
* You should have received a copy of the GNU Lesser General Public *
17
* License along with this library; if not, write to the Free Software *
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
21
* Alternatively, this file is available under the Mozilla Public *
22
* License Version 1.1. You may obtain a copy of the License at *
23
* http://www.mozilla.org/MPL/ *
24
***************************************************************************/
26
#ifndef TAGLIB_VORBISCOMMENT_H
27
#define TAGLIB_VORBISCOMMENT_H
33
#include "tstringlist.h"
34
#include "tbytevector.h"
35
#include "taglib_export.h"
42
* A mapping between a list of field names, or keys, and a list of values
43
* associated with that field.
45
* \see XiphComment::fieldListMap()
47
typedef Map<String, StringList> FieldListMap;
49
//! Ogg Vorbis comment implementation
52
* This class is an implementation of the Ogg Vorbis comment specification,
53
* to be found in section 5 of the Ogg Vorbis specification. Because this
54
* format is also used in other (currently unsupported) Xiph.org formats, it
55
* has been made part of a generic implementation rather than being limited
58
* Vorbis comments are a simple vector of keys and values, called fields.
59
* Multiple values for a given key are supported.
64
class TAGLIB_EXPORT XiphComment : public TagLib::Tag
68
* Constructs an empty Vorbis comment.
73
* Constructs a Vorbis comment from \a data.
75
XiphComment(const ByteVector &data);
78
* Destroys this instance of the XiphComment.
80
virtual ~XiphComment();
82
virtual String title() const;
83
virtual String artist() const;
84
virtual String album() const;
85
virtual String comment() const;
86
virtual String genre() const;
87
virtual uint year() const;
88
virtual uint track() const;
90
virtual void setTitle(const String &s);
91
virtual void setArtist(const String &s);
92
virtual void setAlbum(const String &s);
93
virtual void setComment(const String &s);
94
virtual void setGenre(const String &s);
95
virtual void setYear(uint i);
96
virtual void setTrack(uint i);
98
virtual bool isEmpty() const;
101
* Returns the number of fields present in the comment.
103
uint fieldCount() const;
106
* Returns a reference to the map of field lists. Because Xiph comments
107
* support multiple fields with the same key, a pure Map would not work.
108
* As such this is a Map of string lists, keyed on the comment field name.
110
* The standard set of Xiph/Vorbis fields (which may or may not be
111
* contained in any specific comment) is:
120
* <li>ORGANIZATION</li>
121
* <li>DESCRIPTION</li>
129
* For a more detailed description of these fields, please see the Ogg
130
* Vorbis specification, section 5.2.2.1.
132
* \note The Ogg Vorbis comment specification does allow these key values
133
* to be either upper or lower case. However, it is conventional for them
134
* to be upper case. As such, TagLib, when parsing a Xiph/Vorbis comment,
135
* converts all fields to uppercase. When you are using this data
136
* structure, you will need to specify the field name in upper case.
138
* \warning You should not modify this data structure directly, instead
139
* use addField() and removeField().
141
const FieldListMap &fieldListMap() const;
144
* Returns the vendor ID of the Ogg Vorbis encoder. libvorbis 1.0 as the
145
* most common case always returns "Xiph.Org libVorbis I 20020717".
147
String vendorID() const;
150
* Add the field specified by \a key with the data \a value. If \a replace
151
* is true, then all of the other fields with the same key will be removed
154
* If the field value is empty, the field will be removed.
156
void addField(const String &key, const String &value, bool replace = true);
159
* Remove the field specified by \a key with the data \a value. If
160
* \a value is null, all of the fields with the given key will be removed.
162
void removeField(const String &key, const String &value = String::null);
165
* Returns true if the field is contained within the comment.
167
* \note This is safer than checking for membership in the FieldListMap.
169
bool contains(const String &key) const;
172
* Renders the comment to a ByteVector suitable for inserting into a file.
174
ByteVector render() const; // BIC: remove and merge with below
177
* Renders the comment to a ByteVector suitable for inserting into a file.
179
* If \a addFramingBit is true the standard Vorbis comment framing bit will
180
* be appended. However some formats (notably FLAC) do not work with this
183
ByteVector render(bool addFramingBit) const;
187
* Reads the tag from the file specified in the constructor and fills the
190
void parse(const ByteVector &data);
193
XiphComment(const XiphComment &);
194
XiphComment &operator=(const XiphComment &);
196
class XiphCommentPrivate;
197
XiphCommentPrivate *d;
added
removed
Frameworks/taglib/taglib/taglib/ogg/xiphcomment.h
