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