← Back to branch summary

~ubuntu-branches/ubuntu/utopic/ardour3/utopic

« back to all changes in this revision

Viewing changes to libs/taglib/taglib/fileref.h

  • Committer: Package Import Robot
  • Author(s): Felipe Sateler
  • Date: 2013-09-21 19:05:02 UTC
  • Revision ID: package-import@ubuntu.com-20130921190502-8gsftrku6jnzhd7v
Tags: upstream-3.4~dfsg
Import upstream version 3.4~dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
libs/taglib/taglib/fileref.h
 
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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
 
19
 *   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_FILEREF_H
 
27
#define TAGLIB_FILEREF_H
 
28
 
 
29
#include <tfile.h>
 
30
#include <tstringlist.h>
 
31
 
 
32
#include "taglib_export.h"
 
33
#include "audioproperties.h"
 
34
 
 
35
namespace TagLib {
 
36
 
 
37
  class Tag;
 
38
 
 
39
  //! This class provides a simple abstraction for creating and handling files
 
40
 
 
41
  /*!
 
42
   * FileRef exists to provide a minimal, generic and value-based wrapper around
 
43
   * a File.  It is lightweight and implicitly shared, and as such suitable for
 
44
   * pass-by-value use.  This hides some of the uglier details of TagLib::File
 
45
   * and the non-generic portions of the concrete file implementations.
 
46
   *
 
47
   * This class is useful in a "simple usage" situation where it is desirable
 
48
   * to be able to get and set some of the tag information that is similar
 
49
   * across file types.
 
50
   *
 
51
   * Also note that it is probably a good idea to plug this into your mime
 
52
   * type system rather than using the constructor that accepts a file name using
 
53
   * the FileTypeResolver.
 
54
   *
 
55
   * \see FileTypeResolver
 
56
   * \see addFileTypeResolver()
 
57
   */
 
58
 
 
59
  class TAGLIB_EXPORT FileRef
 
60
  {
 
61
  public:
 
62
 
 
63
  //! A class for pluggable file type resolution.
 
64
 
 
65
  /*!
 
66
   * This class is used to add extend TagLib's very basic file name based file
 
67
   * type resolution.
 
68
   *
 
69
   * This can be accomplished with:
 
70
   *
 
71
   * \code
 
72
   *
 
73
   * class MyFileTypeResolver : FileTypeResolver
 
74
   * {
 
75
   *   TagLib::File *createFile(TagLib::FileName *fileName, bool, AudioProperties::ReadStyle)
 
76
   *   {
 
77
   *     if(someCheckForAnMP3File(fileName))
 
78
   *       return new TagLib::MPEG::File(fileName);
 
79
   *     return 0;
 
80
   *   }
 
81
   * }
 
82
   *
 
83
   * FileRef::addFileTypeResolver(new MyFileTypeResolver);
 
84
   *
 
85
   * \endcode
 
86
   *
 
87
   * Naturally a less contrived example would be slightly more complex.  This
 
88
   * can be used to plug in mime-type detection systems or to add new file types
 
89
   * to TagLib.
 
90
   */
 
91
 
 
92
    class TAGLIB_EXPORT FileTypeResolver
 
93
    {
 
94
    public:
 
95
      // do not fix compiler warning about missing virtual destructor
 
96
      // since this would not be binary compatible
 
97
      // let Scott fix it whenever he thinks BIC changes can next be applied
 
98
      /*!
 
99
       * This method must be overridden to provide an additional file type
 
100
       * resolver.  If the resolver is able to determine the file type it should
 
101
       * return a valid File object; if not it should return 0.
 
102
       *
 
103
       * \note The created file is then owned by the FileRef and should not be
 
104
       * deleted.  Deletion will happen automatically when the FileRef passes
 
105
       * out of scope.
 
106
       */
 
107
      virtual File *createFile(FileName fileName,
 
108
                               bool readAudioProperties = true,
 
109
                               AudioProperties::ReadStyle
 
110
                               audioPropertiesStyle = AudioProperties::Average) const = 0;
 
111
      virtual ~FileTypeResolver() {}
 
112
    };
 
113
 
 
114
    /*!
 
115
     * Creates a null FileRef.
 
116
     */
 
117
    FileRef();
 
118
 
 
119
    /*!
 
120
     * Create a FileRef from \a fileName.  If \a readAudioProperties is true then
 
121
     * the audio properties will be read using \a audioPropertiesStyle.  If
 
122
     * \a readAudioProperties is false then \a audioPropertiesStyle will be
 
123
     * ignored.
 
124
     *
 
125
     * Also see the note in the class documentation about why you may not want to
 
126
     * use this method in your application.
 
127
     */
 
128
    explicit FileRef(FileName fileName,
 
129
                     bool readAudioProperties = true,
 
130
                     AudioProperties::ReadStyle
 
131
                     audioPropertiesStyle = AudioProperties::Average);
 
132
 
 
133
    /*!
 
134
     * Contruct a FileRef using \a file.  The FileRef now takes ownership of the
 
135
     * pointer and will delete the File when it passes out of scope.
 
136
     */
 
137
    explicit FileRef(File *file);
 
138
 
 
139
    /*!
 
140
     * Make a copy of \a ref.
 
141
     */
 
142
    FileRef(const FileRef &ref);
 
143
 
 
144
    /*!
 
145
     * Destroys this FileRef instance.
 
146
     */
 
147
    virtual ~FileRef();
 
148
 
 
149
    /*!
 
150
     * Returns a pointer to represented file's tag.
 
151
     *
 
152
     * \warning This pointer will become invalid when this FileRef and all
 
153
     * copies pass out of scope.
 
154
     *
 
155
     * \see File::tag()
 
156
     */
 
157
    Tag *tag() const;
 
158
 
 
159
    /*!
 
160
     * Returns the audio properties for this FileRef.  If no audio properties
 
161
     * were read then this will returns a null pointer.
 
162
     */
 
163
    AudioProperties *audioProperties() const;
 
164
 
 
165
    /*!
 
166
     * Returns a pointer to the file represented by this handler class.
 
167
     *
 
168
     * As a general rule this call should be avoided since if you need to work
 
169
     * with file objects directly, you are probably better served instantiating
 
170
     * the File subclasses (i.e. MPEG::File) manually and working with their APIs.
 
171
     *
 
172
     * This <i>handle</i> exists to provide a minimal, generic and value-based
 
173
     * wrapper around a File.  Accessing the file directly generally indicates
 
174
     * a moving away from this simplicity (and into things beyond the scope of
 
175
     * FileRef).
 
176
     *
 
177
     * \warning This pointer will become invalid when this FileRef and all
 
178
     * copies pass out of scope.
 
179
     */
 
180
    File *file() const;
 
181
 
 
182
    /*!
 
183
     * Saves the file.  Returns true on success.
 
184
     */
 
185
    bool save();
 
186
 
 
187
    /*!
 
188
     * Adds a FileTypeResolver to the list of those used by TagLib.  Each
 
189
     * additional FileTypeResolver is added to the front of a list of resolvers
 
190
     * that are tried.  If the FileTypeResolver returns zero the next resolver
 
191
     * is tried.
 
192
     *
 
193
     * Returns a pointer to the added resolver (the same one that's passed in --
 
194
     * this is mostly so that static inialializers have something to use for
 
195
     * assignment).
 
196
     *
 
197
     * \see FileTypeResolver
 
198
     */
 
199
    static const FileTypeResolver *addFileTypeResolver(const FileTypeResolver *resolver);
 
200
 
 
201
    /*!
 
202
     * As is mentioned elsewhere in this class's documentation, the default file
 
203
     * type resolution code provided by TagLib only works by comparing file
 
204
     * extensions.
 
205
     *
 
206
     * This method returns the list of file extensions that are used by default.
 
207
     *
 
208
     * The extensions are all returned in lowercase, though the comparison used
 
209
     * by TagLib for resolution is case-insensitive.
 
210
     *
 
211
     * \note This does not account for any additional file type resolvers that
 
212
     * are plugged in.  Also note that this is not intended to replace a propper
 
213
     * mime-type resolution system, but is just here for reference.
 
214
     *
 
215
     * \see FileTypeResolver
 
216
     */
 
217
    static StringList defaultFileExtensions();
 
218
 
 
219
    /*!
 
220
     * Returns true if the file (and as such other pointers) are null.
 
221
     */
 
222
    bool isNull() const;
 
223
 
 
224
    /*!
 
225
     * Assign the file pointed to by \a ref to this FileRef.
 
226
     */
 
227
    FileRef &operator=(const FileRef &ref);
 
228
 
 
229
    /*!
 
230
     * Returns true if this FileRef and \a ref point to the same File object.
 
231
     */
 
232
    bool operator==(const FileRef &ref) const;
 
233
 
 
234
    /*!
 
235
     * Returns true if this FileRef and \a ref do not point to the same File
 
236
     * object.
 
237
     */
 
238
    bool operator!=(const FileRef &ref) const;
 
239
 
 
240
    /*!
 
241
     * A simple implementation of file type guessing.  If \a readAudioProperties
 
242
     * is true then the audio properties will be read using
 
243
     * \a audioPropertiesStyle.  If \a readAudioProperties is false then
 
244
     * \a audioPropertiesStyle will be ignored.
 
245
     *
 
246
     * \note You generally shouldn't use this method, but instead the constructor
 
247
     * directly.
 
248
     *
 
249
     * \deprecated
 
250
     */
 
251
    static File *create(FileName fileName,
 
252
                        bool readAudioProperties = true,
 
253
                        AudioProperties::ReadStyle audioPropertiesStyle = AudioProperties::Average);
 
254
 
 
255
 
 
256
  private:
 
257
    class FileRefPrivate;
 
258
    FileRefPrivate *d;
 
259
  };
 
260
 
 
261
} // namespace TagLib
 
262
 
 
263
#endif