runtime/nepomuk/kioslaves/search/queryserviceclient.h

   1 /*
   2    Copyright (c) 2008 Sebastian Trueg <trueg@kde.org>
   3
   4    This library is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU Library General Public
   6    License version 2 as published by the Free Software Foundation.
   7
   8    This library is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11    Library General Public License for more details.
  12
  13    You should have received a copy of the GNU Library General Public License
  14    along with this library; see the file COPYING.LIB.  If not, write to
  15    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16    Boston, MA 02110-1301, USA.
  17 */
  18
  19 #ifndef _NEPOMUK_QUERY_SERVICE_CLIENT_H_
  20 #define _NEPOMUK_QUERY_SERVICE_CLIENT_H_
  21
  22 #include <QtCore/QObject>
  23
  24 class QUrl;
  25
  26 namespace Nepomuk {
  27     namespace Search {
  28
  29         class Result;
  30         class Query;
  31
  32         /**
  33          * \class QueryServiceClient queryserviceclient.h Nepomuk/Search/QueryServiceClient
  34          *
  35          * \brief Convenience frontend to the %Nepomuk Query DBus Service
  36          *
  37          * The QueryServiceClient provides an easy way to access the %Nepomuk Query Service
  38          * without having to deal with any communication details. By default it monitors
  39          * queries for changes.
  40          *
  41          * Usage is simple: Create an instance of the client for each search you want to
  42          * track. Once instance may also be reused for subsequent queries if further updates
  43          * of the persistent query are not necessary.
  44          *
  45          * \author Sebastian Trueg <trueg@kde.org>
  46          */
  47         class QueryServiceClient : public QObject
  48         {
  49             Q_OBJECT
  50
  51         public:
  52             /**
  53              * Create a new QueryServiceClient instance.
  54              */
  55             QueryServiceClient( QObject* parent = 0 );
  56
  57             /**
  58              * Desctructor. Closes the query.
  59              */
  60             ~QueryServiceClient();
  61
  62             /**
  63              * Check if the service is running.
  64              * \return \p true if the Nepomuk query service is running and could
  65              * be contacted via DBus, \p false otherwise
  66              */
  67             static bool serviceAvailable();
  68
  69         public Q_SLOTS:
  70             /**
  71              * Start a query using the Nepomuk user query language.
  72              *
  73              * Results will be reported via newEntries. All results
  74              * have been reported once finishedListing has been emitted.
  75              *
  76              * \return \p true if the query service was found and the query
  77              * was started. \p false otherwise.
  78              *
  79              * \sa QueryParser
  80              */
  81             bool query( const QString& query );
  82
  83             /**
  84              * Start a query.
  85              *
  86              * Results will be reported via newEntries. All results
  87              * have been reported once finishedListing has been emitted.
  88              *
  89              * \return \p true if the query service was found and the query
  90              * was started. \p false otherwise.
  91              */
  92             bool query( const Query& query );
  93
  94             /**
  95              * Start a query using the Nepomuk user query language.
  96              *
  97              * Results will be reported as with query(const QString&)
  98              * but a local event loop will be started to block the method
  99              * call until all results have been listed.
 100              *
 101              * The client will be closed after the initial listing. Thus,
 102              * changes to results will not be reported as it is the case
 103              * with the non-blocking methods.
 104              *
 105              * \return \p true if the query service was found and the query
 106              * was started. \p false otherwise.
 107              *
 108              * \sa query(const QString&), close()
 109              */
 110             bool blockingQuery( const QString& query );
 111
 112             /**
 113              * \overload
 114              *
 115              * \sa query(const Query&)
 116              */
 117             bool blockingQuery( const Query& query );
 118
 119             /**
 120              * Close the client, thus stop to monitor the query
 121              * for changes. Without closing the client it will continue
 122              * signalling changes to the results.
 123              *
 124              * This will also make any blockingQuery return immediately.
 125              */
 126             void close();
 127
 128         Q_SIGNALS:
 129             /**
 130              * Emitted for new search results. This signal is emitted both
 131              * for the initial listing and for changes to the search.
 132              */
 133             void newEntries( const QList<Nepomuk::Search::Result>& entries );
 134
 135             /**
 136              * Emitted if the search results changed when monitoring a query.
 137              * \param entries A list of resource URIs identifying the resources
 138              * that dropped out of the query results.
 139              */
 140             void entriesRemoved( const QList<QUrl>& entries );
 141
 142             /**
 143              * Emitted when the initial listing has been finished, ie. if all
 144              * results have been reported via newEntries. If no further updates
 145              * are necessary the client should be closed now.
 146              */
 147             void finishedListing();
 148
 149         private:
 150             class Private;
 151             Private* const d;
 152
 153             Q_PRIVATE_SLOT( d, void _k_entriesRemoved( const QStringList& ) )
 154             Q_PRIVATE_SLOT( d, void _k_finishedListing() )
 155         };
 156     }
 157 }
 158
 159 #endif