workspace/libs/nepomukqueryclient/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 #include "nepomukqueryclient_export.h"
  25
  26 class QUrl;
  27
  28 namespace Nepomuk {
  29     namespace Search {
  30
  31         class Result;
  32         class Query;
  33
  34         /**
  35          * \class QueryServiceClient queryserviceclient.h Nepomuk/Search/QueryServiceClient
  36          *
  37          * \brief Convenience frontend to the %Nepomuk Query DBus Service
  38          *
  39          * The QueryServiceClient provides an easy way to access the %Nepomuk Query Service
  40          * without having to deal with any communication details. By default it monitors
  41          * queries for changes.
  42          *
  43          * Usage is simple: Create an instance of the client for each search you want to
  44          * track. Once instance may also be reused for subsequent queries if further updates
  45          * of the persistent query are not necessary.
  46          *
  47          * \author Sebastian Trueg <trueg@kde.org>
  48          */
  49         class NEPOMUKQUERYCLIENT_EXPORT QueryServiceClient : public QObject
  50         {
  51             Q_OBJECT
  52
  53         public:
  54             /**
  55              * Create a new QueryServiceClient instance.
  56              */
  57             QueryServiceClient( QObject* parent = 0 );
  58
  59             /**
  60              * Desctructor. Closes the query.
  61              */
  62             ~QueryServiceClient();
  63
  64             /**
  65              * Check if the service is running.
  66              * \return \p true if the Nepomuk query service is running and could
  67              * be contacted via DBus, \p false otherwise
  68              */
  69             static bool serviceAvailable();
  70
  71         public Q_SLOTS:
  72             /**
  73              * Start a query using the Nepomuk user query language.
  74              *
  75              * Results will be reported via newEntries. All results
  76              * have been reported once finishedListing has been emitted.
  77              *
  78              * \return \p true if the query service was found and the query
  79              * was started. \p false otherwise.
  80              *
  81              * \sa QueryParser
  82              */
  83             bool query( const QString& query );
  84
  85             /**
  86              * Start a query.
  87              *
  88              * Results will be reported via newEntries. All results
  89              * have been reported once finishedListing has been emitted.
  90              *
  91              * \return \p true if the query service was found and the query
  92              * was started. \p false otherwise.
  93              */
  94             bool query( const Query& query );
  95
  96             /**
  97              * Start a query using the Nepomuk user query language.
  98              *
  99              * Results will be reported as with query(const QString&)
 100              * but a local event loop will be started to block the method
 101              * call until all results have been listed.
 102              *
 103              * The client will be closed after the initial listing. Thus,
 104              * changes to results will not be reported as it is the case
 105              * with the non-blocking methods.
 106              *
 107              * \return \p true if the query service was found and the query
 108              * was started. \p false otherwise.
 109              *
 110              * \sa query(const QString&), close()
 111              */
 112             bool blockingQuery( const QString& query );
 113
 114             /**
 115              * \overload
 116              *
 117              * \sa query(const Query&)
 118              */
 119             bool blockingQuery( const Query& query );
 120
 121             /**
 122              * Close the client, thus stop to monitor the query
 123              * for changes. Without closing the client it will continue
 124              * signalling changes to the results.
 125              *
 126              * This will also make any blockingQuery return immediately.
 127              */
 128             void close();
 129
 130         Q_SIGNALS:
 131             /**
 132              * Emitted for new search results. This signal is emitted both
 133              * for the initial listing and for changes to the search.
 134              */
 135             void newEntries( const QList<Nepomuk::Search::Result>& entries );
 136
 137             /**
 138              * Emitted if the search results changed when monitoring a query.
 139              * \param entries A list of resource URIs identifying the resources
 140              * that dropped out of the query results.
 141              */
 142             void entriesRemoved( const QList<QUrl>& entries );
 143
 144             /**
 145              * Emitted when the initial listing has been finished, ie. if all
 146              * results have been reported via newEntries. If no further updates
 147              * are necessary the client should be closed now.
 148              */
 149             void finishedListing();
 150
 151         private:
 152             class Private;
 153             Private* const d;
 154
 155             Q_PRIVATE_SLOT( d, void _k_entriesRemoved( const QStringList& ) )
 156             Q_PRIVATE_SLOT( d, void _k_finishedListing() )
 157         };
 158     }
 159 }
 160
 161 #endif