1 /*************************************************************************** 2 copyright : (C) 2002 - 2008 by Scott Wheeler 3 email : wheeler@kde.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_VORBISFILE_H 27 #define TAGLIB_VORBISFILE_H 28 29 #include "taglib_export.h" 30 #include "oggfile.h" 31 #include "xiphcomment.h" 32 33 #include "vorbisproperties.h" 34 35 namespace TagLib { 36 37 /* 38 * This is just to make this appear to be in the Ogg namespace in the 39 * documentation. The typedef below will make this work with the current code. 40 * In the next BIC version of TagLib this will be really moved into the Ogg 41 * namespace. 42 */ 43 44 #ifdef DOXYGEN 45 namespace Ogg { 46 #endif 47 48 //! A namespace containing classes for Vorbis metadata 49 50 namespace Vorbis { 51 52 53 //! An implementation of Ogg::File with Vorbis specific methods 54 55 /*! 56 * This is the central class in the Ogg Vorbis metadata processing collection 57 * of classes. It's built upon Ogg::File which handles processing of the Ogg 58 * logical bitstream and breaking it down into pages which are handled by 59 * the codec implementations, in this case Vorbis specifically. 60 */ 61 62 class TAGLIB_EXPORT File : public Ogg::File 63 { 64 public: 65 /*! 66 * Constructs a Vorbis file from \a file. If \a readProperties is true the 67 * file's audio properties will also be read. 68 * 69 * \note In the current implementation, \a propertiesStyle is ignored. 70 */ 71 File(FileName file, bool readProperties = true, 72 Properties::ReadStyle propertiesStyle = Properties::Average); 73 74 /*! 75 * Constructs a Vorbis file from \a stream. If \a readProperties is true the 76 * file's audio properties will also be read. 77 * 78 * \note TagLib will *not* take ownership of the stream, the caller is 79 * responsible for deleting it after the File object. 80 * 81 * \note In the current implementation, \a propertiesStyle is ignored. 82 */ 83 File(IOStream *stream, bool readProperties = true, 84 Properties::ReadStyle propertiesStyle = Properties::Average); 85 86 /*! 87 * Destroys this instance of the File. 88 */ 89 virtual ~File(); 90 91 /*! 92 * Returns the XiphComment for this file. XiphComment implements the tag 93 * interface, so this serves as the reimplementation of 94 * TagLib::File::tag(). 95 */ 96 virtual Ogg::XiphComment *tag() const; 97 98 99 /*! 100 * Implements the unified property interface -- export function. 101 * This forwards directly to XiphComment::properties(). 102 */ 103 PropertyMap properties() const; 104 105 /*! 106 * Implements the unified tag dictionary interface -- import function. 107 * Like properties(), this is a forwarder to the file's XiphComment. 108 */ 109 PropertyMap setProperties(const PropertyMap &); 110 111 /*! 112 * Returns the Vorbis::Properties for this file. If no audio properties 113 * were read then this will return a null pointer. 114 */ 115 virtual Properties *audioProperties() const; 116 117 /*! 118 * Save the file. 119 * 120 * This returns true if the save was successful. 121 */ 122 virtual bool save(); 123 124 /*! 125 * Check if the given \a stream can be opened as an Ogg Vorbis file. 126 * 127 * \note This method is designed to do a quick check. The result may 128 * not necessarily be correct. 129 */ 130 static bool isSupported(IOStream *stream); 131 132 private: 133 File(const File &); 134 File &operator=(const File &); 135 136 void read(bool readProperties); 137 138 class FilePrivate; 139 FilePrivate *d; 140 }; 141 } 142 143 /* 144 * To keep compatibility with the current version put Vorbis in the Ogg namespace 145 * only in the docs and provide a typedef to make it work. In the next BIC 146 * version this will be removed and it will only exist in the Ogg namespace. 147 */ 148 149 #ifdef DOXYGEN 150 } 151 #else 152 namespace Ogg { namespace Vorbis { typedef TagLib::Vorbis::File File; } } 153 #endif 154 155 } 156 157 #endif 158