Unity Scopes API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
ScopeBase.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2013 Canonical Ltd
3  *
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.
7  *
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.
12  *
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/>.
15  *
16  * Authored by: Michi Henning <michi.henning@canonical.com>
17  */
18 
19 #ifndef UNITY_SCOPES_SCOPEBASE_H
20 #define UNITY_SCOPES_SCOPEBASE_H
21 
22 #include <unity/scopes/SearchQueryBase.h>
23 #include <unity/scopes/PreviewQueryBase.h>
24 #include <unity/scopes/RegistryProxyFwd.h>
25 #include <unity/scopes/ActivationQueryBase.h>
26 #include <unity/scopes/Version.h>
27 #include <unity/scopes/Result.h>
28 #include <unity/scopes/ActionMetadata.h>
29 #include <unity/scopes/SearchMetadata.h>
30 
34 #define UNITY_SCOPE_CREATE_FUNCTION unity_scope_create
35 
39 #define UNITY_SCOPE_DESTROY_FUNCTION unity_scope_destroy
40 
41 // Convenience definitions for looking up the create and destroy functions in the symbol table
42 // of a dynamically loaded scope.
43 // UNITY_SCOPE_CREATE_SYMSTR and UNITY_SCOPE_DESTROY_SYMSTR expand to a string literal containing the name
44 // of the create and destroy function, respectively.
45 
46 #ifndef DOXYGEN_SKIP
47 # define UNITY_SCOPE_STR(sym) #sym
48 # define UNITY_SCOPE_XSTR(sym) UNITY_SCOPE_STR(sym)
49 #endif
50 
54 #define UNITY_SCOPE_CREATE_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_CREATE_FUNCTION)
55 
59 #define UNITY_SCOPE_DESTROY_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_DESTROY_FUNCTION)
60 
61 namespace unity
62 {
63 
64 namespace scopes
65 {
66 
67 class CannedQuery;
68 
69 namespace internal
70 {
71 class ScopeBaseImpl;
72 class ScopeLoader;
73 class RuntimeImpl;
74 }
75 
137 {
138 public:
140  NONCOPYABLE(ScopeBase);
141  virtual ~ScopeBase();
143 
147  static constexpr int VERSION = UNITY_SCOPES_VERSION_MAJOR;
148 
165  virtual int start(std::string const& scope_id, RegistryProxy const& registry) = 0;
166 
178  virtual void stop() = 0;
179 
190  virtual void run();
191 
203  virtual SearchQueryBase::UPtr search(CannedQuery const& query, SearchMetadata const& metadata) = 0;
204 
218  virtual ActivationQueryBase::UPtr activate(Result const& result, ActionMetadata const& metadata);
219 
235  virtual ActivationQueryBase::UPtr perform_action(Result const& result, ActionMetadata const& metadata, std::string const& widget_id, std::string const& action_id);
236 
248  virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
249 
253  static void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
254 
260  std::string scope_directory() const;
261 
262 protected:
264  ScopeBase();
265 private:
266  std::unique_ptr<internal::ScopeBaseImpl> p;
267 
268  friend class internal::ScopeLoader;
269  friend class internal::RuntimeImpl;
271 };
272 
273 } // namespace scopes
274 
275 } // namespace unity
276 
289 
299 
300 namespace unity
301 {
302 
303 namespace scopes
304 {
305 
310 
315 
316 } // namespace scopes
317 
318 } // namespace unity
319 
320 #endif
static constexpr int VERSION
This value must be returned from the start() method.
Definition: ScopeBase.h:147
virtual PreviewQueryBase::UPtr preview(Result const &result, ActionMetadata const &metadata)=0
Invoked when a scope is requested to create a preview for a particular result.
static void runtime_version(int &v_major, int &v_minor, int &v_micro) noexcept
Returns the version information for the scopes API that the scope was linked with.
Definition: ScopeBase.cpp:57
Metadata passed with search requests.
Definition: SearchMetadata.h:41
virtual SearchQueryBase::UPtr search(CannedQuery const &query, SearchMetadata const &metadata)=0
Called by the scopes run time when a scope needs to instantiate a query.
Base class for a scope implementation.
Definition: ScopeBase.h:136
Metadata passed to scopes for preview and activation.
Definition: ActionMetadata.h:41
The attributes of a result returned by a Scope.
Definition: Result.h:51
virtual void stop()=0
Called by the scopes run time when the scope should shut down.
std::string scope_directory() const
Returns directory where the scope files are.
Definition: ScopeBase.cpp:64
virtual int start(std::string const &scope_id, RegistryProxy const &registry)=0
Called by the scopes run time after the create function completes.
virtual void run()
Called by the scopes run time after it has called start() to hand a thread of control to the scope...
Definition: ScopeBase.cpp:42
#define UNITY_SCOPE_CREATE_FUNCTION
Expands to the identifier of the scope create function.
Definition: ScopeBase.h:34
Parameters of a search query.
Definition: CannedQuery.h:46
decltype(&UNITY_SCOPE_CREATE_FUNCTION) typedef CreateFunction
Convenience typedef for the create function pointer.
Definition: ScopeBase.h:309
#define UNITY_SCOPE_DESTROY_FUNCTION
Expands to the identifier of the scope destroy function.
Definition: ScopeBase.h:39
virtual ActivationQueryBase::UPtr activate(Result const &result, ActionMetadata const &metadata)
Called by the scopes run time when a scope needs to respond to a result activation request...
Definition: ScopeBase.cpp:47
decltype(&UNITY_SCOPE_DESTROY_FUNCTION) typedef DestroyFunction
Convenience typedef for the destroy function pointer.
Definition: ScopeBase.h:314
std::shared_ptr< Registry > RegistryProxy
Convenience type definition.
Definition: RegistryProxyFwd.h:34
virtual ActivationQueryBase::UPtr perform_action(Result const &result, ActionMetadata const &metadata, std::string const &widget_id, std::string const &action_id)
Invoked when a scope is requested to handle a preview action.
Definition: ScopeBase.cpp:52