unity.scopes.Result

The attributes of a result returned by a Scope. More...

#include <unity/scopes/Result.h>

Inheritance diagram for unity::scopes::Result: src="https://assets.ubuntu.com/v1/d7f276b3-classunity_1_1scopes_1_1_result__inherit__graph.png" border="0" alt="Inheritance graph"/>

Public Member Functions

virtual ~Result ()
 
void store (Result const &other, bool intercept_activation=false)
 Stores a Result inside this Result instance. More...
 
bool has_stored_result () const
 Check if this Result instance has a stored result. More...
 
Result retrieve () const
 Get a stored result. More...
 
void set_uri (std::string const &uri)
 Set the "uri" attribute of this result.
 
void set_title (std::string const &title)
 Set the "title" attribute of this result. More...
 
void set_art (std::string const &image)
 Set the "art" attribute of this result. More...
 
void set_dnd_uri (std::string const &dnd_uri)
 Set the "dnd_uri" attribute of this result. More...
 
void set_intercept_activation ()
 Indicates to the receiver that this scope should intercept activation requests for this result. More...
 
bool direct_activation () const
 Check if this result should be activated directly by the shell because the scope doesn't handle activation of this result. More...
 
ScopeProxy target_scope_proxy () const
 Get the proxy of a scope that handles activation and preview of this result. More...
 
Variantoperator[] (std::string const &key)
 Returns reference of a Result attribute. More...
 
Variant const & operator[] (std::string const &key) const
 Returns a const reference to a Result attribute. More...
 
std::string uri () const noexcept
 Get the "uri" property of this Result. More...
 
std::string title () const noexcept
 Get the "title" property of this Result. More...
 
std::string art () const noexcept
 Get the "art" property of this Result. More...
 
std::string dnd_uri () const noexcept
 Get the "dnd_uri" property of this Result. More...
 
bool contains (std::string const &key) const
 Check if this Result has an attribute. More...
 
Variant const & value (std::string const &key) const
 Get the value of an attribute. More...
 
VariantMap serialize () const
 Returns a dictionary of all attributes of this Result instance. More...
 
bool is_account_login_result () const
 Check if this result is an online account login result. More...
 
bool operator== (Result const &other) const
 Compare result. More...
 
Copy and assignment

Copy and assignment (move and non-move versions) have the usual value semantics.

 Result (Result const &other)
 
 Result (Result &&)
 
Resultoperator= (Result const &other)
 
Resultoperator= (Result &&)
 

Detailed Description

The attributes of a result returned by a Scope.

The Result API provides convenience methods for some typical attributes (title, art), but scopes are free to add and use any custom attributes with operator[]. The only required attribute is 'uri' and it must not be empty before calling Reply::push().

Constructor & Destructor Documentation

virtual unity::scopes::Result::~Result ( )
virtual

Destructor.

Member Function Documentation

std::string unity::scopes::Result::art ( ) const
noexcept

Get the "art" property of this Result.

This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with operator[]).

Returns
The value of "art" or the empty string.
bool unity::scopes::Result::contains ( std::string const &  key) const

Check if this Result has an attribute.

Parameters
keyThe attribute name.
Returns
True if the attribute is set.
bool unity::scopes::Result::direct_activation ( ) const

Check if this result should be activated directly by the shell because the scope doesn't handle activation of this result.

Returns
True if this result needs to be activated directly.
std::string unity::scopes::Result::dnd_uri ( ) const
noexcept

Get the "dnd_uri" property of this Result.

This method returns an empty string if this attribute is not of type Variant::Type::String type (e.g. it was set with operator[]).

Returns
The value of "dnd_uri" or the empty string.
bool unity::scopes::Result::has_stored_result ( ) const

Check if this Result instance has a stored result.

Returns
True if there is a stored result
bool unity::scopes::Result::is_account_login_result ( ) const

Check if this result is an online account login result.

Returns
True if this result is an online account login result.
bool unity::scopes::Result::operator== ( Result const &  other) const

Compare result.

Returns
True if results have all attributes equal.
Variant& unity::scopes::Result::operator[] ( std::string const &  key)

Returns reference of a Result attribute.

