Sailfish Accounts

API Documentation

Account QML Type

Allows clients to modify or sign into an account with a service provider More...

Import Statement: import .

List of all members, including inherited members

Properties

displayName : string
enabled : bool
error : Account::Error
errorMessage : string
identifier : int
providerName : string
status : Account::Status
supportedServiceNames : QStringList

Methods

void blockingSync()
cancelSignInOperation()
QVariant configurationValue(const QString &serviceName, const QString &key)
QVariantMap configurationValues(const QString &serviceName)
createSignInCredentials(const QString &applicationName, const QString &credentialsName, SignInParameters *parameters, const QString &symmetricKey)
void disableWithService(const QString &serviceName)
void enableWithService(const QString &serviceName)
hasSignInCredentials(const QString &applicationName, const QString &credentialsName)
bool isEnabledWithService(const QString &serviceName)
void remove()
void removeConfigurationValue(const QString &serviceName, const QString &key)
removeSignInCredentials(const QString &applicationName, const QString &credentialsName)
void setConfigurationValue(const QString &serviceName, const QString &key, const QVariant &value)
signIn(const QString &applicationName, const QString &credentialsName, SignInParameters *parameters, const QString &symmetricKey)
signOut(const QString &applicationName, const QString &credentialsName)
void sync()
updateSignInCredentials(const QString &applicationName, const QString &credentialsName, SignInParameters *parameters, const QString &symmetricKey)

Detailed Description

The Account type is a non-visual type which allows the details of an account to be specified, and saved to the system accounts database.

Any modifications to any property of an account will have no effect until the modifications are saved to the database by calling sync().

 import Sailfish.Accounts 1.0

 Item {
     id: root

     Account {
         id: account
         identifier: 12 // retrieved from AccountManager or AccountModel

         // we will be updating the following two properties
         displayName: "inactive example account"
         enabled: false

         onStatusChanged: {
             if (status == Account.Initialized) {
                 sync() // trigger database write
             } else if (status == Account.Error) {
                 // handle error
             } else if (status == Account.Synced) {
                 // successfully written to database
                 // for example purposes, we may want to remove the account.
                 remove() // trigger database write
             } else if (status == Account.Invalid) {
                 // successfully removed from database.
             }
         }
     }
 }

An Account can also be used to sign into a service.

Each application must create signon credentials in the account, and may sign into the account using those credentials. If the service uses OAuth1.0a or OAuth2 for authentication, the client must pass a valid ConsumerKey or ClientId in the parameters to the authentication request.

The following example shows how per-application credentials can be added to an existing account for an OAuth2 service:

 import Sailfish.Accounts 1.0

 Account {
     id: account
     identifier: 12 // example: Facebook account id retrieved from AccountManager or AccountModel

     onStatusChanged: {
         if (status == Account.Initialized) {
             var siParams = signInParameters("facebook-sharing")
             siParams.setParameter("ClientId", "123456789abcdef")
             if (!hasSignInCredentials("MyApp", "MyCredentials")) {
                 createSignInCredentials("MyApp", "SharingCredentials", siParams)
             } else {
                 signIn("MyApp", "SharingCredentials", siParams)
             }
         }
     }

     onSignInCredentialsCreated: {
         for (var i in data) console.log(i+"="+data[i]) // will contain AccessToken
     }

     onSignInResponse: {
         for (var i in data) console.log(i+"="+data[i]) // will contain AccessToken
     }
 }

If the authentication method is password based, the client must pass in a symmetric key which is used to encrypt and decrypt the credentials.

 import Sailfish.Accounts 1.0

 Account {
     id: account
     identifier: 13 // example: Jabber account id retrieved from AccountManager or AccountModel

     onStatusChanged: {
         if (status == Account.Initialized) {
             var siParams = signInParameters("jabber-im")
             if (!hasSignInCredentials("MyApp", "MyCredentials")) {
                 createSignInCredentials("MyApp", "JabberCredentials", "MySecretKey", siParams)
             } else {
                 signIn("MyApp", "JabberCredentials", "MySecretKey", siParams)
             }
         }
     }

     onSignInCredentialsCreated: {
         for (var i in data) console.log(i+"="+data[i]) // will contain Username + Password
     }

     onSignInResponse: {
         for (var i in data) console.log(i+"="+data[i]) // will contain Username + Password
     }
 }

To create an account, use the AccountManager type:

 import Sailfish.Accounts 1.0

 QtObject {
     id: root

     AccountManager {
         id: manager
         Component.onCompleted: manager.createAccount("facebook")
         onAccountCreated: account.identifier = accountId
     }

     Account {
         id: account

         onStatusChanged: {
             if (status == Account.Initialized) {
                 console.log("Successfully created account")
                 var siParams = signInParameters("facebook-sharing")
                 siParams.setParameter("ClientId", "123456789abcdef")
                 createSignInCredentials("MyApp", "SharingCredentials", siParams)
             }
         }

         onSignInCredentialsCreated: {
             console.log("Successfully created credentials")
             for (var i in data) console.log(i+"="+data[i]);
         }
     }
 }

