1 /*************************************************************************** 2 copyright : (C) 2010 by Alex Novichkov 3 email : [email protected] 4 5 copyright : (C) 2006 by Lukáš Lalinský 6 email : [email protected] 7 (original WavPack implementation) 8 9 copyright : (C) 2004 by Allan Sandfeld Jensen 10 email : [email protected] 11 (original MPC implementation) 12 ***************************************************************************/ 13 14 /*************************************************************************** 15 * This library is free software; you can redistribute it and/or modify * 16 * it under the terms of the GNU Lesser General Public License version * 17 * 2.1 as published by the Free Software Foundation. * 18 * * 19 * This library is distributed in the hope that it will be useful, but * 20 * WITHOUT ANY WARRANTY; without even the implied warranty of * 21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 22 * Lesser General Public License for more details. * 23 * * 24 * You should have received a copy of the GNU Lesser General Public * 25 * License along with this library; if not, write to the Free Software * 26 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA * 27 * 02110-1301 USA * 28 * * 29 * Alternatively, this file is available under the Mozilla Public * 30 * License Version 1.1. You may obtain a copy of the License at * 31 * http://www.mozilla.org/MPL/ * 32 ***************************************************************************/ 33 34 #ifndef TAGLIB_APEFILE_H 35 #define TAGLIB_APEFILE_H 36 37 #include "tfile.h" 38 #include "taglib_export.h" 39 #include "apeproperties.h" 40 41 namespace TagLib { 42 43 class Tag; 44 45 namespace ID3v1 { class Tag; } 46 namespace APE { class Tag; } 47 48 //! An implementation of APE metadata 49 50 /*! 51 * This is implementation of APE metadata. 52 * 53 * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream 54 * properties from the file. 55 */ 56 57 namespace APE { 58 59 //! An implementation of TagLib::File with APE specific methods 60 61 /*! 62 * This implements and provides an interface for APE files to the 63 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing 64 * the abstract TagLib::File API as well as providing some additional 65 * information specific to APE files. 66 */ 67 68 class TAGLIB_EXPORT File : public TagLib::File 69 { 70 public: 71 /*! 72 * This set of flags is used for various operations and is suitable for 73 * being OR-ed together. 74 */ 75 enum TagTypes { 76 //! Empty set. Matches no tag types. 77 NoTags = 0x0000, 78 //! Matches ID3v1 tags. 79 ID3v1 = 0x0001, 80 //! Matches APE tags. 81 APE = 0x0002, 82 //! Matches all tag types. 83 AllTags = 0xffff 84 }; 85 86 /*! 87 * Constructs an APE 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 APE 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 APE 121 * will be converted to the PropertyMap. 122 */ 123 PropertyMap properties() const; 124 125 /*! 126 * Removes unsupported properties. Forwards to the actual Tag's 127 * removeUnsupportedProperties() function. 128 */ 129 void removeUnsupportedProperties(const StringList &properties); 130 131 /*! 132 * Implements the unified property interface -- import function. 133 * Creates an APEv2 tag if necessary. A potentially existing ID3v1 134 * tag will be updated as well. 135 */ 136 PropertyMap setProperties(const PropertyMap &); 137 138 /*! 139 * Returns the APE::Properties for this file. If no audio properties 140 * were read then this will return a null pointer. 141 */ 142 virtual Properties *audioProperties() const; 143 144 /*! 145 * Saves the file. 146 * 147 * \note According to the official Monkey's Audio SDK, an APE file 148 * can only have either ID3V1 or APE tags, so a parameter is used here. 149 */ 150 virtual bool save(); 151 152 /*! 153 * Returns a pointer to the ID3v1 tag of the file. 154 * 155 * If \a create is false (the default) this may return a null pointer 156 * if there is no valid ID3v1 tag. If \a create is true it will create 157 * an ID3v1 tag if one does not exist and returns a valid pointer. 158 * 159 * \note This may return a valid pointer regardless of whether or not the 160 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file 161 * on disk actually has an ID3v1 tag. 162 * 163 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 164 * deleted by the user. It will be deleted when the file (object) is 165 * destroyed. 166 * 167 * \see hasID3v1Tag() 168 */ 169 ID3v1::Tag *ID3v1Tag(bool create = false); 170 171 /*! 172 * Returns a pointer to the APE tag of the file. 173 * 174 * If \a create is false (the default) this may return a null pointer 175 * if there is no valid APE tag. If \a create is true it will create 176 * an APE tag if one does not exist and returns a valid pointer. 177 * 178 * \note This may return a valid pointer regardless of whether or not the 179 * file on disk has an APE tag. Use hasAPETag() to check if the file 180 * on disk actually has an APE tag. 181 * 182 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 183 * deleted by the user. It will be deleted when the file (object) is 184 * destroyed. 185 * 186 * \see hasAPETag() 187 */ 188 APE::Tag *APETag(bool create = false); 189 190 /*! 191 * This will remove the tags that match the OR-ed together TagTypes from the 192 * file. By default it removes all tags. 193 * 194 * \note This will also invalidate pointers to the tags 195 * as their memory will be freed. 196 * \note In order to make the removal permanent save() still needs to be called 197 */ 198 void strip(int tags = AllTags); 199 200 /*! 201 * Returns whether or not the file on disk actually has an APE tag. 202 * 203 * \see APETag() 204 */ 205 bool hasAPETag() const; 206 207 /*! 208 * Returns whether or not the file on disk actually has an ID3v1 tag. 209 * 210 * \see ID3v1Tag() 211 */ 212 bool hasID3v1Tag() const; 213 214 /*! 215 * Returns whether or not the given \a stream can be opened as an APE 216 * file. 217 * 218 * \note This method is designed to do a quick check. The result may 219 * not necessarily be correct. 220 */ 221 static bool isSupported(IOStream *stream); 222 223 private: 224 File(const File &); 225 File &operator=(const File &); 226 227 void read(bool readProperties); 228 229 class FilePrivate; 230 FilePrivate *d; 231 }; 232 } 233 } 234 235 #endif 236