org.gnome.OnlineAccounts

org.gnome.OnlineAccounts — OnlineAccounts interface

Methods

SetSaveOnlineFlag           (in  'b'         save_online_flag)
GetSaveOnlineFlag           (out 'b'         save_online_flag)
GetHaveOnlineUserFlag       (out 'b'         have_online_user_flag)
GetConnectedToServerFlag    (out 'b'         connected_to_server_flag)
SaveAccountChanges          (in  'o'         account_object_path,
                             in  'a{ss}'     new_properties)
GetOrCreateAccount          (in  's'         account_type,
                             in  's'         username,
                             in  's'         return_cb,
                             in  's'         error_cb,
                             out '(obs)'     result_account_tuple)
RemoveAccount               (in  'o'         account_object_path,
                             in  's'         return_cb,
                             in  's'         error_cb)
GetEnabledAccounts          (out 'ao'        enabled_accounts)
GetEnabledAccountsWithTypes (in  'as'        account_types,
                             out 'ao'        enabled_accounts)
GetAllAccounts              (out 'ao'        accounts)
GetAllAccountsWithTypes     (in  'as'        account_types,
                             out 'ao'        accounts)
GetAllAccountTypes          (out 'a{s(sss)}' account_types)
EnsureAccountType           (in  's'         type_name,
                             in  's'         type_full_name,
                             in  's'         type_user_info_type,
                             in  's'         type_link)
OpenAccountsDialog          (in  'u'         event_time)
OpenAccountsDialogWithTypes (in  'as'        account_types,
                             in  'u'         event_time)

Signals

AccountAdded                 ('o' account_object_path)
AccountRemoved               ('o' account_object_path)
AccountEnabled               ('o' account_object_path)
AccountDisabled              ('o' account_object_path)
SaveOnlineFlagChanged        ('b' new_save_online_flag)
HaveOnlineUserFlagChanged    ('b' new_have_online_user_flag)
ConnectedToServerFlagChanged ('b' new_connected_to_server_flag)
AccountUpdateFeedback        ('s' feedback_header,
                              's' feedback_message,
                              'b' is_error_flag)

Implemented Interfaces

Objects implementing org.gnome.OnlineAccounts also implements org.freedesktop.DBus.Introspectable, org.freedesktop.DBus.Properties

Description

Online Accounts service can be used by desktop applications to create and retrieve information about user's online accounts, such as Google or Twitter. Online Accounts service stores account information in GConf and passwords in GNOME Keyring and takes care of all GConf and GNOME Keyring manipulations. In addition, it provides applications with a stock dialog that allows adding and modifying accounts of certain types used by the application. The central management of accounts allows the user to only enter account information once and have it be available to all applications that work with a given account type.

The presence of an account type in the list of online accounts on the GNOME Online site should be ensured by the application developers. This enables users who use GNOME Online to have their accounts of these types available to them on any machine they use. Users can opt-in to use the GNOME Online service by selecting "Save Accounts Online" option in the stock dialog and logging in to the GNOME Online site. This page has an explanation about the service for the users.

If the account type needed by a certain application doesn't already exist on the GNOME Online site, the application developers can experiment with the Online Accounts service by adding the account type locally with EnsureAccountType() , and only adding the account type online and making it public once their feature is publicly available. Beyond the initial experimentation, EnsureAccountType() should always be used by applications to ensure that Online Accounts service has information about the type even if the server is not available.

Typically, applications should use GetEnabledAccountsWithTypes() to get all enabled accounts for a certain set of types, as well as connect to AccountEnabled() and AccountDisabled() signals. Using enabled accounts and allowing the user to edit accounts in the stock dialog by calling OpenAccountsDialogWithTypes() allows applications to completely delegate online accounts management to the Online Accounts service. Examples of such use of the Online Accounts service can be found in the code for the Online Desktop sidebar and in the code for Twitux.

Most other functions are only useful if the application needs to have its own user interface for adding and modifying accounts. If the application is using GetAllAccounts(), it should check if the accounts it gets are disabled. It should add accounts to the service with GetOrCreateAccount(), save account changes with SaveAccountChanges(), and remove accounts with RemoveAccount(). It should make it clear to the user that these changes will be saved centrally, and also provide the user with an option to save accounts on GNOME Online and use SetSaveOnlineFlag() to toggle that option. Implementation of the stock accounts dialog might be useful for understanding how to implement a custom user interface that uses the Online Accounts service to store away the accounts information centrally.

Details

SetSaveOnlineFlag ()

SetSaveOnlineFlag (in  'b' save_online_flag)

Sets a boolean flag specifying if the user wants the accounts information to be saved on the GNOME Online service. This preference should be provided by the user.

save_online_flag:

A boolean flag specifying if the user wants the accounts information to be saved on the GNOME Online service.

GetSaveOnlineFlag ()

GetSaveOnlineFlag (out 'b' save_online_flag)

Returns a boolean flag specifying if the user wants the accounts information to be saved on the GNOME Online service.

save_online_flag:

Returns a boolean flag specifying if the user wants the accounts information to be saved on the GNOME Online service.

GetHaveOnlineUserFlag ()

GetHaveOnlineUserFlag (out 'b' have_online_user_flag)

Indicates if the GNOME Online identity of the desktop user is known. This flag is only useful if the application is not using the stock accounts dialog and needs to provide the user with an ability to log in to GNOME Online.

have_online_user_flag:

Returns TRUE if the GNOME Online identity of the desktop user is known.

GetConnectedToServerFlag ()

GetConnectedToServerFlag (out 'b' connected_to_server_flag)

Indicates if the Online Accounts service is connected to the GNOME Online server.

connected_to_server_flag:

Returns TRUE if the Online Accounts service is connected to the GNOME Online server.

SaveAccountChanges ()

SaveAccountChanges (in  'o'     account_object_path,
                    in  'a{ss}' new_properties)

Sets new values for the specified properties of the account.

account_object_path:

An object path to the account for which new properties are being set.

new_properties:

A dictionary of key and value pairs for account properties. Valid values for keys are "password" and "enabled". This method needs to be used by an application only if it provides its own user interface for entering account passwords or changing account enabled status.

GetOrCreateAccount ()

GetOrCreateAccount (in  's'     account_type,
                    in  's'     username,
                    in  's'     return_cb,
                    in  's'     error_cb,
                    out '(obs)' result_account_tuple)

An asynchronous function that gets or creates an account of a given type with a given username. The result is returned by calling a return or an error callback function. The function is asynchronous because it can require communication with the GNOME Online server if a new account is added and the GNOME Online user identity is known.

Applications should not need to use this function if they use the stock account dialog. However, they might want to use this function to add the accounts already saved by the user through the application's own user interface. In this case, the application should ask the user's permission to do so first.

account_type:

A short name for the account type.

username:

A username for the account.

return_cb:

A function called with the return value in case of success.

error_cb:

A function called with an error message in case of failure.

result_account_tuple:

Returns a tuple with an account object path as the first element, a boolean indicating if a new account was created as a second element, and a feedback message as a third element

RemoveAccount ()

RemoveAccount (in  'o' account_object_path,
               in  's' return_cb,
               in  's' error_cb)

An asynchronous function that removes the specified account. The function is asynchronous because it requires communication with the GNOME Online server to remove the account if the GNOME Online user identity is known. Applications should not need to use this function if they use the stock account dialog.

account_object_path:

An object path for the account to be removed.

return_cb:

A function called in case of success.

error_cb:

A function called with an error message in case of failure.

GetEnabledAccounts ()

GetEnabledAccounts (out 'ao' enabled_accounts)

Returns a list of object paths to the enabled account objects of all types. This function should be used by applications to avoid getting disabled accounts.

enabled_accounts:

Returns a list of object paths to the enabled account objects of all types.

GetEnabledAccountsWithTypes ()

GetEnabledAccountsWithTypes (in  'as' account_types,
                             out 'ao' enabled_accounts)

Returns a list of object paths to the enabled account objects that have specified types. This function should be used by applications to avoid getting disabled accounts.

account_types:

A list of account types for which enabled accounts should be returned.

enabled_accounts:

Returns a list of object paths to the enabled account objects that have specified types.

GetAllAccounts ()

GetAllAccounts (out 'ao' accounts)

Returns a list of object paths to the account objects of all types. GetEnabledAccounts() should normally be used instead to avoid getting disabled accounts.

accounts:

Returns a list of object paths to the account objects of all types.

GetAllAccountsWithTypes ()

GetAllAccountsWithTypes (in  'as' account_types,
                         out 'ao' accounts)

Returns a list of object paths to the account objects that have specified types. GetEnabledAccountsWithTypes() should normally be used instead to avoid getting disabled accounts.

account_types:

A list of account types for which accounts should be returned.

accounts:

Returns a list of object paths to the account objects that have specified types.

GetAllAccountTypes ()

GetAllAccountTypes (out 'a{s(sss)}' account_types)