Property Documentation

displayName : string

This property contains the display name of the account

The display name is the name of the account which should be displayed to users in selection lists, edit dialogues, and other user-interface contexts.

enabled : bool

This property will be true if the account can be used, or false if it cannot.

The account should be enabled if the details specified for it are valid. An account may need valid credentials associated with it before it can be enabled.

Note: After changing this property, the changed will be reflected in the property value but will not actually take effect in the database until sync() is called.

error : Account::Error

This property contains the most recent error which occurred during account creation or synchronisation.

Note that the error will NOT automatically return to NoError if subsequent synchronisation operations succeed.

errorMessage : string

This property contains the error message associated with the most recent error which occurred during account creation or synchronisation.

Note that the error message will NOT automatically return to being empty if subsequent synchronisation operations succeed.

identifier : int

This property contains the identifier of the Account.

The value of the property will be zero if the Account is a new, unsynced account. If the Account has been saved in the system accounts database, it will be non-zero.

When declaring an Account you must supply an identifier to cause the account to reference an account that already exists in the system accounts database - this identifier can be retrieved from the AccountManager.

providerName : string

This property contains the name of the service provider with which the account is valid.

An account provider plugin will provide a .provider file in /usr/share/accounts/providers which specifies the name of the provider.

status : Account::Status

This property contains the current database-sync status of the account

An account may have any of five statuses:

Status	Description
Initializing	The account is loading from the database
Initialized	The account is initialized and ready to be used
Synced	No outstanding local modifications to the account have occurred since last sync(). Any previous sync() calls have completed.
SyncInProgress	Any outstanding local modifications are currently being written to the database due to a call to sync(). No local property modifications may occur while the account has this status.
Modified	Local modifications to the account have occurred since last sync(). In order to persist the changes to the database, sync() must be called. Note that if another process modifies the canonical (database) version of the account, no signal will be emitted and thus the status of the local account representation will NOT automatically change to Modified.
SigningIn	The account is creating credentials or signing in with credentials
Error	An error occurred during account creation or synchronisation.
Invalid	The account has been removed from the database and is no longer valid.

Connecting to the account's statusChanged() signal is the usual way to handle database synchronisation events.

supportedServiceNames : QStringList

This property contains the names of services supported by the account

Every service provided by a provider has a service name which is specified in the .service file located at /usr/share/accounts/services which is installed by the account provider plugin.

Method Documentation

void blockingSync()

This is the same as sync(), but the operation is guaranteed to be synchronous.

cancelSignInOperation()

Cancels the sign-in operation started by a call to createSignInCredentials(), updateSignInCredentials() or signIn(). Upon cancellation, the signInError() is emitted with SignInOperationCanceledError.

This function has no effect if none of these functions have been called, or if the sign-in operation started by the function has already finished (that is, if signInCredentialsCreated(), signInCredentialsUpdated(), signInResponse() or signInError() have already been emitted).

QVariant configurationValue(const QString &serviceName, const QString &key)

Returns the individual configuration value for the account which applies specifically to the service with the specified serviceName and the specified key.

Some default settings are usually specified in the .service file installed by the account provider plugin. Other settings may be specified directly on an account for the service.

If the specified serviceName is empty, the a value from the account's global configuration settings will be retrieved instead, if it exists.

If the key does not exist for the given account and service, a null QVariant will be returned.

The configuration values are retrieved asynchronously after account construction. Clients should wait until the account is in the Initialized or Synced state before they attempt to access (or modify) the configuration values.

QVariantMap configurationValues(const QString &serviceName)

Returns the configuration settings for the account which apply specifically to the service with the specified serviceName. Note that it won't include global configuration settings which may also be applied (as fallback settings) when the account is used with the service.

Some default settings are usually specified in the .service file installed by the account provider plugin. Other settings may be specified directly on an account for the service.

If the specified serviceName is empty, the account's global configuration settings will be returned instead. Note: this does not return all configuration settings of all services; it only returns configuration settings which are globally applicable to all services for the account.

createSignInCredentials(const QString &applicationName, const QString &credentialsName, SignInParameters *parameters, const QString &symmetricKey = QString())

Creates sign-in credentials with this account for the application with the given applicationName named credentialsName (or named "default" if the credentialsName parameter is empty).

The account will transition to the SigningIn state when creation of the credentials commences.

If the parameters specify the OAuth method of authentication, sign-in will occur as part of the creation of credentials (and the user will be prompted for authorization via a web-view). The result of this process, if successful, will include an AccessToken. The symmetricKey parameter will be ignored for OAuth authentication.

If the parameters specify a password-based method of authentication, sign-in will not occur but instead the username and password specified in the parameters will be encrypted with the given symmetricKey and stored in the credentials. If the symmetricKey parameter is empty, the credentials will not be encrypted - which means that any application will be able to use those credentials with the service, and in fact the credentials will be set as the default credentials for the account with that service.

Once creation of credentials completes successfully the signInCredentialsCreated() signal will be emitted. If creation of the credentials encounters an error then the signInError() signal will be emitted. The account will transition to the Synced state just prior to emission of the success or error signals.

Calling this function will have no effect if the account is not initially in either the Initialized or Synced state.

void disableWithService(const QString &serviceName)

Disables the account with the service identified by the given serviceName.

If the service does not exist, or this account does not support the service, or the status of the account is either Invalid or SyncInProgress, the operation will silently fail.

Note: After calling this, isEnabledWithService() will report the service as disabled, but this change will not take effect in the database until sync() is called. The enabledWithServiceChanged() signal will be emitted when the change is committed to the database.

void enableWithService(const QString &serviceName)

Enables the account with the service identified by the given serviceName.

If the service does not exist, or this account does not support the service, or the status of the account is either Invalid or SyncInProgress, the operation will silently fail.

Note: After calling this, isEnabledWithService() will report the service as enabled, but this change will not take effect in the database until sync() is called. The enabledWithServiceChanged() signal will be emitted when the change is committed to the database.

hasSignInCredentials(const QString &applicationName, const QString &credentialsName) const

Returns true if the application named applicationName has created sign-in credentials with this account named credentialsName. If credentialsName is empty, the function returns true if the "default" named credentials have been created by the application.

Returns false if no credentials with the given credentialsName exist for the application. This function will also return false if the account is not in either the Initialized or Synced state.

bool isEnabledWithService(const QString &serviceName)

Returns true if the account is enabled with the specified service. Returns false if the account is not enabled with the specified service, or if the specified service does not exist, or is not supported by the account.

void remove()

Removes the account. A removed account becomes invalid. Any credentials associated with the account are also removed.

void removeConfigurationValue(const QString &serviceName, const QString &key)

Removes the configuration setting named key for the account which applies specifically to the service with the specified serviceName.

The serviceName must identify a service supported by the account, or be empty, else calling this function will have no effect. If the serviceName is empty, the global account configuration settings will updated instead.

removeSignInCredentials(const QString &applicationName, const QString &credentialsName)

Removes the sign-in credentials for the application with the given applicationName from the account, where the credentials are named the given credentialsName (or named "default" if the credentialsName parameter is empty).

Calling this function will have no effect if the account is not in either the Initialized or Synced state, if the application name specified is invalid, or if the account is currently busy creating or using sign in credentials.

void setConfigurationValue(const QString &serviceName, const QString &key, const QVariant &value)

Sets the configuration setting named key for the account which applies specifically to the service with the specified serviceName to the given value. The value must be of a supported type; see setConfigurationValues() for the list of types that are supported.

The value will only be set to be updated if it is different from the value collected at the last sync. This is to ensure any changes made by other processes in the background are preserved.

Signs the application with the given applicationName into the account using the per-application credentials identified by the given credentialsName. The given parameters will be used during sign-in (although any username or password specified in those parameters will be ignored).

If the sign-in process uses a password authentication system, the previously stored credentials (username and password) will be decrypted using the given symmetricKey, which means that if the key given is incorrect, sign-in will fail.

If the sign-in process uses an OAuth-based authentication system, the symmetricKey argument will be ignored, and the tokens associated with the ClientId or ConsumerKey specified in the parameters will be read from the database.

Emits signInResponseReceived() on success, or signInError() on failure.

Calling this function will have no effect if the account is not in either the Initialized or Synced state.

signOut(const QString &applicationName, const QString &credentialsName)

Signs the account out of the service where it had previously been signed in using the credentials named the given credentialsName (or named "default" if no credentialsName is given).

Client code should not call this method, as the account can remain signed in safely. Signing out will clear the cache of any tokens or credentials stored for the named credentials.

Calling this function will have no effect if the account is not in either the Initialized or Synced state.

void sync()

Writes any outstanding local modifications to the database. The operation may be either synchronous or asynchronous depending on whether the database is currently locked or open for writing. The account will transition to the SyncInProgress status and remain with that status for the duration of the synchronisation operation.

Calling this function will have no effect if the account is invalid or if a previous synchronisation operation is in progress.

updateSignInCredentials(const QString &applicationName, const QString &credentialsName, SignInParameters *parameters, const QString &symmetricKey)

Updates the existing credentials with the given credentialsName for the application with the given applicationName.

If the applicationName is invalid or the named credentials do not exist, or if the account is not in either the Initialized or Synced state, calling this function will immediately fail.

If the credentials are OAuth credentials, the tokens will be cleared and the user will be asked to sign in again via webview in order to generate new, valid tokens.

If the credentials are non-OAuth credentials, the username and password stored in the existing credentials will be cleared and replaced with those specified in the parameters. If the symmetricKey is non-empty, it will be used to encrypt the username and password before being stored.

On success the signInCredentialsUpdated() signal will be emitted. On failure the signInError() signal will be emitted. The account will transition to the Synced state just prior to the success or error signals being emitted.