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

   1 /***************************************************************************
   2     copyright            : (C) 2004 by Allan Sandfeld Jensen
   3     email                : kde@carewolf.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_APEITEM_H
  27 #define TAGLIB_APEITEM_H
  28
  29 #include "tbytevector.h"
  30 #include "tstring.h"
  31 #include "tstringlist.h"
  32
  33 namespace TagLib {
  34
  35   namespace APE {
  36
  37     //! An implementation of APE-items
  38
  39     /*!
  40      * This class provides the features of items in the APEv2 standard.
  41      */
  42     class TAGLIB_EXPORT Item
  43     {
  44     public:
  45       /*!
  46        * Enum of types an Item can have. The value of 3 is reserved.
  47        */
  48       enum ItemTypes {
  49         //! Item contains text information coded in UTF-8
  50         Text = 0,
  51         //! Item contains binary information
  52         Binary = 1,
  53         //! Item is a locator of external stored information
  54         Locator = 2
  55       };
  56       /*!
  57        * Constructs an empty item.
  58        */
  59       Item();
  60
  61       /*!
  62        * Constructs an item with \a key and \a value.
  63        */
  64       // BIC: Remove this, StringList has a constructor from a single string
  65       Item(const String &key, const String &value);
  66
  67       /*!
  68        * Constructs an item with \a key and \a values.
  69        */
  70       Item(const String &key, const StringList &values);
  71
  72       /*!
  73        * Construct an item as a copy of \a item.
  74        */
  75       Item(const Item &item);
  76
  77       /*!
  78        * Destroys the item.
  79        */
  80       virtual ~Item();
  81
  82       /*!
  83        * Copies the contents of \a item into this item.
  84        */
  85       Item &operator=(const Item &item);
  86
  87       /*!
  88        * Returns the key.
  89        */
  90       String key() const;
  91
  92       /*!
  93        * Returns the binary value.
  94        *
  95        * \deprecated This will be removed in the next binary incompatible version
  96        * as it is not kept in sync with the things that are set using setValue()
  97        * and friends.
  98        */
  99       ByteVector value() const;
 100
 101       /*!
 102        * Sets the key for the item to \a key.
 103        */
 104       void setKey(const String &key);
 105
 106       /*!
 107        * Sets the value of the item to \a value and clears any previous contents.
 108        *
 109        * \see toString()
 110        */
 111       void setValue(const String &value);
 112
 113       /*!
 114        * Sets the value of the item to the list of values in \a value and clears
 115        * any previous contents.
 116        *
 117        * \see toStringList()
 118        */
 119       void setValues(const StringList &values);
 120
 121       /*!
 122        * Appends \a value to create (or extend) the current list of values.
 123        *
 124        * \see toString()
 125        */
 126       void appendValue(const String &value);
 127
 128       /*!
 129        * Appends \a values to extend the current list of values.
 130        *
 131        * \see toStringList()
 132        */
 133       void appendValues(const StringList &values);
 134
 135       /*!
 136        * Returns the size of the full item.
 137        */
 138       int size() const;
 139
 140       /*!
 141        * Returns the value as a single string. In case of multiple strings,
 142        * the first is returned.
 143        */
 144       String toString() const;
 145
 146       /*!
 147        * \deprecated
 148        * \see values
 149        */
 150       StringList toStringList() const;
 151
 152       /*!
 153        * Returns the list of values.
 154        */
 155       StringList values() const;
 156
 157       /*!
 158        * Render the item to a ByteVector.
 159        */
 160       ByteVector render() const;
 161
 162       /*!
 163        * Parse the item from the ByteVector \a data.
 164        */
 165       void parse(const ByteVector& data);
 166
 167       /*!
 168        * Set the item to read-only.
 169        */
 170       void setReadOnly(bool readOnly);
 171
 172       /*!
 173        * Return true if the item is read-only.
 174        */
 175       bool isReadOnly() const;
 176
 177       /*!
 178        * Sets the type of the item to \a type.
 179        *
 180        * \see ItemTypes
 181        */
 182       void setType(ItemTypes type);
 183
 184       /*!
 185        * Returns the type of the item.
 186        */
 187       ItemTypes type() const;
 188
 189       /*!
 190        * Returns if the item has any real content.
 191        */
 192       bool isEmpty() const;
 193
 194     private:
 195       class ItemPrivate;
 196       ItemPrivate *d;
 197     };
 198   }
 199
 200 }
 201
 202 #endif
 203
 204