Unity Scopes API
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 #pragma once
20 
21 #include <unity/scopes/AbstractScopeBase.h>
22 #include <unity/scopes/ActionMetadata.h>
23 #include <unity/scopes/SearchMetadata.h>
24 #include <unity/scopes/Version.h>
25 
29 #define UNITY_SCOPE_CREATE_FUNCTION UNITY_SCOPES_VERSIONED_CREATE_SYM
30 
34 #define UNITY_SCOPE_DESTROY_FUNCTION unity_scope_destroy
35 
36 // Convenience definitions for looking up the create and destroy functions in the symbol table
37 // of a dynamically loaded scope.
38 // UNITY_SCOPE_CREATE_SYMSTR and UNITY_SCOPE_DESTROY_SYMSTR expand to a string literal containing the name
39 // of the create and destroy function, respectively.
40 
41 #ifndef DOXYGEN_SKIP
42 # define UNITY_SCOPE_STR(sym) #sym
43 # define UNITY_SCOPE_XSTR(sym) UNITY_SCOPE_STR(sym)
44 #endif
45 
49 #define UNITY_SCOPE_CREATE_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_CREATE_FUNCTION)
50 
54 #define UNITY_SCOPE_DESTROY_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_DESTROY_FUNCTION)
55 
56 namespace unity
57 {
58 
59 namespace scopes
60 {
61 
62 class CannedQuery;
63 
64 namespace internal
65 {
66 
67 class ScopeBaseImpl;
68 class RuntimeImpl;
69 
70 }
71 
72 namespace testing
73 {
74 
75 class TypedScopeFixtureHelper;
76 
77 }
78 
139 {
140 public:
142  NONCOPYABLE(ScopeBase);
143  virtual ~ScopeBase();
145 
155  virtual void start(std::string const& scope_id);
156 
168  virtual void stop();
169 
180  virtual void run();
181 
193  virtual SearchQueryBase::UPtr search(CannedQuery const& query, SearchMetadata const& metadata) = 0;
194 
208  virtual ActivationQueryBase::UPtr activate(Result const& result, ActionMetadata const& metadata);
209 
225  virtual ActivationQueryBase::UPtr perform_action(Result const& result,
226  ActionMetadata const& metadata,
227  std::string const& widget_id,
228  std::string const& action_id);
229 
241  virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
242 
246  static void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
247 
257  virtual std::string scope_directory() const final;
258 
271  virtual std::string cache_directory() const final;
272 
288  virtual std::string app_directory() const final;
289 
303  virtual std::string tmp_directory() const final;
304 
314  virtual unity::scopes::RegistryProxy registry() const final;
315 
332  virtual VariantMap settings() const final;
333 
350  virtual ChildScopeList find_child_scopes() const;
351 
360  virtual ChildScopeList child_scopes() const final;
361 
376  virtual ActivationQueryBase::UPtr activate_result_action(Result const& result,
377  ActionMetadata const& metadata,
378  std::string const& action_id);
379 
380 protected:
382  ScopeBase();
383 private:
384  std::unique_ptr<internal::ScopeBaseImpl> p;
385 
386  friend class internal::RuntimeImpl;
387  friend class internal::ScopeObject;
388  friend class testing::TypedScopeFixtureHelper;
390 };
391 
392 } // namespace scopes
393 
394 } // namespace unity
395 
411 
421 
422 namespace unity
423 {
424 
425 namespace scopes
426 {
427 
432 
437 
438 } // namespace scopes
439 
440 } // namespace unity
virtual ChildScopeList child_scopes() const final
Returns the current list of child scopes aggregated by this scope.
Definition: ScopeBase.cpp:117
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.
virtual VariantMap settings() const final
Returns a dictionary with the scope's current settings.
Definition: ScopeBase.cpp:107
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:75
Metadata passed with search requests.
Definition: SearchMetadata.h:45
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:138
Metadata passed to scopes for preview and activation.
Definition: ActionMetadata.h:41
The attributes of a result returned by a Scope.
Definition: Result.h:50
virtual void stop()
Called by the scopes run time when the scope should shut down.
Definition: ScopeBase.cpp:48
Definition: OnlineAccountClient.h:39
virtual std::string scope_directory() const final
Returns the directory that stores the scope's configuration files and shared library.
Definition: ScopeBase.cpp:82
virtual std::string cache_directory() const final
Returns a directory that is (exclusively) writable for the scope.
Definition: ScopeBase.cpp:87
virtual std::string tmp_directory() const final
Returns a tmp directory that is (exclusively) writable for the scope.
Definition: ScopeBase.cpp:97
Top-level namespace for all things Unity-related.
Definition: Version.h:49
std::map< std::string, Variant > VariantMap
A dictionary of (string, Variant) pairs.
Definition: Variant.h:38
Definition: ActionMetadata.h:31
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:53
#define UNITY_SCOPE_CREATE_FUNCTION
Expands to the identifier of the scope create function.
Definition: ScopeBase.h:29
Parameters of a search query.
Definition: CannedQuery.h:49
virtual std::string app_directory() const final
Returns a directory that is shared with an app in the same click package.
Definition: ScopeBase.cpp:92
decltype(&UNITY_SCOPE_CREATE_FUNCTION) typedef CreateFunction
Convenience typedef for the create function pointer.
Definition: ScopeBase.h:431
#define UNITY_SCOPE_DESTROY_FUNCTION
Expands to the identifier of the scope destroy function.
Definition: ScopeBase.h:34
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:58
virtual ChildScopeList find_child_scopes() const
Returns a defaulted list of child scopes aggregated by this scope.
Definition: ScopeBase.cpp:112
decltype(&UNITY_SCOPE_DESTROY_FUNCTION) typedef DestroyFunction
Convenience typedef for the destroy function pointer.
Definition: ScopeBase.h:436
std::shared_ptr< Registry > RegistryProxy
Convenience type definition.
Definition: RegistryProxyFwd.h:33
virtual ActivationQueryBase::UPtr activate_result_action(Result const &result, ActionMetadata const &metadata, std::string const &action_id)
Invoked when a scope is requested to handle a result in-card action.
Definition: ScopeBase.cpp:68
virtual void start(std::string const &scope_id)
Called by the scopes run time after the create function completes.
Definition: ScopeBase.cpp:43
virtual unity::scopes::RegistryProxy registry() const final
Returns the proxy to the registry.
Definition: ScopeBase.cpp:102
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:63
Abstract base class for a scope implementation.
Definition: AbstractScopeBase.h:40
std::vector< ChildScope > ChildScopeList
A list of child scopes.
Definition: ChildScope.h:33