git.maemo.org Git - someplayer/blob - src/taglib/toolkit/taglib.h

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