ktrm.h 6.28 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
/***************************************************************************
    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   *
Dirk Mueller's avatar
Dirk Mueller committed
18
 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  *
19 20 21 22 23 24 25 26 27 28 29 30 31
 *   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>

32
#if HAVE_TUNEPIMP
33 34

#include <qstring.h>
Laurent Montel's avatar
Laurent Montel committed
35
#include <q3valuelist.h>
36 37 38
#include <qmap.h>

/**
Scott Wheeler's avatar
Scott Wheeler committed
39 40 41
 * 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).
42 43
 */

Scott Wheeler's avatar
Scott Wheeler committed
44
class KTRMResult
45
{
Scott Wheeler's avatar
Scott Wheeler committed
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
    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;
98 99
};

Laurent Montel's avatar
Laurent Montel committed
100
typedef Q3ValueList<KTRMResult> KTRMResultList;
101

Scott Wheeler's avatar
Scott Wheeler committed
102 103 104 105 106 107 108 109 110 111 112
/**
 * 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.
 */
113 114 115
class KTRMLookup
{
public:
Scott Wheeler's avatar
Scott Wheeler committed
116 117 118 119
    /**
     * Creates and starts a lookup for \a file.  If \a autoDelete is set to
     * true the lookup will delete itself when it has finished.
     */
120
    KTRMLookup(const QString &file, bool autoDelete = false);
Scott Wheeler's avatar
Scott Wheeler committed
121

122 123
    virtual ~KTRMLookup();

Scott Wheeler's avatar
Scott Wheeler committed
124 125 126
    /**
     * Returns the file name that was specified in the constructor.
     */
127 128
    QString file() const;

Scott Wheeler's avatar
Scott Wheeler committed
129 130 131 132 133 134
    /**
     * Returns the TunePimp file ID for the file.  This is of no use to the
     * public API.
     * 
     * @internal
     */
135 136 137 138 139 140
    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.
Scott Wheeler's avatar
Scott Wheeler committed
141 142 143
     *
     * \note The base class call should happen at the beginning of the subclass
     * reimplementation; it populates the values of results().
144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
     */
    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.
Scott Wheeler's avatar
Scott Wheeler committed
159 160 161
     *
     * \note The base class call should happen at the beginning of the subclass
     * reimplementation; it populates the values of results().
162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
     */
    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