Unity Scopes API
|
Base class for a scope implementation. More...
#include <unity/scopes/ScopeBase.h>
Public Member Functions | |
virtual void | start (std::string const &scope_id) |
Called by the scopes run time after the create function completes. More... | |
virtual void | stop () |
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... | |
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 | 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... | |
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. | |
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:
The derived class gets passed an instance of RegistryProxy in the virtual method start(), so aggregating scopes need to override the default implementation. In addition, the library must provide two functions with "C" linkage:
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:
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 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 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.
|
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.
result | The result that should be activated. |
metadata | additional data sent by the client. |
|
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.
LogicException | if called from the constructor of this instance. |
|
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.
result | The result that was previewed. |
metadata | Additional data sent by client. |
widget_id | The identifier of the 'actions' widget of the activated action. |
action_id | The identifier of the action that was activated. |
|
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.
result | The result that should be previewed. |
metadata | Additional data sent by the client. |
|
finalvirtual |
Returns the proxy to the registry.
LogicException | if called from the constructor of this instance. |
|
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.
|
finalvirtual |
Returns the directory that stores the scope's configuration files and shared library.
LogicException | if called from the constructor of this instance. |
|
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.
query | The query string to be executed by the returned object instance. |
metadata | additional data sent by the client. |
|
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.
LogicException | if called from the constructor of this instance. |
|
virtual |
|
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().
|
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.
LogicException | if called from the constructor of this instance. |