src/collection/QueryMaker.h

   1 /*
   2  *  Copyright (c) 2007 Maximilian Kossick <maximilian.kossick@googlemail.com>
   3  *
   4  *  This program is free software; you can redistribute it and/or modify
   5  *  it under the terms of the GNU General Public License as published by
   6  *  the Free Software Foundation; either version 2 of the License, or
   7  *  (at your option) any later version.
   8  *
   9  *  This program is distributed in the hope that it will be useful,
  10  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  *  GNU General Public License for more details.
  13  *
  14  *  You should have received a copy of the GNU General Public License
  15  *  along with this program; if not, write to the Free Software
  16  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  17  */
  18 #ifndef AMAROK_COLLECTION_QUERYMAKER_H
  19 #define AMAROK_COLLECTION_QUERYMAKER_H
  20
  21 #include "amarok_export.h"
  22 #include "Meta.h"
  23
  24 #include <QObject>
  25 #include <QStringList>
  26 #include <QtGlobal>
  27
  28 class AMAROK_EXPORT QueryMaker : public QObject
  29 {
  30     Q_OBJECT
  31
  32     public:
  33         //track metadata
  34         static const qint64 valUrl          = 1LL << 0;
  35         static const qint64 valTitle        = 1LL << 1;
  36         static const qint64 valArtist       = 1LL << 2;
  37         static const qint64 valAlbum        = 1LL << 3;
  38         static const qint64 valGenre        = 1LL << 4;
  39         static const qint64 valComposer     = 1LL << 5;
  40         static const qint64 valYear         = 1LL << 6;
  41         static const qint64 valComment      = 1LL << 7;
  42         static const qint64 valTrackNr      = 1LL << 8;
  43         static const qint64 valDiscNr       = 1LL << 9;
  44         //track data
  45         static const qint64 valLength       = 1LL << 10;
  46         static const qint64 valBitrate      = 1LL << 11;
  47         static const qint64 valSamplerate   = 1LL << 12;
  48         static const qint64 valFilesize     = 1LL << 13;
  49         static const qint64 valFormat       = 1LL << 14;
  50         static const qint64 valCreateDate   = 1LL << 15;
  51         //statistics
  52         static const qint64 valScore        = 1LL << 16;
  53         static const qint64 valRating       = 1LL << 17;
  54         static const qint64 valFirstPlayed  = 1LL << 18;
  55         static const qint64 valLastPlayed   = 1LL << 19;
  56         static const qint64 valPlaycount    = 1LL << 20;
  57
  58         enum AlbumQueryMode { AllAlbums = 0
  59                               , OnlyCompilations = 1
  60                               , OnlyNormalAlbums = 2 };
  61
  62         QueryMaker();
  63         virtual ~QueryMaker();
  64
  65         /**
  66             resets all internal data to the default values. Calling this method is the same
  67             as creating a new QueryMaker.
  68             @return this
  69         */
  70         virtual QueryMaker* reset() = 0;
  71         /**
  72             starts the query. This method returns immediately. All processing is done in one or more
  73             separate worker thread(s). One of the newResultReady signals will be emitted at least once,
  74             followed by the queryDone() signal exactly once. See BlockingQuery for a way to run a query
  75             synchronously.
  76         */
  77         virtual void run() = 0;
  78         /**
  79             aborts a running query. Calling this method aborts a running query as soon as possible. This method returns immediately. No signals will be emitted after calling this method. This
  80             method has no effect if no query is running.
  81         */
  82         virtual void abortQuery() = 0;
  83
  84         /**
  85             returns the number of times one of the newResultReady signals will be emitted
  86             by the QueryMaker instance.
  87          */
  88         virtual int resultCount() const;
  89
  90         /**
  91             starts a query for Meta::Track objects. The results of the query will be returned as
  92             Meta::Track objects, so you have to connect your client to the
  93             newResultReady( QString, Meta::TrackList ) signal (unless you want the results as
  94             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
  95             @return this
  96         */
  97         virtual QueryMaker* startTrackQuery() = 0;
  98         /**
  99             starts a query for Meta::Artist objects. The results of the query will be returned as
 100             Meta::Artist objects, so you have to connect your client to the
 101             newResultReady( QString, Meta::ArtistList ) signal (unless you want the results as
 102             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
 103             @return this
 104         */
 105         virtual QueryMaker* startArtistQuery() = 0;
 106         /**
 107             starts a query for Meta::Album objects. The results of the query will be returned as
 108             Meta::Album objects, so you have to connect your client to the
 109             newResultReady( QString, Meta::AlbumList ) signal (unless you want the results as
 110             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
 111             @return this
 112         */
 113         virtual QueryMaker* startAlbumQuery() = 0;
 114         /**
 115             starts a query for Meta::Genre objects. The results of the query will be returned as
 116             Meta::Genre objects, so you have to connect your client to the
 117             newResultReady( QString, Meta::GenreList ) signal (unless you want the results as
 118             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
 119             @return this
 120         */
 121         virtual QueryMaker* startGenreQuery() = 0;
 122         /**
 123             starts a query for Meta::Composer objects. The results of the query will be returned as
 124             Meta::Composer objects, so you have to connect your client to the
 125             newResultReady( QString, Meta::ComposerList ) signal (unless you want the results as
 126             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
 127             @return this
 128         */
 129         virtual QueryMaker* startComposerQuery() = 0;
 130         /**
 131             starts a query for Meta::Year objects. The results of the query will be returned as
 132             Meta::Year objects, so you have to connect your client to the
 133             newResultReady( QString, Meta::YearList ) signal (unless you want the results as
 134             Meta::Data pointers, see returnResultAsDataPtrs( bool ) for details.
 135             @return this
 136         */
 137         virtual QueryMaker* startYearQuery() = 0;
 138         /**
 139             starts a custom query. unlike the other startX methods, you have to set up the return
 140             values yourself using addReturnValue( qint64 ) and addReturnFunction(). The results will
 141             be returned as a QStringList. Threfore you have to connect to the
 142             newResultReady( QString, QStringList ) signal to receive the results. Calling
 143             returnResultsAsDataPtrs( bool ) has no effect when using a custom query.
 144             @return this
 145         */
 146         virtual QueryMaker* startCustomQuery() = 0;
 147         /**
 148             sets the QueryMaker instance to return Meta::Data objects instead of the actual type.
 149             In some cases it can be useful to ignore the actual type of the result and just work with
 150             the method provided by Meta::Data. Calling this method with resultAsDataPtrs = true causes
 151             the QueryMaker instance to emit the newResultReady( QString, Meta::DataList ) signal
 152             for all query types (except a custom query). Calling the method with resultAsDataPtrs = false
 153             switches back to the normal behaviour.
 154
 155             @return this
 156         */
 157         virtual QueryMaker* returnResultAsDataPtrs( bool resultAsDataPtrs ) = 0;
 158
 159         /**
 160             only works after starting a custom query with startCustomQuery()
 161             @return this
 162           */
 163         virtual QueryMaker* addReturnValue( qint64 value ) = 0;
 164         virtual QueryMaker* orderBy( qint64 value, bool descending = false ) = 0;
 165
 166         virtual QueryMaker* includeCollection( const QString &collectionId ) = 0;
 167         virtual QueryMaker* excludeCollection( const QString &collectionId ) = 0;
 168
 169         virtual QueryMaker* addMatch( const Meta::TrackPtr &track ) = 0;
 170         virtual QueryMaker* addMatch( const Meta::ArtistPtr &artist ) = 0;
 171         virtual QueryMaker* addMatch( const Meta::AlbumPtr &album ) = 0;
 172         virtual QueryMaker* addMatch( const Meta::ComposerPtr &composer ) = 0;
 173         virtual QueryMaker* addMatch( const Meta::GenrePtr &genre ) = 0;
 174         virtual QueryMaker* addMatch( const Meta::YearPtr &year ) = 0;
 175         virtual QueryMaker* addMatch( const Meta::DataPtr &data ) = 0;
 176
 177         virtual QueryMaker* addFilter( qint64 value, const QString &filter, bool matchBegin = false, bool matchEnd = false ) = 0;
 178         virtual QueryMaker* excludeFilter( qint64 value, const QString &filter, bool matchBegin = false, bool matchEnd = false ) = 0;
 179
 180         /**
 181             limit the maximum number of items in a result. the result will have [0..@p size ] items. When this function
 182             is not used, the result size is unbounded. Note: the maximum size applies to each result individually, so if the newResultReady signal is emitted multiple times, each result may have up to @p size items.
 183         */
 184         virtual QueryMaker* limitMaxResultSize( int size ) = 0;
 185
 186         /**
 187          * select the mode for querying albums. If this method is not called,
 188          * QueryMaker defaults to AlbumQueryMode::AllAlbums.
 189          */
 190         virtual QueryMaker* setAlbumQueryMode( AlbumQueryMode mode );
 191
 192         virtual QueryMaker* beginAnd() = 0;
 193         virtual QueryMaker* beginOr() = 0;
 194         virtual QueryMaker* endAndOr() = 0;
 195
 196     signals:
 197         void newResultReady( QString collectionId, Meta::TrackList );
 198         void newResultReady( QString collectionId, Meta::ArtistList );
 199         void newResultReady( QString collectionId, Meta::AlbumList );
 200         void newResultReady( QString collectionId, Meta::GenreList );
 201         void newResultReady( QString collectionId, Meta::ComposerList );
 202         void newResultReady( QString collectionId, Meta::YearList );
 203         void newResultReady( QString collectionId, Meta::DataList );
 204         void newResultReady( QString collectionId, QStringList );
 205
 206         void queryDone();
 207 };
 208
 209 #endif /* AMAROK_COLLECTION_QUERYMAKER_H */
 210