ScopeBase

Base class for a scope implementation. More...

#include <unity/scopes/ScopeBase.h>

Inheritance diagram for unity::scopes::ScopeBase:
Inheritance graph
[legend]

Public Member Functions

virtual void start (std::string const &scope_id)
 Called by the scopes runtime after the create function completes. More...
 
virtual void stop ()
 Called by the scopes runtime when the scope should shut down. More...
 
virtual void run ()
 Called by the scopes runtime after it has called start() to hand a thread of control to the scope. More...
 
virtual SearchQueryBase::UPtr search (CannedQuery const &query, SearchMetadata const &metadata)=0
 Called by the scopes runtime when a scope needs to instantiate a query. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual std::string scope_directory () const final
 Returns the directory that stores the scope's configuration files and shared library. More...
 
virtual std::string cache_directory () const final
 Returns a directory that is (exclusively) writable for the scope. More...
 
virtual std::string app_directory () const final
 Returns a directory that is shared with an app in the same click package. More...
 
virtual std::string tmp_directory () const final
 Returns a tmp directory that is (exclusively) writable for the scope. More...
 
virtual unity::scopes::RegistryProxy registry () const final
 Returns the proxy to the registry. More...
 
virtual VariantMap settings () const final
 Returns a dictionary with the scope's current settings. More...
 
virtual ChildScopeList find_child_scopes () const
 Returns a defaulted list of child scopes aggregated by this scope. More...
 
virtual ChildScopeList child_scopes () const final
 Returns the current list of child scopes aggregated by this scope. More...
 
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. More...
 

Static Public Member Functions

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.
 

Detailed Description

Base class for a scope implementation.

Scopes are accessed by the scopes runtime as a shared library (one library per scope). Each scope must implement a class that derives from ScopeBase, for example:

#include <unity/scopes/ScopeBase.h>
class MyScope : public unity::scopes::ScopeBase
{
public:
MyScope();
virtual ~MyScope();
virtual void start(std::string const& scope_id); // Optional
virtual void stop(); // Optional
virtual void run(); // Optional
// ...
};

In addition, the library must provide two functions with "C" linkage:

  • a create function that must return a pointer to the derived instance
  • a destroy function that is passed the pointer returned by the create function

Typically, the create and destroy functions will simply call new and delete, respectively. If the create function throws an exception, the destroy function will not be called. If the create function returns NULL, the destroy function will be called with NULL as its argument.

Rather than hard-coding the names of the functions, use the UNITY_SCOPE_CREATE_FUNCTION and UNITY_SCOPE_DESTROY_FUNCTION macros, for example:

UNITY_SCOPE_CREATE_FUNCTION()
{
return new MyScope;
}
void
UNITY_SCOPE_DESTROY_FUNCTION(unity::scopes::ScopeBase* scope)
{
delete scope;
}

After the scopes runtime has obtained a pointer to the class instance from the create function, it calls start(), which allows the scope to intialize itself. This is followed by a call to run(). The call to run() is made by a separate thread; its only purpose is to pass a thread of control to the scope, for example, to run an event loop. When the scope should complete its activities, the runtime calls stop(). The calls to the create function, start(), stop(), and the destroy function) are made by the same thread.

The scope implementation, if it does not return from run(), is expected to return from run() in response to a call to stop() in a timely manner.

Member Function Documentation

ActivationQueryBase::UPtr unity::scopes::ScopeBase::activate ( Result const &  result,
ActionMetadata const &  metadata 
)
virtual

Called by the scopes runtime when a scope needs to respond to a result activation request.

This method must return an instance that is derived from ActivationQueryBase. The implementation of this method must return in a timely manner, that is, it should perform only minimal initialization that is guaranteed to complete quickly. The call to activate() is made by an arbitrary thread. The default implementation returns an instance of ActivationQueryBase that responds with ActivationResponse::Status::NotHandled.

Parameters
resultThe result that should be activated.
metadataadditional data sent by the client.
Returns
The activation instance.
ActivationQueryBase::UPtr unity::scopes::ScopeBase::activate_result_action ( Result const &  result,
ActionMetadata const &  metadata,
std::string const &  action_id 
)
virtual

Invoked when a scope is requested to handle a result in-card action.

This method must return an instance that is derived from ActivationQueryBase. The implementation of this method must return in a timely manner, that is, it should perform only minimal initialization that is guaranteed to complete quickly. The call to activate_result_action() is made by an arbitrary thread. The default implementation returns an instance of ActivationQueryBase that responds with ActivationResponse::Status::NotHandled.

Parameters
resultThe result whose action was activated.
metadataAdditional data sent by the client.
action_idThe identifier of the action that was activated.
Returns
The activation instance.
std::string unity::scopes::ScopeBase::app_directory ( ) const
finalvirtual

Returns a directory that is shared with an app in the same click package.

If a scope and an app share a single click package, this directory and the files in it are writable by the app, and read-only to the scope. This allows the app to write information into the filesystem that can be read by the scope (but not vice versa).

Note
The app directory is available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
The root directory of a filesystem sub-tree that the scope shares with an application installed from the same click-package.
Exceptions
LogicExceptionif called from the constructor of this instance.
std::string unity::scopes::ScopeBase::cache_directory ( ) const
finalvirtual

Returns a directory that is (exclusively) writable for the scope.

This directory allows scopes to store persistent information, such as cached content or similar.

Note
The cache directory is available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
The root directory of a filesystem sub-tree that is writable for the scope.
Exceptions
LogicExceptionif called from the constructor of this instance.
ChildScopeList unity::scopes::ScopeBase::child_scopes ( ) const
finalvirtual

Returns the current list of child scopes aggregated by this scope.

