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/AbstractScopeBase.h>
23 #include <unity/scopes/ActionMetadata.h>
24 #include <unity/scopes/SearchMetadata.h>
25 #include <unity/scopes/Version.h>
26 
30 #define UNITY_SCOPE_CREATE_FUNCTION UNITY_SCOPES_VERSIONED_CREATE_SYM
31 
35 #define UNITY_SCOPE_DESTROY_FUNCTION unity_scope_destroy
36 
37 // Convenience definitions for looking up the create and destroy functions in the symbol table
38 // of a dynamically loaded scope.
39 // UNITY_SCOPE_CREATE_SYMSTR and UNITY_SCOPE_DESTROY_SYMSTR expand to a string literal containing the name
40 // of the create and destroy function, respectively.
41 
42 #ifndef DOXYGEN_SKIP
43 # define UNITY_SCOPE_STR(sym) #sym
44 # define UNITY_SCOPE_XSTR(sym) UNITY_SCOPE_STR(sym)
45 #endif
46 
50 #define UNITY_SCOPE_CREATE_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_CREATE_FUNCTION)
51 
55 #define UNITY_SCOPE_DESTROY_SYMSTR UNITY_SCOPE_XSTR(UNITY_SCOPE_DESTROY_FUNCTION)
56 
57 namespace unity
58 {
59 
60 namespace scopes
61 {
62 
63 class CannedQuery;
64 
65 namespace internal
66 {
67 
68 class ScopeBaseImpl;
69 class RuntimeImpl;
70 
71 }
72 
73 namespace testing
74 {
75 
76 struct TypedScopeFixtureHelper;
77 
78 }
79 
141 {
142 public:
144  NONCOPYABLE(ScopeBase);
145  virtual ~ScopeBase();
147 
157  virtual void start(std::string const& scope_id);
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,
228  ActionMetadata const& metadata,
229  std::string const& widget_id,
230  std::string const& action_id);
231 
243  virtual PreviewQueryBase::UPtr preview(Result const& result, ActionMetadata const& metadata) = 0;
244 
248  static void runtime_version(int& v_major, int& v_minor, int& v_micro) noexcept;
249 
259  virtual std::string scope_directory() const final;
260 
273  virtual std::string cache_directory() const final;
274 
287  virtual std::string tmp_directory() const final;
288 
298  virtual unity::scopes::RegistryProxy registry() const final;
299 
314  virtual VariantMap settings() const final;
315 
316 protected:
318  ScopeBase();
319 private:
320  std::unique_ptr<internal::ScopeBaseImpl> p;
321 
322  friend class internal::RuntimeImpl;
323  friend class internal::ScopeObject;
324  friend struct testing::TypedScopeFixtureHelper;
326 };
327 
328 } // namespace scopes
329 
330 } // namespace unity
331 
348 
358 
359 namespace unity
360 {
361 
362 namespace scopes
363 {
364 
369 
374 
375 } // namespace scopes
376 
377 } // namespace unity
378 
379 #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.
virtual VariantMap settings() const final
Returns a dictionary with the scope's current settings.
Definition: ScopeBase.cpp:95
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:68
Metadata passed with search requests.
Definition: SearchMetadata.h:43
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:140
Metadata passed to scopes for preview and activation.
Definition: ActionMetadata.h:42
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:48
Definition: ScopeBase.h:73
virtual std::string scope_directory() const final
Returns the directory that stores the scope's configuration files and shared library.
Definition: ScopeBase.cpp:75
virtual std::string cache_directory() const final
Returns a directory that is (exclusively) writable for the scope.
Definition: ScopeBase.cpp:80
virtual std::string tmp_directory() const final
Returns a tmp directory that is (exclusively) writable for the scope.
Definition: ScopeBase.cpp:85
Top-level namespace for all things Unity-related.
Definition: Version.h:50
std::map< std::string, Variant > VariantMap
A dictionary of (string, Variant) pairs.
Definition: Variant.h:39
Definition: ActionMetadata.h:32
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:30
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:368
#define UNITY_SCOPE_DESTROY_FUNCTION
Expands to the identifier of the scope destroy function.
Definition: ScopeBase.h:35
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
decltype(&UNITY_SCOPE_DESTROY_FUNCTION) typedef DestroyFunction
Convenience typedef for the destroy function pointer.
Definition: ScopeBase.h:373
std::shared_ptr< Registry > RegistryProxy
Convenience type definition.
Definition: RegistryProxyFwd.h:34
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:90
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