Represents an instance of a service in an Online Accounts More...

Import Statement: import Ubuntu.OnlineAccounts 0.1




Detailed Description

The AccountService element represents a service within an existing online account. It can be used to obtain an authentication token to use the service it refers to.

Currently, an AccountService is valid only if its objectHandle property is set to a value obtained from an AccountServiceModel or an Account.

See AccountServiceModel's documentation for usage examples.

Property Documentation

accountId : string

The account's numeric ID; note that all AccountService objects which work on the same online account will have the same ID.

authData : jsobject

An object providing information about the authentication. The returned object will have at least these members:

  • method is the authentication method
  • mechanism is the authentication mechanism (a sub-specification of the method)
  • parameters is a dictionary of authentication parameters
  • credentialsId is the numeric identified of the credentials in the secrets storage. See the Credentials element for more info.

autoSync : bool

This property tells whether the AccountService should invoke the Account::sync() method whenever updateSettings(), updateDisplayName() or updateServiceEnabled() are called. By default, this property is true.

credentials : Credentials

The credentials used by this account service. This property is meant to be used only when creating or editing the account, and serves to bind a credentials record to the account: when the value of the Credentials::credentialsId changes, an update of authData.credentialsId will be queued (and immediately executed if autoSync is true). By default, reading this property returns a null object.

displayName : string

The account's display name (usually the user's login or ID); note that all AccountService objects which work on the same online account will share the same display name.

enabled : bool

This read-only property tells whether the AccountService is enabled. An application shouldn't use an AccountService which is disabled.

objectHandle : object

An opaque handle to the underlying C++ object. Until the property is set, the AccountService element is uninitialized. Similarly, if the C++ object is destroyed (for instance, because the AccountServiceModel which owns it is destroyed or if the account is deleted), expect the AccountService to become invalid.

provider : jsobject

An immutable object representing the provider which provides the account. The returned object will have at least these members:

  • id is the unique identifier for this provider
  • displayName
  • iconName
  • isSingleAccount, true if this provider supports creating one account at most
  • translations, the localization domain for translating the provider's display name

service : jsobject

An immutable object representing the service which this AccountService instantiates. The returned object will have at least these members:

  • id is the unique identified for this service
  • displayName
  • iconName
  • serviceTypeId identifies the provided service type
  • translations, the localization domain for translating the provider's display name

serviceEnabled : bool

This read-only property tells whether the service is enabled within the account. This property differs from the enabled property in that the enabled property also considers whether the account is enabled, while this one only reflects the status of the service. Applications shouldn't rely on the value on this property to decide whether to use the account or not.

See also enabled.

settings : jsobject

A dictionary of all the account service's settings. This does not include the authentication settings, which are available from the AccountService::authData property.

Signal Documentation

authenticated(jsobject reply)

Emitted when the authentication has been successfully completed. The reply object will contain the authentication data, which depends on the authentication method used.

authenticationError(jsobject error)

Emitted when the authentication fails. The error object will contain the following fields:

  • code is a numeric error code (see Signon::Error for the meaning)
  • message is a textual description of the error, not meant for the end-user

Method Documentation

void authenticate(jsobject sessionData)

Perform the authentication on this account. The sessionData dictionary is optional and if not given the value of authData::parameters will be used.

Each call to this method will cause either of authenticated or authenticationError signals to be emitted at some time later. Note that the authentication might involve interactions with the network or with the end-user, so don't expect these signals to be emitted immediately.

See also authenticated and authenticationError.

void cancelAuthentication()

Cancel an ongoing authentication on this account. This method does nothing if there isn't any authentication process going on.

See also authenticate.

void updateServiceEnabled(bool enabled)

Enables or disables the service within the account configuration. Since the enabled property is the combination of the global account's enabledness status and the specific service's status, its value might not change after this method is called.

See also enabled, serviceEnabled, and autoSync.

void updateSettings(jsobject settings)

Change some settings. Only the settings which are present in the settings dictionary will be changed; all others settings will not be affected. To remove a settings, set its value to null.

See also autoSync.