src/ktrm.h

   1 /***************************************************************************
   2     copyright            : (C) 2004 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 Steet, Fifth Floor, Boston, MA  02110-1301  *
  19  *   USA                                                                   *
  20  ***************************************************************************/
  21
  22 /*
  23  * At some point this will likely be a library class, as such it's been written
  24  * as such and is LGPL'ed.
  25  */
  26
  27 #ifndef KTRM_H
  28 #define KTRM_H
  29
  30 #include <QObject>
  31 #include <qmap.h>
  32 #include <QString>
  33 #include <q3valuelist.h>
  34
  35 /**
  36  * This represents a potential match for a TRM lookup.  KTRMResultList is
  37  * returned from KTRMLookup and will be sorted by relevance (better matches
  38  * at the beginning of the list).
  39  */
  40
  41 namespace KIO { class Job; }
  42
  43 class KTRMResult
  44 {
  45     friend class KTRMLookup;
  46
  47 public:
  48     KTRMResult();
  49     KTRMResult(const KTRMResult &result);
  50     ~KTRMResult();
  51
  52     /**
  53      * Returns the title of the track for the potential match.
  54      */
  55     QString title() const;
  56
  57     /**
  58      * Returns the artist name of the track for the potential match.
  59      */
  60     QString artist() const;
  61
  62     /**
  63      * Returns the album name of the track for the potential match.
  64      */
  65     QString album() const;
  66
  67     /**
  68      * Returns the track number of the track for the potential match.
  69      */
  70     int track() const;
  71
  72     /**
  73      * Returns the original release year of the track for the potential match.
  74      */
  75     int year() const;
  76
  77     /**
  78      * Returns true if all of the values for the result are empty.
  79      */
  80     bool isEmpty() const;
  81
  82     /**
  83      * Compares to \a r based on the relevance of the match.  Better matches
  84      * will be greater than less accurate matches.
  85      */
  86     bool operator<(const KTRMResult &r) const;
  87
  88     /**
  89      * Compares to \a r based on the relevance of the match.  Better matches
  90      * will be greater than less accurate matches.
  91      */
  92     bool operator>(const KTRMResult &r) const;
  93
  94     /**
  95      * Basic assignment operator; required for the QTL
  96      */
  97     KTRMResult &operator= (const KTRMResult &r);
  98
  99     /**
 100      * Basic comparison operator; required for the QTL
 101      */
 102     bool operator== (const KTRMResult &r) const;
 103
 104 private:
 105     class KTRMResultPrivate;
 106     KTRMResultPrivate *d;
 107 };
 108
 109 typedef Q3ValueList<KTRMResult> KTRMResultList;
 110
 111 /**
 112  * An abstraction for libtunepimp's TRM based lookup and file recognition.
 113  *
 114  * A lookup is started when the object is created.  One of the virtual methods
 115  * -- recognized(), unrecognized(), collision() or error().  Those methods
 116  * should be reimplemented in subclasses to specify what behavior should happen
 117  * for each result.
 118  *
 119  * The lookups themselves happen in a background thread, but the return calls
 120  * are guaranteed to run in the GUI thread.
 121  */
 122 class KTRMLookup : public QObject
 123 {
 124 Q_OBJECT
 125
 126 signals:
 127     void sigResult( KTRMResultList, QString );
 128
 129 protected slots:
 130     virtual void lookupResult( KIO::Job* );
 131
 132 public:
 133     /**
 134      * Creates and starts a lookup for \a file.  If \a autoDelete is set to
 135      * true the lookup will delete itself when it has finished.
 136      */
 137     explicit KTRMLookup(const QString &file, bool autoDelete = false);
 138
 139     virtual ~KTRMLookup();
 140
 141     /**
 142      * Returns the file name that was specified in the constructor.
 143      */
 144     QString file() const;
 145
 146     /**
 147      * Returns the TunePimp file ID for the file.  This is of no use to the
 148      * public API.
 149      *
 150      * @internal
 151      */
 152     int fileId() const;
 153
 154     /**
 155      * This method is called when the puid was already generated. It will then do
 156      * the lookup with MusicBrainz's server. This may be reimplemented to provide
 157      * specific behavion for the lookup.
 158      */
 159     virtual void puidGenerated();
 160
 161     /**
 162      * This method is called if the track was recognized by the TRM server.
 163      * results() will return just one value.  This may be reimplemented to
 164      * provide specific behavion in the case of the track being recognized.
 165      *
 166      * \note The base class call should happen at the beginning of the subclass
 167      * reimplementation; it populates the values of results().
 168      */
 169     virtual void recognized();
 170
 171     /**
 172      * This method is called if the track was not recognized by the TRM server.
 173      * results() will return an empty set.  This may be reimplemented to provide
 174      * specific behavion in the case of the track not being recognized.
 175      */
 176     virtual void unrecognized();
 177
 178     /**
 179      * This method is called if there are multiple potential matches for the TRM
 180      * value.  results() will return a list of the potential matches, sorted by
 181      * liklihood.  This may be reimplemented to provide
 182      * specific behavion in the case of the track not being recognized.
 183      *
 184      * \note The base class call should happen at the beginning of the subclass
 185      * reimplementation; it populates the values of results().
 186      */
 187     virtual void collision();
 188
 189     /**
 190      * This method is called if the track was not recognized by the TRM server.
 191      * results() will return an empty set.  This may be reimplemented to provide
 192      * specific behavion in the case of the track not being recognized.
 193      */
 194     virtual void error();
 195
 196     /**
 197      * Returns the list of matches found by the lookup.  In the case that there
 198      * was a TRM collision this list will contain multiple entries.  In the case
 199      * that it was recognized this will only contain one entry.  Otherwise it
 200      * will remain empty.
 201      */
 202     KTRMResultList results() const;
 203
 204 protected:
 205     /**
 206      * This method is called when any of terminal states (recognized,
 207      * unrecognized, collision or error) has been reached after the specific
 208      * method for the result has been called.
 209      *
 210      * This should be reimplemented in the case that there is some general
 211      * processing to be done for all terminal states.
 212      */
 213     virtual void finished();
 214
 215 private:
 216     class KTRMLookupPrivate;
 217     KTRMLookupPrivate *d;
 218 };
 219
 220 /**
 221  * Helper Functions used for sorting MusicBrainz results
 222  */
 223 double stringSimilarity(QString s1, QString s2);
 224 double stringSimilarity(QStringList &l, QString &s);
 225
 226 #endif /*KTRM_H*/