An aggregator should respect the "enabled" states of each child scope, returning results only for the child scopes that are enabled.

Returns
The list of child scopes aggregated by this scope.
ChildScopeList unity::scopes::ScopeBase::find_child_scopes ( ) const
virtual

Returns a defaulted list of child scopes aggregated by this scope.

The scope author must ensure that the list returned by this method contains all scopes that this aggregator may collect results from. The "enabled" state for each child returned should be set to a default value (i.e. whether the child is enabled or disabled by default when newly discovered).

The default behaviour of this method is to simply return all available scopes on the system in enabled state. This translates to: "Any scope may potentially be aggregated by this scope".

Note
Only aggregator scopes should implement this method.
Returns
The list of child scopes aggregated by this scope.
ActivationQueryBase::UPtr unity::scopes::ScopeBase::perform_action ( Result const &  result,
ActionMetadata const &  metadata,
std::string const &  widget_id,
std::string const &  action_id 
)
virtual

Invoked when a scope is requested to handle a preview action.

This method must return an instance that is derived from ActivationQueryBase. The implementation of this method must return in a timely manner, that is, it should perform only minimal initialization that is guaranteed to complete quickly. The call to activate() is made by an arbitrary thread. The default implementation returns an instance of ActivationQueryBase that responds with ActivationResponse::Status::NotHandled.

Parameters
resultThe result that was previewed.
metadataAdditional data sent by client.
widget_idThe identifier of the 'actions' widget of the activated action.
action_idThe identifier of the action that was activated.
Returns
The activation instance.
virtual PreviewQueryBase::UPtr unity::scopes::ScopeBase::preview ( Result const &  result,
ActionMetadata const &  metadata 
)
pure virtual

Invoked when a scope is requested to create a preview for a particular result.

This method must return an instance that is derived from PreviewQueryBase. The implementation of this method must return in a timely manner, that is, it should perform only minimal initialization that is guaranteed to complete quickly. The call to activate() is made by an arbitrary thread.

Parameters
resultThe result that should be previewed.
metadataAdditional data sent by the client.
Returns
The preview instance.

Implemented in unity::scopes::qt::QScopeBaseAPI.

RegistryProxy unity::scopes::ScopeBase::registry ( ) const
finalvirtual

Returns the proxy to the registry.

Note
The registry proxy is available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
The proxy to the registry.
Exceptions
LogicExceptionif called from the constructor of this instance.
void unity::scopes::ScopeBase::run ( )
virtual

Called by the scopes runtime after it has called start() to hand a thread of control to the scope.

run() passes a thread of control to the scope to do with as it sees fit, for example, to run an event loop. During finalization, the scopes runtime joins with the thread that called run(). This means that, if the scope implementation does not return from run(), it is expected to arrange for run() to complete in a timely manner in response to a call to stop(). Failure to do so will cause deadlock during finalization.

If run() throws an exception, the runtime handles the exception and calls stop() in response.

std::string unity::scopes::ScopeBase::scope_directory ( ) const
finalvirtual

Returns the directory that stores the scope's configuration files and shared library.

Note
The scope directory is available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
The scope's configuration directory.
Exceptions
LogicExceptionif called from the constructor of this instance.
virtual SearchQueryBase::UPtr unity::scopes::ScopeBase::search ( CannedQuery const &  query,
SearchMetadata const &  metadata 
)
pure virtual

Called by the scopes runtime when a scope needs to instantiate a query.

This method must return an instance that is derived from QueryBase. The implementation of this method must return in a timely manner, that is, it should perform only minimal initialization that is guaranteed to complete quickly. The call to search() is made by an arbitrary thread.

Parameters
queryThe query string to be executed by the returned object instance.
metadataadditional data sent by the client.
Returns
The query instance.

Implemented in unity::scopes::qt::QScopeBaseAPI.

unity::scopes::VariantMap unity::scopes::ScopeBase::settings ( ) const
finalvirtual

Returns a dictionary with the scope's current settings.

Instead of storing the return value, it is preferable to call settings() each time your implementation requires a settings value. This ensures that, if a user changes settings while the scope is running, the new settings take effect with the next query.

Note
The settings are available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
The scope's current settings.
Exceptions
LogicExceptionif called from the constructor of this instance.
ResourceExceptionif settings database file is corrupted.
FileExceptionif settings database file is not readable.
void unity::scopes::ScopeBase::start ( std::string const &  scope_id)
virtual

Called by the scopes runtime after the create function completes.

If start() throws an exception, stop() will not be called.

The call to start() is made by the same thread that calls the create function.

Parameters
scope_idThe name of the scope as defined by the scope's configuration file.

Reimplemented in unity::scopes::qt::QScopeBaseAPI.

void unity::scopes::ScopeBase::stop ( )
virtual

Called by the scopes runtime when the scope should shut down.

A scope should deallocate as many resources as possible when stop() is called, for example, deallocate any caches and close network connections. In addition, if the scope implements run() and did not return from run(), it must return from run() in response to the call to stop().

Exceptions from stop() are ignored.

The call to stop() is made by the same thread that calls the create function and start().

Reimplemented in unity::scopes::qt::QScopeBaseAPI.

std::string unity::scopes::ScopeBase::tmp_directory ( ) const
finalvirtual

Returns a tmp directory that is (exclusively) writable for the scope.

This directory is periodically cleaned of unused files. The exact amount of time may vary, but is on the order of a few hours. The directory is also cleaned during reboot.

Note
The tmp directory is available only after this ScopeBase is instantiated; do not call this method from the constructor!
Returns
A directory for temporary files.
Exceptions
LogicExceptionif called from the constructor of this instance.