/*************************************************************************** copyright : (C) 2004 by Scott Wheeler email : wheeler@kde.org ***************************************************************************/ /*************************************************************************** * This library is free software; you can redistribute it and/or modify * * it under the terms of the GNU Lesser General Public License version * * 2.1 as published by the Free Software Foundation. * * * * This library is distributed in the hope that it will be useful, but * * WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * * Lesser General Public License for more details. * * * * You should have received a copy of the GNU Lesser General Public * * License along with this library; if not, write to the Free Software * * Foundation, Inc., 51 Franklin Steet, Fifth Floor, Boston, MA 02110-1301 * * USA * ***************************************************************************/ /* * At some point this will likely be a library class, as such it's been written * as such and is LGPL'ed. */ #ifndef KTRM_H #define KTRM_H #include #include #include #include /** * This represents a potential match for a TRM lookup. KTRMResultList is * returned from KTRMLookup and will be sorted by relevance (better matches * at the beginning of the list). */ namespace KIO { class Job; } class KTRMResult { friend class KTRMLookup; public: KTRMResult(); KTRMResult(const KTRMResult &result); ~KTRMResult(); /** * Returns the title of the track for the potential match. */ TQString title() const; /** * Returns the artist name of the track for the potential match. */ TQString artist() const; /** * Returns the album name of the track for the potential match. */ TQString album() const; /** * Returns the track number of the track for the potential match. */ int track() const; /** * Returns the original release year of the track for the potential match. */ int year() const; /** * Returns true if all of the values for the result are empty. */ bool isEmpty() const; /** * Compares to \a r based on the relevance of the match. Better matches * will be greater than less accurate matches. */ bool operator<(const KTRMResult &r) const; /** * Compares to \a r based on the relevance of the match. Better matches * will be greater than less accurate matches. */ bool operator>(const KTRMResult &r) const; /** * Basic assignment operator; required for the TQTL */ KTRMResult &operator= (const KTRMResult &r); /** * Basic comparison operator; required for the TQTL */ bool operator== (const KTRMResult &r) const; private: class KTRMResultPrivate; KTRMResultPrivate *d; }; typedef TQValueList KTRMResultList; /** * An abstraction for libtunepimp's TRM based lookup and file recognition. * * A lookup is started when the object is created. One of the virtual methods * -- recognized(), unrecognized(), collision() or error(). Those methods * should be reimplemented in subclasses to specify what behavior should happen * for each result. * * The lookups themselves happen in a background thread, but the return calls * are guaranteed to run in the GUI thread. */ class KTRMLookup : public TQObject { Q_OBJECT TQ_OBJECT signals: void sigResult( KTRMResultList, TQString ); protected slots: virtual void lookupResult( KIO::Job* ); public: /** * Creates and starts a lookup for \a file. If \a autoDelete is set to * true the lookup will delete itself when it has finished. */ KTRMLookup(const TQString &file, bool autoDelete = false); virtual ~KTRMLookup(); /** * Returns the file name that was specified in the constructor. */ TQString file() const; /** * Returns the TunePimp file ID for the file. This is of no use to the * public API. * * @internal */ int fileId() const; /** * This method is called when the puid was already generated. It will then do * the lookup with MusicBrainz's server. This may be reimplemented to provide * specific behavion for the lookup. */ virtual void puidGenerated(); /** * This method is called if the track was recognized by the TRM server. * results() will return just one value. This may be reimplemented to * provide specific behavion in the case of the track being recognized. * * \note The base class call should happen at the beginning of the subclass * reimplementation; it populates the values of results(). */ virtual void recognized(); /** * This method is called if the track was not recognized by the TRM server. * results() will return an empty set. This may be reimplemented to provide * specific behavion in the case of the track not being recognized. */ virtual void unrecognized(); /** * This method is called if there are multiple potential matches for the TRM * value. results() will return a list of the potential matches, sorted by * liklihood. This may be reimplemented to provide * specific behavion in the case of the track not being recognized. * * \note The base class call should happen at the beginning of the subclass * reimplementation; it populates the values of results(). */ virtual void collision(); /** * This method is called if the track was not recognized by the TRM server. * results() will return an empty set. This may be reimplemented to provide * specific behavion in the case of the track not being recognized. */ virtual void error(); /** * Returns the list of matches found by the lookup. In the case that there * was a TRM collision this list will contain multiple entries. In the case * that it was recognized this will only contain one entry. Otherwise it * will remain empty. */ KTRMResultList results() const; protected: /** * This method is called when any of terminal states (recognized, * unrecognized, collision or error) has been reached after the specific * method for the result has been called. * * This should be reimplemented in the case that there is some general * processing to be done for all terminal states. */ virtual void finished(); private: class KTRMLookupPrivate; KTRMLookupPrivate *d; }; /** * Helper Functions used for sorting MusicBrainz results */ double stringSimilarity(TQString s1, TQString s2); double stringSimilarity(TQStringList &l, TQString &s); #endif /*KTRM_H*/