Add a list of the default file extensions that TagLib knows about, as requested

by Stefan.  Also did a few additional updates on the API docs.

CCMAIL:Stefan Gehn <mETz81@web.de>

git-svn-id: svn://anonsvn.kde.org/home/kde/trunk/kdesupport/taglib@438212 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

diff --git a/fileref.cpp b/fileref.cpp
index 587326566b810cece264318c0ea441da3db2712e..f5d4bcaa3f0ddfac5db2f1b327accf0b77b11c08 100644 (file)
--- a/fileref.cpp
+++ b/fileref.cpp
@@ -100,6 +100,18 @@ void FileRef::addFileTypeResolver(const FileTypeResolver *resolver) // static
   FileRefPrivate::fileTypeResolvers.prepend(resolver);
 }
 
+StringList FileRef::defaultFileExtensions()
+{
+  StringList l;
+
+  l.append("ogg");
+  l.append("flac");
+  l.append("mp3");
+  l.append("mpc");
+
+  return l;
+}
+
 bool FileRef::isNull() const
 {
   return !d->file || !d->file->isValid();
@@ -145,6 +157,10 @@ File *FileRef::create(const char *fileName, bool readAudioProperties,
 
   String s = fileName;
 
+  // If this list is updated, the method defaultFileExtensions() should also be
+  // updated.  However at some point that list should be created at the same time
+  // that a default file type resolver is created.
+
   if(s.size() > 4) {
     if(s.substr(s.size() - 4, 4).upper() == ".OGG")
       return new Vorbis::File(fileName, readAudioProperties, audioPropertiesStyle);

diff --git a/fileref.h b/fileref.h
index 2b6352b043d33f0cf3b6313efb71a5d0aace62ea..98be9ab644a0b2857aac4e1ff6e0c174416acf24 100644 (file)
--- a/fileref.h
+++ b/fileref.h
@@ -22,6 +22,8 @@
 #ifndef TAGLIB_FILEREF_H
 #define TAGLIB_FILEREF_H
 
+#include <tstringlist.h>
+
 #include "audioproperties.h"
 
 namespace TagLib {
@@ -101,6 +103,9 @@ namespace TagLib {
                                audioPropertiesStyle = AudioProperties::Average) const = 0;
     };
 
+    /*!
+     * Creates a null FileRef.
+     */
     FileRef();
 
     /*!
@@ -176,9 +181,29 @@ namespace TagLib {
      * additional FileTypeResolver is added to the front of a list of resolvers
      * that are tried.  If the FileTypeResolver returns zero the next resolver
      * is tried.
+     *
+     * \see FileTypeResolver
      */
     static void addFileTypeResolver(const FileTypeResolver *resolver);
 
+    /*!
+     * As is mentioned elsewhere in this class's documentation, the default file
+     * type resolution code provided by TagLib only works by comparing file
+     * extensions.
+     *
+     * This method returns the list of file extensions that are used by default.
+     *
+     * The extensions are all returned in lowercase, though the comparison used
+     * by TagLib for resolution is case-insensitive.
+     *
+     * \note This does not account for any additional file type resolvers that
+     * are plugged in.  Also note that this is not intended to replace a propper
+     * mime-type resolution system, but is just here for reference.
+     *
+     * \see FileTypeResolver
+     */
+    static StringList defaultFileExtensions();
+
     /*!
      * Returns true if the file (and as such other pointers) are null.
      */
@@ -208,11 +233,14 @@ namespace TagLib {
      *
      * \note You generally shouldn't use this method, but instead the constructor
      * directly.
+     *
+     * \deprecated
      */
     static File *create(const char *fileName,
                         bool readAudioProperties = true,
                         AudioProperties::ReadStyle audioPropertiesStyle = AudioProperties::Average);
 
+
   private:
     class FileRefPrivate;
     FileRefPrivate *d;