1 /*************************************************************************** 2 copyright : (C) 2006 by Lukáš Lalinský 3 email : [email protected] 4 5 copyright : (C) 2004 by Allan Sandfeld Jensen 6 email : [email protected] 7 (original MPC implementation) 8 ***************************************************************************/ 9 10 /*************************************************************************** 11 * This library is free software; you can redistribute it and/or modify * 12 * it under the terms of the GNU Lesser General Public License version * 13 * 2.1 as published by the Free Software Foundation. * 14 * * 15 * This library is distributed in the hope that it will be useful, but * 16 * WITHOUT ANY WARRANTY; without even the implied warranty of * 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * 18 * Lesser General Public License for more details. * 19 * * 20 * You should have received a copy of the GNU Lesser General Public * 21 * License along with this library; if not, write to the Free Software * 22 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA * 23 * 02110-1301 USA * 24 * * 25 * Alternatively, this file is available under the Mozilla Public * 26 * License Version 1.1. You may obtain a copy of the License at * 27 * http://www.mozilla.org/MPL/ * 28 ***************************************************************************/ 29 30 #ifndef TAGLIB_TRUEAUDIOFILE_H 31 #define TAGLIB_TRUEAUDIOFILE_H 32 33 #include "tfile.h" 34 #include "trueaudioproperties.h" 35 36 namespace TagLib { 37 38 class Tag; 39 40 namespace ID3v2 { class Tag; class FrameFactory; } 41 namespace ID3v1 { class Tag; } 42 43 //! An implementation of TrueAudio metadata 44 45 /*! 46 * This is implementation of TrueAudio metadata. 47 * 48 * This supports ID3v1 and ID3v2 tags as well as reading stream 49 * properties from the file. 50 */ 51 52 namespace TrueAudio { 53 54 //! An implementation of TagLib::File with TrueAudio specific methods 55 56 /*! 57 * This implements and provides an interface for TrueAudio files to the 58 * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing 59 * the abstract TagLib::File API as well as providing some additional 60 * information specific to TrueAudio files. 61 */ 62 63 class TAGLIB_EXPORT File : public TagLib::File 64 { 65 public: 66 /*! 67 * This set of flags is used for various operations and is suitable for 68 * being OR-ed together. 69 */ 70 enum TagTypes { 71 //! Empty set. Matches no tag types. 72 NoTags = 0x0000, 73 //! Matches ID3v1 tags. 74 ID3v1 = 0x0001, 75 //! Matches ID3v2 tags. 76 ID3v2 = 0x0002, 77 //! Matches all tag types. 78 AllTags = 0xffff 79 }; 80 81 /*! 82 * Constructs a TrueAudio file from \a file. If \a readProperties is true 83 * the file's audio properties will also be read. 84 * 85 * \note In the current implementation, \a propertiesStyle is ignored. 86 */ 87 File(FileName file, bool readProperties = true, 88 Properties::ReadStyle propertiesStyle = Properties::Average); 89 90 /*! 91 * Constructs a TrueAudio file from \a file. If \a readProperties is true 92 * the file's audio properties will also be read. 93 * 94 * If this file contains and ID3v2 tag the frames will be created using 95 * \a frameFactory. 96 * 97 * \note In the current implementation, \a propertiesStyle is ignored. 98 */ 99 File(FileName file, ID3v2::FrameFactory *frameFactory, 100 bool readProperties = true, 101 Properties::ReadStyle propertiesStyle = Properties::Average); 102 103 /*! 104 * Constructs a TrueAudio file from \a stream. If \a readProperties is true 105 * the file's audio properties will also be read. 106 * 107 * \note TagLib will *not* take ownership of the stream, the caller is 108 * responsible for deleting it after the File object. 109 * 110 * \note In the current implementation, \a propertiesStyle is ignored. 111 */ 112 File(IOStream *stream, bool readProperties = true, 113 Properties::ReadStyle propertiesStyle = Properties::Average); 114 115 /*! 116 * Constructs a TrueAudio file from \a stream. If \a readProperties is true 117 * the file's audio properties will also be read. 118 * 119 * \note TagLib will *not* take ownership of the stream, the caller is 120 * responsible for deleting it after the File object. 121 * 122 * If this file contains and ID3v2 tag the frames will be created using 123 * \a frameFactory. 124 * 125 * \note In the current implementation, \a propertiesStyle is ignored. 126 */ 127 File(IOStream *stream, ID3v2::FrameFactory *frameFactory, 128 bool readProperties = true, 129 Properties::ReadStyle propertiesStyle = Properties::Average); 130 131 /*! 132 * Destroys this instance of the File. 133 */ 134 virtual ~File(); 135 136 /*! 137 * Returns the Tag for this file. 138 */ 139 virtual TagLib::Tag *tag() const; 140 141 /*! 142 * Implements the unified property interface -- export function. 143 * If the file contains both ID3v1 and v2 tags, only ID3v2 will be 144 * converted to the PropertyMap. 145 */ 146 PropertyMap properties() const; 147 148 /*! 149 * Implements the unified property interface -- import function. 150 * Creates in ID3v2 tag if necessary. If an ID3v1 tag exists, it will 151 * be updated as well, within the limitations of ID3v1. 152 */ 153 PropertyMap setProperties(const PropertyMap &); 154 155 void removeUnsupportedProperties(const StringList &properties); 156 157 /*! 158 * Returns the TrueAudio::Properties for this file. If no audio properties 159 * were read then this will return a null pointer. 160 */ 161 virtual Properties *audioProperties() const; 162 163 /*! 164 * Set the ID3v2::FrameFactory to something other than the default. 165 * 166 * \see ID3v2FrameFactory 167 * \deprecated This value should be passed in via the constructor 168 */ 169 TAGLIB_DEPRECATED void setID3v2FrameFactory(const ID3v2::FrameFactory *factory); 170 171 /*! 172 * Saves the file. 173 */ 174 virtual bool save(); 175 176 /*! 177 * Returns a pointer to the ID3v1 tag of the file. 178 * 179 * If \a create is false (the default) this may return a null pointer 180 * if there is no valid ID3v1 tag. If \a create is true it will create 181 * an ID3v1 tag if one does not exist and returns a valid pointer. 182 * 183 * \note This may return a valid pointer regardless of whether or not the 184 * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file 185 * on disk actually has an ID3v1 tag. 186 * 187 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 188 * deleted by the user. It will be deleted when the file (object) is 189 * destroyed. 190 * 191 * \see hasID3v1Tag() 192 */ 193 ID3v1::Tag *ID3v1Tag(bool create = false); 194 195 /*! 196 * Returns a pointer to the ID3v2 tag of the file. 197 * 198 * If \a create is false (the default) this may return a null pointer 199 * if there is no valid ID3v2 tag. If \a create is true it will create 200 * an ID3v2 tag if one does not exist and returns a valid pointer. 201 * 202 * \note This may return a valid pointer regardless of whether or not the 203 * file on disk has an ID3v2 tag. Use hasID3v2Tag() to check if the file 204 * on disk actually has an ID3v2 tag. 205 * 206 * \note The Tag <b>is still</b> owned by the MPEG::File and should not be 207 * deleted by the user. It will be deleted when the file (object) is 208 * destroyed. 209 * 210 * \see hasID3v2Tag() 211 */ 212 ID3v2::Tag *ID3v2Tag(bool create = false); 213 214 /*! 215 * This will remove the tags that match the OR-ed together TagTypes from the 216 * file. By default it removes all tags. 217 * 218 * \note This will also invalidate pointers to the tags 219 * as their memory will be freed. 220 * \note In order to make the removal permanent save() still needs to be called 221 */ 222 void strip(int tags = AllTags); 223 224 /*! 225 * Returns whether or not the file on disk actually has an ID3v1 tag. 226 * 227 * \see ID3v1Tag() 228 */ 229 bool hasID3v1Tag() const; 230 231 /*! 232 * Returns whether or not the file on disk actually has an ID3v2 tag. 233 * 234 * \see ID3v2Tag() 235 */ 236 bool hasID3v2Tag() const; 237 238 /*! 239 * Returns whether or not the given \a stream can be opened as a TrueAudio 240 * file. 241 * 242 * \note This method is designed to do a quick check. The result may 243 * not necessarily be correct. 244 */ 245 static bool isSupported(IOStream *stream); 246 247 private: 248 File(const File &); 249 File &operator=(const File &); 250 251 void read(bool readProperties); 252 253 class FilePrivate; 254 FilePrivate *d; 255 }; 256 } 257 } 258 259 #endif 260