1/***************************************************************************
2 copyright : (C) 2002 - 2008 by Scott Wheeler
3 email : wheeler@kde.org
4 ***************************************************************************/
5
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. *
10 * *
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. *
15 * *
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., 51 Franklin Street, Fifth Floor, Boston, MA *
19 * 02110-1301 USA *
20 * *
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 ***************************************************************************/
25
26#ifndef TAGLIB_H
27#define TAGLIB_H
28
29#include "taglib_config.h"
30
31#define TAGLIB_MAJOR_VERSION 1
32#define TAGLIB_MINOR_VERSION 11
33#define TAGLIB_PATCH_VERSION 1
34
35#if defined(__GNUC__) && (__GNUC__ > 4 || (__GNUC__ == 4 && __GNUC_MINOR__ > 1)) || defined(__clang__)
36#define TAGLIB_IGNORE_MISSING_DESTRUCTOR _Pragma("GCC diagnostic ignored \"-Wnon-virtual-dtor\"")
37#else
38#define TAGLIB_IGNORE_MISSING_DESTRUCTOR
39#endif
40
41#if (defined(_MSC_VER) && _MSC_VER >= 1600)
42#define TAGLIB_CONSTRUCT_BITSET(x) static_cast<unsigned long long>(x)
43#else
44#define TAGLIB_CONSTRUCT_BITSET(x) static_cast<unsigned long>(x)
45#endif
46
47#include <string>
48
49//! A namespace for all TagLib related classes and functions
50
51/*!
52 * This namespace contains everything in TagLib. For projects working with
53 * TagLib extensively it may be convenient to add a
54 * \code
55 * using namespace TagLib;
56 * \endcode
57 */
58
59namespace TagLib {
60
61 class String;
62
63 // These integer types are deprecated. Do not use them.
64
65 typedef wchar_t wchar; // Assumed to be sufficient to store a UTF-16 char.
66 typedef unsigned char uchar;
67 typedef unsigned short ushort;
68 typedef unsigned int uint;
69 typedef unsigned long ulong;
70 typedef unsigned long long ulonglong;
71
72 /*!
73 * Unfortunately std::wstring isn't defined on some systems, (i.e. GCC < 3)
74 * so I'm providing something here that should be constant.
75 */
76 typedef std::basic_string<wchar_t> wstring;
77}
78
79/*!
80 * \mainpage TagLib
81 *
82 * \section intro Introduction
83 *
84 * TagLib is a library for reading and editing audio meta data, commonly know as \e tags.
85 *
86 * Features:
87 * - A clean, high level, C++ API to handling audio meta data.
88 * - Format specific APIs for advanced API users.
89 * - ID3v1, ID3v2, APE, FLAC, Xiph, iTunes-style MP4 and WMA tag formats.
90 * - MP3, MPC, FLAC, MP4, ASF, AIFF, WAV, TrueAudio, WavPack, Ogg FLAC, Ogg Vorbis, Speex and Opus file formats.
91 * - Basic audio file properties such as length, sample rate, etc.
92 * - Long term binary and source compatibility.
93 * - Extensible design, notably the ability to add other formats or extend current formats as a library user.
94 * - Full support for unicode and internationalized tags.
95 * - Dual <a href="http://www.mozilla.org/MPL/MPL-1.1.html">MPL</a> and
96 * <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html">LGPL</a> licenses.
97 * - No external toolkit dependencies.
98 *
99 * \section why Why TagLib?
100 *
101 * TagLib originally was written to provide an updated and improved ID3v2 implementation in C++ for use
102 * in a variety of Open Source projects. Since development began in 2002 and the 1.0 release in 2004
103 * it has expanded to cover a wide variety of tag and file formats and is used in a wide variety of
104 * Open Source and proprietary applications. It now supports a variety of UNIXes, including Apple's OS
105 * X, as well as Microsoft Windows.
106 *
107 * \section commercial Usage in Commercial Applications
108 *
109 * TagLib's licenses \e do allow usage within propriety (\e closed) applications, however TagLib is \e not
110 * public domain. Please note the requirements of the LGPL or MPL, and adhere to at least one of them.
111 * In simple terms, you must at a minimum note your usage of TagLib, note the licensing terms of TagLib and
112 * if you make changes to TagLib publish them. Please review the licenses above before using TagLib in your
113 * software. Note that you may choose either the MPL or the LGPL, you do not have to fulfill the
114 * requirements of both.
115 *
116 * \section installing Installing TagLib
117 *
118 * Please see the <a href="http://developer.kde.org/~wheeler/taglib.html">TagLib website</a> for the latest
119 * downloads.
120 *
121 * TagLib can be built using the CMake build system. TagLib installs a taglib-config and pkg-config file to
122 * make it easier to integrate into various build systems. Note that TagLib's include install directory \e must
123 * be included in the header include path. Simply adding <taglib/tag.h> will \e not work.
124 *
125 * \section start Getting Started
126 *
127 * TagLib provides both simple, abstract APIs which make it possible to ignore the differences between tagging
128 * formats and format specific APIs which allow programmers to work with the features of specific tagging
129 * schemes. There is a similar abstraction mechanism for AudioProperties.
130 *
131 * The best place to start is with the <b>Class Hierarchy</b> linked at the top of the page. The File and
132 * AudioProperties classes and their subclasses are the core of TagLib. The FileRef class is also a convenient
133 * way for using a value-based handle.
134 *
135 * \note When working with FileRef please consider that it has only the most basic (extension-based) file
136 * type resolution. Please see its documentation on how to plug in more advanced file type resolution. (Such
137 * resolution may be part of later TagLib releases by default.)
138 *
139 * Here's a very simple example with TagLib:
140 *
141 * \code
142 *
143 * TagLib::FileRef f("Latex Solar Beef.mp3");
144 * TagLib::String artist = f.tag()->artist(); // artist == "Frank Zappa"
145 *
146 * f.tag()->setAlbum("Fillmore East");
147 * f.save();
148 *
149 * TagLib::FileRef g("Free City Rhymes.ogg");
150 * TagLib::String album = g.tag()->album(); // album == "NYC Ghosts & Flowers"
151 *
152 * g.tag()->setTrack(1);
153 * g.save();
154 *
155 * \endcode
156 *
157 * More examples can be found in the \e examples directory of the source distribution.
158 *
159 * \section Contact
160 *
161 * Questions about TagLib should be directed to the TagLib mailing list, not directly to the author.
162 *
163 * - <a href="http://developer.kde.org/~wheeler/taglib/">TagLib Homepage</a>
164 * - <a href="https://mail.kde.org/mailman/listinfo/taglib-devel">TagLib Mailing List (taglib-devel@kde.org)</a>
165 *
166 * \author Scott Wheeler <wheeler@kde.org> et al.
167 *
168 */
169
170#endif
171