summaryrefslogtreecommitdiffstats
path: root/juk/ktrm.h
diff options
context:
space:
mode:
authortoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
committertoma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2009-11-25 17:56:58 +0000
commite2de64d6f1beb9e492daf5b886e19933c1fa41dd (patch)
tree9047cf9e6b5c43878d5bf82660adae77ceee097a /juk/ktrm.h
downloadtdemultimedia-e2de64d6f1beb9e492daf5b886e19933c1fa41dd.tar.gz
tdemultimedia-e2de64d6f1beb9e492daf5b886e19933c1fa41dd.zip
Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.
BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdemultimedia@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'juk/ktrm.h')
-rw-r--r--juk/ktrm.h197
1 files changed, 197 insertions, 0 deletions
diff --git a/juk/ktrm.h b/juk/ktrm.h
new file mode 100644
index 00000000..028a436b
--- /dev/null
+++ b/juk/ktrm.h
@@ -0,0 +1,197 @@
+/***************************************************************************
+ 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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
+ * 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 <config.h>
+
+#if HAVE_MUSICBRAINZ
+
+#include <qstring.h>
+#include <qvaluelist.h>
+#include <qmap.h>
+
+/**
+ * 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).
+ */
+
+class KTRMResult
+{
+ friend class KTRMLookup;
+
+public:
+ KTRMResult();
+ KTRMResult(const KTRMResult &result);
+ ~KTRMResult();
+
+ /**
+ * Returns the title of the track for the potential match.
+ */
+ QString title() const;
+
+ /**
+ * Returns the artist name of the track for the potential match.
+ */
+ QString artist() const;
+
+ /**
+ * Returns the album name of the track for the potential match.
+ */
+ QString 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;
+
+private:
+ class KTRMResultPrivate;
+ KTRMResultPrivate *d;
+};
+
+typedef QValueList<KTRMResult> 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:
+ /**
+ * 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 QString &file, bool autoDelete = false);
+
+ virtual ~KTRMLookup();
+
+ /**
+ * Returns the file name that was specified in the constructor.
+ */
+ QString 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 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 specifc
+ * 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;
+};
+
+#endif
+#endif