ktrm.h 6.27 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
/**
 * Copyright (C) 2004 Scott Wheeler <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
 */
20 21 22 23 24 25 26 27 28

/*
 * 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

29 30
#include <QObject>

31
// FIXME ktrm
32 33
#if 0

34 35 36 37 38 39
template<class T>
class QList;

class QString;
class QStringList;

Laurent Montel's avatar
Laurent Montel committed
40
class KJob;
41

42
/**
43 44 45
 * 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).
46 47
 */

48
class KTRMResult
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 98 99 100 101
    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;
102 103
};

104
typedef QList<KTRMResult> KTRMResultList;
105

106 107 108 109 110 111 112 113 114 115 116
/**
 * 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.
 */
Laurent Montel's avatar
Laurent Montel committed
117
class KTRMLookup : public QObject
118
{
Laurent Montel's avatar
Laurent Montel committed
119 120
Q_OBJECT

121
public:
122 123 124 125
    /**
     * Creates and starts a lookup for \a file.  If \a autoDelete is set to
     * true the lookup will delete itself when it has finished.
     */
126
    explicit KTRMLookup(const QString &file, bool autoDelete = false);
127

128 129
    virtual ~KTRMLookup();

130 131 132
    /**
     * Returns the file name that was specified in the constructor.
     */
133 134
    QString file() const;

135 136 137
    /**
     * Returns the TunePimp file ID for the file.  This is of no use to the
     * public API.
138
     *
139 140
     * @internal
     */
141
    int fileId() const;
Laurent Montel's avatar
Laurent Montel committed
142 143 144 145 146 147
    /**
     * 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();
148 149 150 151 152

    /**
     * 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.
153 154 155
     *
     * \note The base class call should happen at the beginning of the subclass
     * reimplementation; it populates the values of results().
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170
     */
    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.
171 172 173
     *
     * \note The base class call should happen at the beginning of the subclass
     * reimplementation; it populates the values of results().
174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
     */
    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,
195
     * unrecognized, collision or error) has been reached after the specific
196 197 198 199 200 201 202
     * 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();

203 204 205 206 207 208
protected slots:
    virtual void lookupResult( KJob* );

signals:
    void sigResult( KTRMResultList, QString );

209 210 211 212
private:
    class KTRMLookupPrivate;
    KTRMLookupPrivate *d;
};
Laurent Montel's avatar
Laurent Montel committed
213

214 215 216 217 218
/*
 * Helper Functions used for sorting MusicBrainz results
 */
double stringSimilarity(QString s1, QString s2);
double stringSimilarity(const QStringList &l, const QString &s);
219 220

#endif
221

222 223
#endif

224
// vim: set et sw=4 tw=0 sta: