Unity Scopes API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
unity::scopes::ScopeBase Class Referenceabstract

Base class for a scope implementation. More...

#include <unity/scopes/ScopeBase.h>

Public Member Functions

virtual int start (std::string const &scope_id, RegistryProxy const &registry)=0
 Called by the scopes run time after the create function completes. More...
 
virtual void stop ()=0
 Called by the scopes run time when the scope should shut down. More...
 
virtual void run ()
 Called by the scopes run time 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 run time when a scope needs to instantiate a query. More...
 
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. 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...
 
std::string scope_directory () const
 Returns directory where the scope files are. 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.
 

Static Public Attributes

static constexpr int VERSION = UNITY_SCOPES_VERSION_MAJOR
 This value must be returned from the start() method.
 

Detailed Description

Base class for a scope implementation.

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

class MyScope : public unity::scopes::ScopeBase
{
public:
MyScope();
virtual ~MyScope();
virtual int start(); // Mandatory
virtual void stop(); // Mandatory
virtual void run(); // Optional
};

The derived class must provide implementations of the pure virtual methods start() and stop(). 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. (However, there is no requirement that the derived class instance must be heap-allocated.) 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:

{
return new MyScope; // Example only, heap-allocation is not mandatory
}
void
{
delete scope; // Example only, heap-allocation is not mandatory
}

After the scopes run time 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 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 run time 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 run time 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::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.
void unity::scopes::ScopeBase::run ( )
virtual

Called by the scopes run time 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 run time 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 timely manner in response to a call to stop(). Failure to do so will cause deadlock during finalization.

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

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

Returns directory where the scope files are.

Note, scope directory is only known after the scope has been instantantiated, e.g. it's not available in the constructor.

virtual SearchQueryBase::UPtr unity::scopes::ScopeBase::search ( CannedQuery const &  query,
SearchMetadata const &  metadata 
)
pure virtual

Called by the scopes run time 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.
virtual int unity::scopes::ScopeBase::start ( std::string const &  scope_id,
RegistryProxy const &  registry 
)
pure virtual

Called by the scopes run time 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.
registryA proxy to the scope registry. This parameter is provided for aggregating scopes that need to retrieve proxies to their child scopes.
Returns
Any return value other than ScopeBase::VERSION will cause the scopes run time to refuse to load the scope. The return value is used to ensure that the shared library containing the scope is ABI compatible with the scopes run time.
virtual void unity::scopes::ScopeBase::stop ( )
pure virtual

Called by the scopes run time 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().


The documentation for this class was generated from the following files: