You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdemultimedia/juk/ktrm.h

198 lines
6.3 KiB

/***************************************************************************
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 Street, 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 <config.h>
#if HAVE_MUSICBRAINZ
#include <tqstring.h>
#include <tqvaluelist.h>
#include <tqmap.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.
*/
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;
private:
class KTRMResultPrivate;
KTRMResultPrivate *d;
};
typedef TQValueList<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 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 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