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 (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.

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.

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.

GetConnectedToServerFlag (out 'b' connected_to_server_flag)

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

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

Sets new values for the specified properties of the account.

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.

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.

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.

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.

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.

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.

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

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

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.

OpenAccountsDialog (in  'u' event_time)

Opens stock accounts dialog for all account types.

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

Opens stock accounts dialog for the given account types.

Signal Details

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.

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.

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.

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.

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.

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.

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.

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.