1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : [email protected] 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_FILE_H 27 #define TAGLIB_FILE_H 28 29 #include "taglib_export.h" 30 #include "taglib.h" 31 #include "tag.h" 32 #include "tbytevector.h" 33 #include "tiostream.h" 34 35 namespace TagLib { 36 37 class String; 38 class Tag; 39 class AudioProperties; 40 class PropertyMap; 41 42 //! A file class with some useful methods for tag manipulation 43 44 /*! 45 * This class is a basic file class with some methods that are particularly 46 * useful for tag editors. It has methods to take advantage of 47 * ByteVector and a binary search method for finding patterns in a file. 48 */ 49 50 class TAGLIB_EXPORT File 51 { 52 public: 53 /*! 54 * Position in the file used for seeking. 55 */ 56 enum Position { 57 //! Seek from the beginning of the file. 58 Beginning, 59 //! Seek from the current position in the file. 60 Current, 61 //! Seek from the end of the file. 62 End 63 }; 64 65 /*! 66 * Specify which tags to strip either explicitly, or on save. 67 */ 68 enum StripTags { 69 StripNone, //<! Don't strip any tags 70 StripOthers //<! Strip all tags not explicitly referenced in method call 71 }; 72 73 /*! 74 * Used to specify if when saving files, if values between different tag 75 * types should be syncronized. 76 */ 77 enum DuplicateTags { 78 Duplicate, //<! Syncronize values between different tag types 79 DoNotDuplicate //<! Do not syncronize values between different tag types 80 }; 81 82 /*! 83 * Destroys this File instance. 84 */ 85 virtual ~File(); 86 87 /*! 88 * Returns the file name in the local file system encoding. 89 */ 90 FileName name() const; 91 92 /*! 93 * Returns a pointer to this file's tag. This should be reimplemented in 94 * the concrete subclasses. 95 */ 96 virtual Tag *tag() const = 0; 97 98 /*! 99 * Exports the tags of the file as dictionary mapping (human readable) tag 100 * names (uppercase Strings) to StringLists of tag values. Calls the according 101 * specialization in the File subclasses. 102 * For each metadata object of the file that could not be parsed into the PropertyMap 103 * format, the returned map's unsupportedData() list will contain one entry identifying 104 * that object (e.g. the frame type for ID3v2 tags). Use removeUnsupportedProperties() 105 * to remove (a subset of) them. 106 * For files that contain more than one tag (e.g. an MP3 with both an ID3v1 and an ID3v2 107 * tag) only the most "modern" one will be exported (ID3v2 in this case). 108 * BIC: Will be made virtual in future releases. 109 */ 110 PropertyMap properties() const; 111 112 /*! 113 * Removes unsupported properties, or a subset of them, from the file's metadata. 114 * The parameter \a properties must contain only entries from 115 * properties().unsupportedData(). 116 * BIC: Will be mad virtual in future releases. 117 */ 118 void removeUnsupportedProperties(const StringList& properties); 119 120 /*! 121 * Sets the tags of this File to those specified in \a properties. Calls the 122 * according specialization method in the subclasses of File to do the translation 123 * into the format-specific details. 124 * If some value(s) could not be written imported to the specific metadata format, 125 * the returned PropertyMap will contain those value(s). Otherwise it will be empty, 126 * indicating that no problems occurred. 127 * With file types that support several tag formats (for instance, MP3 files can have 128 * ID3v1, ID3v2, and APEv2 tags), this function will create the most appropriate one 129 * (ID3v2 for MP3 files). Older formats will be updated as well, if they exist, but won't 130 * be taken into account for the return value of this function. 131 * See the documentation of the subclass implementations for detailed descriptions. 132 * BIC: will become pure virtual in the future 133 */ 134 PropertyMap setProperties(const PropertyMap &properties); 135 136 /*! 137 * Returns a pointer to this file's audio properties. This should be 138 * reimplemented in the concrete subclasses. If no audio properties were 139 * read then this will return a null pointer. 140 */ 141 virtual AudioProperties *audioProperties() const = 0; 142 143 /*! 144 * Save the file and its associated tags. This should be reimplemented in 145 * the concrete subclasses. Returns true if the save succeeds. 146 * 147 * \warning On UNIX multiple processes are able to write to the same file at 148 * the same time. This can result in serious file corruption. If you are 149 * developing a program that makes use of TagLib from multiple processes you 150 * must insure that you are only doing writes to a particular file from one 151 * of them. 152 */ 153 virtual bool save() = 0; 154 155 /*! 156 * Reads a block of size \a length at the current get pointer. 157 */ 158 ByteVector readBlock(unsigned long length); 159 160 /*! 161 * Attempts to write the block \a data at the current get pointer. If the 162 * file is currently only opened read only -- i.e. readOnly() returns true -- 163 * this attempts to reopen the file in read/write mode. 164 * 165 * \note This should be used instead of using the streaming output operator 166 * for a ByteVector. And even this function is significantly slower than 167 * doing output with a char[]. 168 */ 169 void writeBlock(const ByteVector &data); 170 171 /*! 172 * Returns the offset in the file that \a pattern occurs at or -1 if it can 173 * not be found. If \a before is set, the search will only continue until the 174 * pattern \a before is found. This is useful for tagging purposes to search 175 * for a tag before the sync frame. 176 * 177 * Searching starts at \a fromOffset, which defaults to the beginning of the 178 * file. 179 * 180 * \note This has the practical limitation that \a pattern can not be longer 181 * than the buffer size used by readBlock(). Currently this is 1024 bytes. 182 */ 183 long find(const ByteVector &pattern, 184 long fromOffset = 0, 185 const ByteVector &before = ByteVector()); 186 187 /*! 188 * Returns the offset in the file that \a pattern occurs at or -1 if it can 189 * not be found. If \a before is set, the search will only continue until the 190 * pattern \a before is found. This is useful for tagging purposes to search 191 * for a tag before the sync frame. 192 * 193 * Searching starts at \a fromOffset and proceeds from the that point to the 194 * beginning of the file and defaults to the end of the file. 195 * 196 * \note This has the practical limitation that \a pattern can not be longer 197 * than the buffer size used by readBlock(). Currently this is 1024 bytes. 198 */ 199 long rfind(const ByteVector &pattern, 200 long fromOffset = 0, 201 const ByteVector &before = ByteVector()); 202 203 /*! 204 * Insert \a data at position \a start in the file overwriting \a replace 205 * bytes of the original content. 206 * 207 * \note This method is slow since it requires rewriting all of the file 208 * after the insertion point. 209 */ 210 void insert(const ByteVector &data, unsigned long start = 0, unsigned long replace = 0); 211 212 /*! 213 * Removes a block of the file starting a \a start and continuing for 214 * \a length bytes. 215 * 216 * \note This method is slow since it involves rewriting all of the file 217 * after the removed portion. 218 */ 219 void removeBlock(unsigned long start = 0, unsigned long length = 0); 220 221 /*! 222 * Returns true if the file is read only (or if the file can not be opened). 223 */ 224 bool readOnly() const; 225 226 /*! 227 * Since the file can currently only be opened as an argument to the 228 * constructor (sort-of by design), this returns if that open succeeded. 229 */ 230 bool isOpen() const; 231 232 /*! 233 * Returns true if the file is open and readable. 234 */ 235 bool isValid() const; 236 237 /*! 238 * Move the I/O pointer to \a offset in the file from position \a p. This 239 * defaults to seeking from the beginning of the file. 240 * 241 * \see Position 242 */ 243 void seek(long offset, Position p = Beginning); 244 245 /*! 246 * Reset the end-of-file and error flags on the file. 247 */ 248 void clear(); 249 250 /*! 251 * Returns the current offset within the file. 252 */ 253 long tell() const; 254 255 /*! 256 * Returns the length of the file. 257 */ 258 long length(); 259 260 /*! 261 * Returns true if \a file can be opened for reading. If the file does not 262 * exist, this will return false. 263 * 264 * \deprecated 265 */ 266 TAGLIB_DEPRECATED static bool isReadable(const char *file); 267 268 /*! 269 * Returns true if \a file can be opened for writing. 270 * 271 * \deprecated 272 */ 273 TAGLIB_DEPRECATED static bool isWritable(const char *name); 274 275 protected: 276 /*! 277 * Construct a File object and opens the \a file. \a file should be a 278 * be a C-string in the local file system encoding. 279 * 280 * \note Constructor is protected since this class should only be 281 * instantiated through subclasses. 282 */ 283 File(FileName file); 284 285 /*! 286 * Construct a File object and use the \a stream instance. 287 * 288 * \note TagLib will *not* take ownership of the stream, the caller is 289 * responsible for deleting it after the File object. 290 * 291 * \note Constructor is protected since this class should only be 292 * instantiated through subclasses. 293 */ 294 File(IOStream *stream); 295 296 /*! 297 * Marks the file as valid or invalid. 298 * 299 * \see isValid() 300 */ 301 void setValid(bool valid); 302 303 /*! 304 * Truncates the file to a \a length. 305 */ 306 void truncate(long length); 307 308 /*! 309 * Returns the buffer size that is used for internal buffering. 310 */ 311 static unsigned int bufferSize(); 312 313 private: 314 File(const File &); 315 File &operator=(const File &); 316 317 class FilePrivate; 318 FilePrivate *d; 319 }; 320 321 } 322 323 #endif 324