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., 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_MPCFILE_H 27 #define TAGLIB_MPCFILE_H 28 29 #include "taglib_export.h" 30 #include "tfile.h" 31 #include "tag.h" 32 33 #include "mpcproperties.h" 34 35 #include "tlist.h" 36 37 namespace TagLib { 38 39 class Tag; 40 41 namespace ID3v1 { class Tag; } 42 namespace APE { class Tag; } 43 44 //! An implementation of MPC metadata 45 46 /*! 47 * This is implementation of MPC metadata. 48 * 49 * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream 50 * properties from the file. ID3v2 tags are invalid in MPC-files, but will be skipped 51 * and ignored. 52 */ 53 54 namespace MPC { 55 56 //! An implementation of TagLib::File with MPC specific methods 57 58 /*! 59 * This implements and provides an interface for MPC files to the 60 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing 61 * the abstract TagLib::File API as well as providing some additional 62 * information specific to MPC files. 63 * The only invalid tag combination supported is an ID3v1 tag after an APE tag. 64 */ 65 66 class TAGLIB_EXPORT File : public TagLib::File 67 { 68 public: 69 /*! 70 * This set of flags is used for various operations and is suitable for 71 * being OR-ed together. 72 */ 73 enum TagTypes { 74 //! Empty set. Matches no tag types. 75 NoTags = 0x0000, 76 //! Matches ID3v1 tags. 77 ID3v1 = 0x0001, 78 //! Matches ID3v2 tags. 79 ID3v2 = 0x0002, 80 //! Matches APE tags. 81 APE = 0x0004, 82 //! Matches all tag types. 83 AllTags = 0xffff 84 }; 85 86 /*! 87 * Constructs an MPC file from \a file. If \a readProperties is true the 88 * file's audio properties will also be read. 89 * 90 * \note In the current implementation, \a propertiesStyle is ignored. 91 */ 92 File(FileName file, bool readProperties = true, 93 Properties::ReadStyle propertiesStyle = Properties::Average); 94 95 /*! 96 * Constructs an MPC file from \a stream. If \a readProperties is true the 97 * file's audio properties will also be read. 98 * 99 * \note TagLib will *not* take ownership of the stream, the caller is 100 * responsible for deleting it after the File object. 101 * 102 * \note In the current implementation, \a propertiesStyle is ignored. 103 */ 104 File(IOStream *stream, bool readProperties = true, 105 Properties::ReadStyle propertiesStyle = Properties::Average); 106 107 /*! 108 * Destroys this instance of the File. 109 */ 110 virtual ~File(); 111 112 /*! 113 * Returns the Tag for this file. This will be an APE tag, an ID3v1 tag 114 * or a combination of the two. 115 */ 116 virtual TagLib::Tag *tag() const; 117 118 /*! 119 * Implements the unified property interface -- export function. 120 * If the file contains both an APE and an ID3v1 tag, only the APE 121 * tag will be converted to the PropertyMap. 122 */ 123 PropertyMap properties() const; 124 125 void removeUnsupportedProperties(const StringList &properties); 126 127 /*! 128 * Implements the unified property interface -- import function. 129 * Affects only the APEv2 tag which will be created if necessary. 130 * If an ID3v1 tag exists, it will be updated as well. 131 */ 132 PropertyMap setProperties(const PropertyMap &); 133 134 /*! 135 * Returns the MPC::Properties for this file. If no audio properties 136 * were read then this will return a null pointer. 137 */ 138 virtual Properties *audioProperties() const; 139 140 /*! 141 * Saves the file. 142 * 143 * This returns true if the save was successful. 144 */ 145 virtual bool save(); 146 147 /*! 148 * Returns a pointer to the ID3v1 tag of the file. 149 * 150 * If \a create is false (the default) this returns a null pointer 151 * if there is no valid APE tag. If \a create is true it will create 152 * an APE tag if one does not exist and returns a valid pointer. 153 * 154 * \note This may return a valid pointer regardless of whether or not the 155 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file 156 * on disk actually has an ID3v1 tag. 157 * 158 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 159 * deleted by the user. It will be deleted when the file (object) is 160 * destroyed. 161 * 162 * \see hasID3v1Tag() 163 */ 164 ID3v1::Tag *ID3v1Tag(bool create = false); 165 166 /*! 167 * Returns a pointer to the APE tag of the file. 168 * 169 * If \a create is false (the default) this may return a null pointer 170 * if there is no valid APE tag. If \a create is true it will create 171 * an APE tag if one does not exist and returns a valid pointer. If 172 * there already be an ID3v1 tag, the new APE tag will be placed before it. 173 * 174 * \note This may return a valid pointer regardless of whether or not the 175 * file on disk has an APE tag. Use hasAPETag() to check if the file 176 * on disk actually has an APE tag. 177 * 178 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 179 * deleted by the user. It will be deleted when the file (object) is 180 * destroyed. 181 * 182 * \see hasAPETag() 183 */ 184 APE::Tag *APETag(bool create = false); 185 186 /*! 187 * This will remove the tags that match the OR-ed together TagTypes from the 188 * file. By default it removes all tags. 189 * 190 * \warning This will also invalidate pointers to the tags 191 * as their memory will be freed. 192 * 193 * \note In order to make the removal permanent save() still needs to be called. 194 */ 195 void strip(int tags = AllTags); 196 197 /*! 198 * \deprecated 199 * \see strip 200 */ 201 TAGLIB_DEPRECATED void remove(int tags = AllTags); 202 203 /*! 204 * Returns whether or not the file on disk actually has an ID3v1 tag. 205 * 206 * \see ID3v1Tag() 207 */ 208 bool hasID3v1Tag() const; 209 210 /*! 211 * Returns whether or not the file on disk actually has an APE tag. 212 * 213 * \see APETag() 214 */ 215 bool hasAPETag() const; 216 217 /*! 218 * Returns whether or not the given \a stream can be opened as an MPC 219 * file. 220 * 221 * \note This method is designed to do a quick check. The result may 222 * not necessarily be correct. 223 */ 224 static bool isSupported(IOStream *stream); 225 226 private: 227 File(const File &); 228 File &operator=(const File &); 229 230 void read(bool readProperties); 231 232 class FilePrivate; 233 FilePrivate *d; 234 }; 235 } 236 } 237 238 #endif 239