/usr/include/nepomuk/queryserviceclient.h is in kdelibs5-dev 4:4.13.3-0ubuntu0.5.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 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 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 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 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 | /*
Copyright (c) 2008-2010 Sebastian Trueg <trueg@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 as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) version 3, or any
later version accepted by the membership of KDE e.V. (or its
successor approved by the membership of KDE e.V.), which shall
act as a proxy defined in Section 6 of version 3 of the license.
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, see <http://www.gnu.org/licenses/>.
*/
#ifndef _NEPOMUK_QUERY_SERVICE_CLIENT_H_
#define _NEPOMUK_QUERY_SERVICE_CLIENT_H_
#include <QtCore/QObject>
#include "property.h"
#include "query.h"
#include "nepomukquery_export.h"
class QUrl;
namespace Nepomuk {
namespace Query {
class Result;
/**
* \class QueryServiceClient queryserviceclient.h Nepomuk/Query/QueryServiceClient
*
* \brief Convenience frontend to the %Nepomuk Query DBus Service
*
* The QueryServiceClient provides an easy way to access the %Nepomuk Query Service
* without having to deal with any communication details. By default it monitors
* queries for changes.
*
* Usage is simple: Create an instance of the client for each search you want to
* track. One instance may also be reused for subsequent queries if further updates
* of the persistent query are not necessary.
*
* For quick queries which do not require any updates one of the static query methods
* can be used: syncQuery(), syncSparqlQuery(), or syncDesktopQuery().
*
* \author Sebastian Trueg <trueg@kde.org>
*
* \since 4.4
*/
class NEPOMUKQUERY_EXPORT QueryServiceClient : public QObject
{
Q_OBJECT
public:
/**
* Create a new QueryServiceClient instance.
*/
QueryServiceClient( QObject* parent = 0 );
/**
* Desctructor. Closes the query.
*/
~QueryServiceClient();
/**
* \brief Check if the Nepomuk query service is running.
* \return \p true if the Nepomuk query service is running and could
* be contacted via DBus, \p false otherwise
*/
static bool serviceAvailable();
/**
* Start a query using the Nepomuk query service.
*
* A local event loop will be started to block the method
* call until all results have been listed, and results will be
* returned. You can check if the query was successful through
* the \p ok pointer.
*
* If updates to the query results are required an instance of QueryServiceClient
* should be created and one of the non-static query methods be used.
*
* \param query the query to perform.
* \param ok a valid boolean pointer, which will be set to \p true
* if the query service was found and the query was started, \p false otherwise.
* If you don't want to track errors, you can pass a null pointer instead.
*
* \return a list of \p Result for the given query.
*
* \sa query(const Query&)
*
* \since 4.5
*/
static QList<Nepomuk::Query::Result> syncQuery( const Query& query, bool *ok = 0 );
/**
* \overload
*
* \param query a SPARQL query which binds results to variable \p 'r'.
* \param ok a valid boolean pointer, which will be set to \p true
* if the query service was found and the query was started, \p false otherwise.
* If you don't want to track errors, you can pass a null pointer instead.
* \param requestPropertyMap An optional mapping of variable binding names in \p query
* to their corresponding properties. For details see sparqlQuery.
*
* \sa sparqlQuery(const Query&)
*
* \since 4.5
*/
static QList<Nepomuk::Query::Result> syncSparqlQuery( const QString& query,
const Nepomuk::Query::RequestPropertyMap& requestPropertyMap = Nepomuk::Query::RequestPropertyMap(),
bool *ok = 0 );
/**
* \overload
*
* \param query a desktop query string which can be parsed by QueryParser.
* \param ok a valid boolean pointer, which will be set to \p true
* if the query service was found and the query was started, \p false otherwise.
* If you don't want to track errors, you can pass a null pointer instead.
*
* \sa desktopQuery(const QString&)
*
* \since 4.5
*/
static QList<Nepomuk::Query::Result> syncDesktopQuery( const QString& query, bool *ok = 0 );
public Q_SLOTS:
/**
* Start a query using the Nepomuk query service.
*
* Results will be reported via newEntries. All results
* have been reported once finishedListing has been emitted.
*
* \param query the query to perform.
*
* \return \p true if the query service was found and the query
* was started. \p false otherwise.
*/
bool query( const Query& query );
/**
* \overload
*
* \param query a SPARQL query which binds results to variable \p 'r'.
* \param requestPropertyMap An optional mapping of variable binding names in \p query
* to their corresponding properties. These bindings will then be reported via
* Result::requestProperties(). This map will be constructed automatically when using
* query(const Query&).
*
* \section sparql_query_examples Examples:
*
* Select a simple request property as can also be done via Query::Query:
*
* \code
* QString query = "select ?r ?mtime where { "
* "?r a nfo:FileDataObject . "
* "?r nie:lastModified ?mtime . "
* "}";
*
* QueryServiceClient::RequestPropertyMap requestPropertyMap;
* requestPropertyMap.insert( "mtime", Vocabulary::NIE::lastModified() );
*
* sparqlQuery( query, requestPropertyMap );
* \endcode
*
* This will report the resources themselves and their modification time in the result's request
* properties:
*
* \code
* void handleResult( const Query::Result& results ) {
* QDateTime lastModified = result.requestProperty( Vocabulary::NIE::lastModified() ).toDateTime();
* [...]
* \endcode
*
* While using Query::Query restricts to request properties to diret properties of the
* results using a custom SPARQL query allows to use any binding as request property.
* The used property URI in the mapping does not even need to match anything in the query:
*
* \code
* QString query = "select ?r ?phone where { "
* "?r a nco:PersonContact . "
* "?r nco:hasPhoneNumber ?n . "
* "?n nco:phoneNumber ?phone . "
* "}";
*
* QueryServiceClient::RequestPropertyMap requestPropertyMap;
* requestPropertyMap.insert( "phone", Vocabulary::NCO::hasPhoneNumber() );
* \endcode
*
* \sa Query::requestPropertyMap()
*/
bool sparqlQuery( const QString& query, const Nepomuk::Query::RequestPropertyMap& requestPropertyMap = Nepomuk::Query::RequestPropertyMap() );
/**
* \overload
*
* \param query a desktop query string which can be parsed by QueryParser.
*/
bool desktopQuery( const QString& query );
/**
* Start a query using the Nepomuk query service.
*
* Results will be reported as with query(const QString&)
* but a local event loop will be started to block the method
* call until all results have been listed.
*
* The client will be closed after the initial listing. Thus,
* changes to results will not be reported as it is the case
* with the non-blocking methods.
*
* \param query the query to perform.
*
* \return \p true if the query service was found and the query
* was started. \p false otherwise.
*
* \sa query(const Query&), close()
*/
bool blockingQuery( const Query& query );
/**
* \overload
*
* \param query a SPARQL query which binds results to variable \p 'r'.
* \param requestPropertyMap An optional mapping of variable binding names in \p query
* to their corresponding properties. For details see sparqlQuery.
*
* \sa sparqlQuery(const Query&)
*/
bool blockingSparqlQuery( const QString& query, const Nepomuk::Query::RequestPropertyMap& requestPropertyMap = Nepomuk::Query::RequestPropertyMap() );
/**
* \overload
*
* \param query a desktop query string which can be parsed by QueryParser.
*
* \sa desktopQuery(const QString&), close()
*/
bool blockingDesktopQuery( const QString& query );
/**
* Close the client, thus stop to monitor the query
* for changes. Without closing the client it will continue
* signalling changes to the results.
*
* This will also make any blockingQuery return immediately.
*/
void close();
/**
* \return \p true if all results have been listed (ie. finishedListing() has
* been emitted), close() has been called, or no query was started.
*
* \since 4.6
*/
bool isListingFinished() const;
/**
* The last error message which has been emitted via error() or an
* empty string if there was no error.
*
* \since 4.6
*/
QString errorMessage() const;
Q_SIGNALS:
/**
* Emitted for new search results. This signal is emitted both
* for the initial listing and for changes to the search.
*/
void newEntries( const QList<Nepomuk::Query::Result>& entries );
/**
* Emitted if the search results changed when monitoring a query.
* \param entries A list of resource URIs identifying the resources
* that dropped out of the query results.
*/
void entriesRemoved( const QList<QUrl>& entries );
/**
* The number of results that are reported via newEntries() before the
* finishedListing() signal.
*
* Emitted once the count of the results is available. This might
* happen before the first result is emitted, in between the results, or
* in rare cases it could even happen after all results have been reported.
*
* Also be aware that no count will be provided when using sparqlQuery()
*
* \since 4.6
*/
void resultCount( int count );
/**
* Emitted when the initial listing has been finished, ie. if all
* results have been reported via newEntries. If no further updates
* are necessary the client should be closed now.
*
* In case of an error this signal is not emitted.
*
* \sa error()
*/
void finishedListing();
/**
* Emitted when an error occurs. This typically happens in case the query
* service is not running or does not respond. No further signals will be
* emitted after this one.
*
* \since 4.6
*/
void error( const QString& errorMessage );
/**
* Emitted when the availability of the query service changes
*
* \since 4.8
*/
void serviceAvailabilityChanged( bool running );
private:
class Private;
Private* const d;
Q_PRIVATE_SLOT( d, void _k_entriesRemoved( const QStringList& ) )
Q_PRIVATE_SLOT( d, void _k_finishedListing() )
Q_PRIVATE_SLOT( d, void _k_handleQueryReply(QDBusPendingCallWatcher*) )
Q_PRIVATE_SLOT( d, void _k_serviceRegistered( const QString& ) )
Q_PRIVATE_SLOT( d, void _k_serviceUnregistered( const QString& ) )
};
}
}
#endif
|