Returns a list of account types known to the Online Accounts service.

account_types:

Returns a dictionary with short account names as keys and tuples of account full name, account user info type, and account type site link as values.

EnsureAccountType ()

EnsureAccountType (in  's' type_name,
                   in  's' type_full_name,
                   in  's' type_user_info_type,
                   in  's' type_link)

This method should be used to ensure that the account type is known to the Online Accounts service in case the GNOME Online server that provides a listing of accounts is not available or the account type is not yet available from the server because support for it is under development and it should not be available publicly. This method should always be called on application start-up for each account type the application works with.

type_name:

A short name for the account type, which can only contain lower case letters or underscores, e.g. "twitter". This name should match the short name that is listed or will be listed on GNOME Online for the account.

type_full_name:

A full name for the account type, e.g. "Twitter".

type_user_info_type:

A type of information that the user needs to enter to identify this account, e.g. "Twitter username".

type_link:

A link to a web site that can provide the user with this information, e.g. "twitter.com".

OpenAccountsDialog ()

OpenAccountsDialog (in  'u' event_time)

Opens stock accounts dialog for all account types.

event_time:

Gtk current event time provided by gtk_get_current_event_time().

OpenAccountsDialogWithTypes ()

OpenAccountsDialogWithTypes (in  'as' account_types,
                             in  'u'  event_time)

Opens stock accounts dialog for the given account types.

account_types:

A list of account types that should be included in the dialog.

event_time:

Gtk current event time provided by gtk_get_current_event_time().

Signal Details

The AccountAdded signal

AccountAdded ('o' account_object_path)

A signal emitted when an account gets added. Be sure to check if the type of the added account is used by the application when handling this signal. Normally, applications should connect to the AccountEnabled() signal instead to avoid being notified about additions of disabled accounts.

account_object_path:

An object path to the added account.

The AccountRemoved signal

AccountRemoved ('o' account_object_path)

A signal emitted when an account gets removed. Normally, applications should connect to the AccountDisabled() signal instead to be sure to be notified when accounts get disabled.

account_object_path:

An object path to the removed account.

The AccountEnabled signal

AccountEnabled ('o' account_object_path)

A signal emitted when an account gets enabled. Be sure to check if the type of the enabled account is used by the application when handling this signal. This is the signal applications should connect to if they are only handling enabled accounts. Such applications don't need to connect to the AccountAdded() signal as AccountEnabled() is emitted when an enabled account is added as well.

account_object_path:

An object path to the enabled account.

The AccountDisabled signal

AccountDisabled ('o' account_object_path)

A signal emitted when an account gets disabled. This is the signal applications should connect to if they are only handling enabled accounts. Such applications don't need to connect to the AccountRemoved() signal as AccountDisabled() is emitted when an account is removed as well.

account_object_path:

An object path to the disabled account.

The SaveOnlineFlagChanged signal

SaveOnlineFlagChanged ('b' new_save_online_flag)

A signal emitted when the value for a boolean flag specifying if the user wants the accounts information to be saved on the GNOME Online service is changed.

new_save_online_flag:

A new boolean value specifying if the user wants the accounts information to be saved on the GNOME Online service.

The HaveOnlineUserFlagChanged signal

HaveOnlineUserFlagChanged ('b' new_have_online_user_flag)

A signal emitted when the value for a boolean flag specifying if the GNOME Online identity of the desktop user is known is changed. This signal is only useful if the application is not using the stock accounts dialog and needs to provide the user with an ability to log in to GNOME Online.

new_have_online_user_flag:

A new boolean value specifying if the GNOME Online identity of the desktop user is known.

The ConnectedToServerFlagChanged signal

ConnectedToServerFlagChanged ('b' new_connected_to_server_flag)

A signal emitted when the value for a boolean flag specifying if the Online Accounts service is connected to the GNOME Online server is changed.

new_connected_to_server_flag:

A new boolean value specifying if the Online Accounts service is connected to the GNOME Online server.

The AccountUpdateFeedback signal

AccountUpdateFeedback ('s' feedback_header,
                       's' feedback_message,
                       'b' is_error_flag)

A signal emitted when some feedback about an online account becomes available from the server. For example, this could happen if the user enabled storing accounts online, and some accounts that were previously stored locally failed server validation. If an application is not using a stock dialog, it needs to be able to display such feedback to the user.

feedback_header:

A header for the feedback message.

feedback_message:

A text for the feedback message.

is_error_flag:

A boolean value indicating if the feedback message is an error. TRUE if it is an error, and FALSE if it is just a notice.