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_SCOPES_VERSIONED_CREATE_SYM
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 
138 {
139 public:
141  NONCOPYABLE(ScopeBase);
142  virtual ~ScopeBase();
144 
157  virtual void start(std::string const& scope_id, RegistryProxy const& registry);
158 
170  virtual void stop();
171 
182  virtual void run();
183 
195  virtual SearchQueryBase::UPtr search(CannedQuery const& query, SearchMetadata const& metadata) = 0;
196 
210  virtual ActivationQueryBase::UPtr activate(Result const& result, ActionMetadata const& metadata);
211 
227  virtual ActivationQueryBase::UPtr perform_action(Result const& result, ActionMetadata const& metadata, std::string const& widget_id, std::string const& action_id);
228 
240  virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
241 
245  static void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
246 
255  std::string scope_directory() const;
256 
270  VariantMap settings() const;
271 
272 protected:
274  ScopeBase();
275 private:
276  std::unique_ptr<internal::ScopeBaseImpl> p;
277 
278  friend class internal::ScopeLoader;
279  friend class internal::ScopeObject;
280  friend class internal::RuntimeImpl;
282 };
283 
284 } // namespace scopes
285 
286 } // namespace unity
287 
300 
310 
311 namespace unity
312 {
313 
314 namespace scopes
315 {
316 
321 
326 
327 } // namespace scopes
328 
329 } // namespace unity
330 
331 #endif
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:67
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:137
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()
Called by the scopes run time when the scope should shut down.
Definition: ScopeBase.cpp:47
std::map< std::string, Variant > VariantMap
A dictionary of (string, Variant) pairs.
Definition: Variant.h:39
std::string scope_directory() const
Returns the directory that stores the scope's configuration files and shared library.
Definition: ScopeBase.cpp:74
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:52
#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:320
#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:57
decltype(&UNITY_SCOPE_DESTROY_FUNCTION) typedef DestroyFunction
Convenience typedef for the destroy function pointer.
Definition: ScopeBase.h:325
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:62
VariantMap settings() const
Returns a dictionary with the scope's current settings.
Definition: ScopeBase.cpp:79
virtual void start(std::string const &scope_id, RegistryProxy const &registry)
Called by the scopes run time after the create function completes.
Definition: ScopeBase.cpp:42