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