This method can be used to read or initialize both standard ("uri", "title", "art", "dnd_uri") and custom metadata attributes. Referencing a non-existing attribute automatically creates it with a default value of Variant::Type::Null.

Parameters
keyThe name of the attribute.
Returns
A reference to the attribute.
Exceptions
unity::Invalidargumentif no attribute with the given name exists.
Variant const& unity::scopes::Result::operator[] ( std::string const &  key) const

Returns a const reference to a Result attribute.

This method can be used for read-only access to both standard ("uri", "title", "art", "dnd_uri") and custom metadata attributes. Referencing a non-existing attribute throws unity::InvalidArgumentException.

Parameters
keyThe name of the attribute.
Returns
A const reference to the attribute.
Exceptions
unity::Invalidargumentif no attribute with the given name exists.
Result unity::scopes::Result::retrieve ( ) const

Get a stored result.

Returns
stored result
Exceptions
unity::InvalidArgumentExceptionif no result was stored in this Result instance.
VariantMap unity::scopes::Result::serialize ( ) const

Returns a dictionary of all attributes of this Result instance.

Returns
All base attributes and custom attributes set with add_metadata().
void unity::scopes::Result::set_art ( std::string const &  image)

Set the "art" attribute of this result.

Equivalent to calling result["art"] = image;

void unity::scopes::Result::set_dnd_uri ( std::string const &  dnd_uri)

Set the "dnd_uri" attribute of this result.

Equivalent to calling result["dnd_uri"] = dnd_uri;

void unity::scopes::Result::set_intercept_activation ( )

Indicates to the receiver that this scope should intercept activation requests for this result.

By default, a scope receives preview requests for the results it creates, but does not receive activation requests (they are handled directly by the shell). Intercepting activation implies intercepting preview requests as well; this is important for scopes that forward results from other scopes and call set_intercept_activation() on these scopes. A scope that sets intercept activation flag for a result should re-implement ScopeBase::activate() and provide an implementation of ActivationQueryBase that handles the actual activation. If not called, the result will be activated directly by the Unity shell whithout involving the scope, assuming an appropriate URI schema handler is present on the system.

void unity::scopes::Result::set_title ( std::string const &  title)

Set the "title" attribute of this result.

Equivalent to calling result["title"] = title;

void unity::scopes::Result::store ( Result const &  other,
bool  intercept_activation = false 
)

Stores a Result inside this Result instance.

This method is meant to be used by aggregator scopes which want to modify results they receive, but want to keep a copy of the original result so that they can be correctly handled by the original scopes who created them when it comes to activation or previews. Scopes middleware will automatically pass the correct inner stored result to the activation or preview request handler of a scope which created it.

Parameters
otherThe original result to store within this result.
intercept_activationTrue if this scope should receive activation and preview requests.
ScopeProxy unity::scopes::Result::target_scope_proxy ( ) const

Get the proxy of a scope that handles activation and preview of this result.

The proxy is available only when receiving this result from a scope, otherwise this method throws LogicException. Activation requests should be sent to a scope returned by this method only if direct_activation() is false.

Returns
The scope proxy.
std::string unity::scopes::Result::title ( ) const
noexcept

Get the "title" property of this Result.

This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with operator[]).

Returns
The value of "title" or the empty string.
std::string unity::scopes::Result::uri ( ) const
noexcept

Get the "uri" property of this Result.

This method returns an empty string if this attribute is not of type Variant::Type::String (e.g. it was set with operator[]).

Returns
The value of "uri" or the empty string.
Variant const& unity::scopes::Result::value ( std::string const &  key) const

Get the value of an attribute.

Note: if int64_t value has been stored in the Result but it doesn't exceed maxium range of 32 bit integer and if results come from the cache (see SearchReply::push_surfacing_results_from_cache()), then the value may be made available as 32 bit int; therefore the code should always check the type of returned Variant and depending on that use Variant::get_int() or Variant::get_int_64_t() when dealing with 64-bit integers. This is not needed when using 32 bit integers only.

Parameters
keyThe attribute name.
Returns
The attribute value.
Exceptions
unity::InvalidArgumentExceptionif given attribute hasn't been set.