unity.scopes.OnlineAccountClient

A simple interface for integrating online accounts access and monitoring into scopes. More...

#include <unity/scopes/OnlineAccountClient.h>

Classes

struct  ServiceStatus
 A container for details about a service's status and authorization parameters. More...
 

Public Types

enum  MainLoopSelect { RunInExternalMainLoop, CreateInternalMainLoop }
 Indicates whether an external main loop already exists, or one should be created internally. More...
 
enum  PostLoginAction {
  Unknown, DoNothing, InvalidateResults, ContinueActivation,
  LastActionCode_ = ContinueActivation
}
 Indicates what action to take when the login process completes. More...
 
typedef std::function< void(ServiceStatus const &)> ServiceUpdateCallback
 Function signature for the service update callback. More...
 

Public Member Functions

 OnlineAccountClient (std::string const &service_name, std::string const &service_type, std::string const &provider_name, MainLoopSelect main_loop_select=CreateInternalMainLoop)
 Create OnlineAccountClient for the specified account service. More...
 
 OnlineAccountClient (std::string const &service_name, std::string const &service_type, std::string const &provider_name, VariantMap const &auth_params, MainLoopSelect main_loop_select=CreateInternalMainLoop)
 Create OnlineAccountClient for the specified account service. More...
 
void set_service_update_callback (ServiceUpdateCallback callback)
 Set the callback function to be invoked when a service status changes. More...
 
void refresh_service_statuses ()
 Refresh all service statuses. More...
 
std::vector< ServiceStatusget_service_statuses ()
 Get statuses for all services matching the name, type and provider specified on construction. More...
 
void register_account_login_item (Result &result, CannedQuery const &query, PostLoginAction login_passed_action, PostLoginAction login_failed_action)
 Register a result item that requires the user to be logged in. More...
 
void register_account_login_item (PreviewWidget &widget, PostLoginAction login_passed_action, PostLoginAction login_failed_action)
 Register a widget item that requires the user to be logged in. More...
 

Detailed Description

A simple interface for integrating online accounts access and monitoring into scopes.

Each instantiation of this class targets a particular account service as specified on construction.

Member Typedef Documentation

typedef std::function<void(ServiceStatus const&)> unity::scopes::OnlineAccountClient::ServiceUpdateCallback

Function signature for the service update callback.

See also
set_service_update_callback

Member Enumeration Documentation

enum unity::scopes::OnlineAccountClient::MainLoopSelect

Indicates whether an external main loop already exists, or one should be created internally.

A running main loop is essential in order to receive service updates from the online accounts backend. When in doubt, set to CreateInternalMainLoop.

Enumerator
RunInExternalMainLoop 

An external main loop already exists and is running.

CreateInternalMainLoop 

An external main loop does not exist.

enum unity::scopes::OnlineAccountClient::PostLoginAction

Indicates what action to take when the login process completes.

Enumerator
Unknown 

An action unknown to the run-time was used.

DoNothing 

Simply return to the scope with no further action.

InvalidateResults 

Invalidate the scope results.

ContinueActivation 

Continue with regular result / widget activation.

LastActionCode_ 

Dummy end marker.

Constructor & Destructor Documentation

unity::scopes::OnlineAccountClient::OnlineAccountClient ( std::string const &  service_name,
std::string const &  service_type,
std::string const &  provider_name,
MainLoopSelect  main_loop_select = CreateInternalMainLoop 
)

Create OnlineAccountClient for the specified account service.

Parameters
service_nameThe name of the service (E.g. "com.ubuntu.scopes.youtube_youtube").
service_typeThe type of service (E.g. "sharing").
provider_nameThe name of the service provider (E.g. "google").
main_loop_selectIndicates whether or not an external main loop exists (see OnlineAccountClient::MainLoopSelect).
unity::scopes::OnlineAccountClient::OnlineAccountClient ( std::string const &  service_name,
std::string const &  service_type,
std::string const &  provider_name,
VariantMap const &  auth_params,
MainLoopSelect  main_loop_select = CreateInternalMainLoop 
)

Create OnlineAccountClient for the specified account service.

Parameters
service_nameThe name of the service (E.g. "com.ubuntu.scopes.youtube_youtube").
service_typeThe type of service (E.g. "sharing").
provider_nameThe name of the service provider (E.g. "google").
auth_paramsAuthentication parameters; this can be used to pass the OAuth client keys, for example.
main_loop_selectIndicates whether or not an external main loop exists (see OnlineAccountClient::MainLoopSelect).

Member Function Documentation

std::vector< OnlineAccountClient::ServiceStatus > unity::scopes::OnlineAccountClient::get_service_statuses ( )

Get statuses for all services matching the name, type and provider specified on construction.

Returns
A list of service statuses.
void unity::scopes::OnlineAccountClient::refresh_service_statuses ( )

Refresh all service statuses.

WARNING: If a service update callback is set, this method will invoke that callback for each service monitored. Therefore, DO NOT call this method from within your callback function!

void unity::scopes::OnlineAccountClient::register_account_login_item ( Result result,
CannedQuery const &  query,
PostLoginAction  login_passed_action,
PostLoginAction  login_failed_action 
)

Register a result item that requires the user to be logged in.

Parameters
resultThe result item that needs account access.
queryThe scope's current query.
login_passed_actionThe action to take upon successful login.
login_failed_actionThe action to take upon unsuccessful login.
void unity::scopes::OnlineAccountClient::register_account_login_item ( PreviewWidget widget,
PostLoginAction  login_passed_action,
PostLoginAction  login_failed_action 
)

Register a widget item that requires the user to be logged in.

Parameters
widgetThe widget item that needs account access.
login_passed_actionThe action to take upon successful login.
login_failed_actionThe action to take upon unsuccessful login.
void unity::scopes::OnlineAccountClient::set_service_update_callback ( ServiceUpdateCallback  callback)

Set the callback function to be invoked when a service status changes.

Parameters
callbackThe external callback function.