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 
44 #define UNITY_SCOPE_CREATE_SYMSTR UNITY_SCOPES_VERSION_XSTR(UNITY_SCOPE_CREATE_FUNCTION)
45 
49 #define UNITY_SCOPE_DESTROY_SYMSTR UNITY_SCOPES_VERSION_XSTR(UNITY_SCOPE_DESTROY_FUNCTION)
50 
51 namespace unity
52 {
53 
54 namespace scopes
55 {
56 
57 class CannedQuery;
58 
59 namespace internal
60 {
61 
62 class ScopeBaseImpl;
63 class RuntimeImpl;
64 
65 }
66 
67 namespace testing
68 {
69 
70 class TypedScopeFixtureHelper;
71 
72 }
73 
134 {
135 public:
137  NONCOPYABLE(ScopeBase);
138  virtual ~ScopeBase();
140 
150  virtual void start(std::string const& scope_id);
151 
163  virtual void stop();
164 
175  virtual void run();
176 
188  virtual SearchQueryBase::UPtr search(CannedQuery const& query, SearchMetadata const& metadata) = 0;
189 
203  virtual ActivationQueryBase::UPtr activate(Result const& result, ActionMetadata const& metadata);
204 
220  virtual ActivationQueryBase::UPtr perform_action(Result const& result,
221  ActionMetadata const& metadata,
222  std::string const& widget_id,
223  std::string const& action_id);
224 
236  virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
237 
241  static void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
242 
252  virtual std::string scope_directory() const final;
253 
266  virtual std::string cache_directory() const final;
267 
283  virtual std::string app_directory() const final;
284 
298  virtual std::string tmp_directory() const final;
299 
309  virtual unity::scopes::RegistryProxy registry() const final;
310 
327  virtual VariantMap settings() const final;
328 
345  virtual ChildScopeList find_child_scopes() const;
346 
355  virtual ChildScopeList child_scopes() const final;
356 
371  virtual ActivationQueryBase::UPtr activate_result_action(Result const& result,
372  ActionMetadata const& metadata,
373  std::string const& action_id);
374 
375 protected:
377  ScopeBase();
378 private:
379  std::unique_ptr<internal::ScopeBaseImpl> p;
380 
381  friend class internal::RuntimeImpl;
382  friend class internal::ScopeObject;
383  friend class testing::TypedScopeFixtureHelper;
385 };
386 
387 } // namespace scopes
388 
389 } // namespace unity
390 
406 
416 
417 namespace unity
418 {
419 
420 namespace scopes
421 {
422 
427 
432 
433 } // namespace scopes
434 
435 } // 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 runtime when a scope needs to instantiate a query.
Base class for a scope implementation.
Definition: ScopeBase.h:133
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 runtime 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 runtime 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:426
#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 runtime 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:431
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 runtime 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