2
* Copyright (C) 2015 Canonical Ltd
4
* This program is free software: you can redistribute it and/or modify
5
* it under the terms of the GNU Lesser General Public License version 3 as
6
* published by the Free Software Foundation.
8
* This program 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
11
* GNU Lesser General Public License for more details.
13
* You should have received a copy of the GNU Lesser General Public License
14
* along with this program. If not, see <http://www.gnu.org/licenses/>.
16
* Authored by: Xavi Garcia <xavi.garcia.mena@canonical.com>
21
#include <unity/util/DefinesPtrs.h>
22
#include <unity/util/NonCopyable.h>
23
#include <unity/scopes/SearchListenerBase.h>
24
#include <unity/scopes/QueryCtrlProxyFwd.h>
26
#include <unity/scopes/qt/QSearchReplyProxy.h>
27
#include <unity/scopes/qt/QCannedQuery.h>
43
class QSearchQueryBaseImpl;
46
class QSearchQueryBaseAPI;
49
\brief Abstract base class to represent a particular query.
51
A scope must return an instance of this class from its implementation of ScopeBase::create_query().
53
\note The constructor of the instance must complete in a timely manner. Do not perform anything in the
54
constructor that might block.
56
class QSearchQueryBase
58
friend class QSearchQueryBaseAPI;
62
NONCOPYABLE(QSearchQueryBase);
63
UNITY_DEFINES_PTRS(QSearchQueryBase);
66
virtual ~QSearchQueryBase();
69
\brief Called by scopes run time to start the query.
71
Your implementation of run() can use the reply proxy to push results
72
for the query. You can push results from within run(), in which case
73
the query implicitly completes when run() returns. Alternatively,
74
run() can store the reply proxy and return immediately. In this
75
case, you can use the stored proxy to push results from another
76
thread. It is safe to call `push()` from multiple threads without
79
The query completes either when run() returns, or when the
80
last stored reply proxy goes out of scope (whichever happens
83
\param reply The proxy on which to push results for the query.
85
virtual void run(QSearchReplyProxy const& reply) = 0;
88
\brief Called by the scopes run time when the query originator
91
Your implementation of this method should ensure that the scope stops
92
processing the current query as soon as possible. Any calls to a `push()` method
93
once a query is cancelled are ignored, so continuing to push after cancellation
94
only wastes CPU cycles. (`push()` returns `false` once a query is cancelled or
95
exceeds its cardinality limit.)
97
virtual void cancelled() = 0; // Originator cancelled the query
100
\brief Get a canned query for this search request.
102
\return The canned query.
103
\throws unity::LogicException if the canned query was not initialized (was default-constructed).
105
QCannedQuery query() const;
108
\brief Get metadata for this search request.
109
\return The search metadata.
110
\throws unity::LogicException if search metadata was not initialized (was default-constructed).
112
unity::scopes::SearchMetadata search_metadata() const;
114
/** @name Subquery methods
115
The subsearch() methods are for use by aggregating scopes.
116
When an aggregator passes a query to its child scopes, it should
117
use subsearch() instead of the normal Scope::search()
118
that would be called by a client. subsearch() takes care
119
of automatically forwarding query cancellation to child scopes.
120
This means that there is no need for an aggregating scope to
121
explicitly forward cancellation to child scopes
122
when its QueryBase::cancelled() method is called by the scopes
126
QueryCtrlProxy subsearch(ScopeProxy const& scope,
127
std::string const& query_string,
128
SearchListenerBase::SPtr const& reply);
129
QueryCtrlProxy subsearch(ScopeProxy const& scope,
130
std::string const& query_string,
131
FilterState const& filter_state,
132
SearchListenerBase::SPtr const& reply);
133
QueryCtrlProxy subsearch(ScopeProxy const& scope,
134
std::string const& query_string,
135
std::string const& department_id,
136
FilterState const& filter_state,
137
SearchListenerBase::SPtr const& reply);
138
QueryCtrlProxy subsearch(ScopeProxy const& scope,
139
std::string const& query_string,
140
std::string const& department_id,
141
FilterState const& filter_state,
142
SearchMetadata const& hints,
143
SearchListenerBase::SPtr const& reply);
150
void init(QSearchQueryBaseAPI* query_api);
152
std::unique_ptr<internal::QSearchQueryBaseImpl> p;
153
friend class internal::QSearchQueryBaseImpl;
159
} // namespace scopes