Account

The Account API lets you retrieve information about accounts that are present on a device. An account includes all of the information that's required to interact with a particular service and exchange data with that service. For example, an account might represent a Windows Live Hotmail email account that's configured to send and receive email on the device. Or an account might represent a Google Calendar that's part of a user's Gmail account.

Each type of account that users can add to the device (for example, Windows Live Hotmail, Gmail, and so on) can have multiple accounts within it. These accounts represent specific services inside the main account, and each one uses its own account entry in the account database on the device. For example, when you add a Gmail account to the device, you can choose to synchronize email, contacts, or calendar entries. Each of these services gets its own account; when you use the Account API to retrieve a list of all of the accounts on the device, these services appear as separate accounts in the list.

There are two pieces of information that determine the behavior and properties of an account: the service and provider. The service indicates what type of information the account handles. Most commonly, the service is a personal information management (PIM) type, such as calendar, contacts, or messages. The service can also be a less common type, such as geolocations or tags. The Service class enumerates all possible service types for an account.

The provider indicates how the account handles information from a particular service. For a given service type, there may be more than one provider that provides information for an account. Consider the messages service type (which uses the Service::Messages enumeration value). Some email accounts, such as Windows Live Hotmail, use ActiveSync as the provider. Others, such as Gmail, use Imap Email as the provider. The Provider class represents a single provider, and you can use this class to retrieve provider information such as name, ID, and advanced settings. The PIM Accounts sample app, which is shown in the image on the right and is available on the Sample apps page, demonstrates how to work effectively with providers and services.

Screen showing a sample app that accesses the accounts on a device.

The Account class represents a single account on the device, and it includes all of the information about the account, such as display name, provider, and owner. You can also query an Account object to determine whether the account supports a particular service, whether the account data is stored externally (for example, using a web service such as Gmail), or whether the account is an enterprise account.

In general, you probably won't use the Account API directly in many of the apps that you create. However, these APIs are an important foundation for other PIM APIs, which use them indirectly. For example, calendar events are uniquely identified using an account ID and a folder ID. By using an account ID, events can be associated with only one specific account on the device, regardless of how many other accounts might be present. To learn more about how to use the Account API in your apps, look at the PIM Accounts sample app on the Sample apps page.

You can use the Account API only to perform read operations on accounts. Any functions that require write access (such as adding, editing, or deleting accounts) are not available to third-party apps.

Prerequisites

To use the Account API in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbpim

Unlike other PIM APIs (such as the Calendar API), the Account API doesn't have an associated permission. Instead, your app receives read access to the account database when you request permission to access another PIM service:

You specify these permissions in the bar-descriptor.xml file for your app.

Retrieving account information

You can use the AccountService class to retrieve a list of accounts that are present on the device. There are several different ways to retrieve accounts, depending on what information you're looking for. To retrieve other account-related information, you can use the Account class.

Retrieve a single account

To retrieve a single account, you can call AccountService::account() and specify the account ID of the account that you want.

Not applicable

#include <bb/pim/account/AccountService>
#include <bb/pim/account/Account>

using namespace bb::pim::account;
AccountService accountService;
Account myAccount = accountService.account(myAccountId);

Not applicable

Retrieve a list of accounts

To retrieve multiple accounts at once, you can call one of the versions of the AccountService::accounts() function.

Not applicable

#include <bb/pim/account/AccountService>
#include <bb/pim/account/Account>
#include <bb/pim/account/Service>

using namespace bb::pim::account;
AccountService accountService;

// Retrieve all of the active accounts that are currently stored
// on the device
QList<Account> allAccts = accountService.accounts();

// Retrieve all accounts that are associated with a
// particular service (for example, the
// Service::Messages service)
QList<Account> allAcctsService = accountService.accounts(
                                     Service::Messages);

// Retrieve all accounts that are associated with a
// particular service and have the specified provider
QList<Account> allAcctsServiceProv = accountService.accounts(
                                         Service::Messages,
                                         myProviderId);

// Retrieve all accounts on the device, including any accounts
// that are disabled
QList<Account> allAcctsInclDis = accountService.allAccounts();

Not applicable

Retrieve the default accounts

To retrieve the default account for a service, you can call AccountService::defaultAccount() or AccountService::defaultAccounts().

Not applicable

#include <bb/pim/account/AccountService>
#include <bb/pim/account/Account>
#include <bb/pim/account/Service>

using namespace bb::pim::account;
AccountService accountService;

// Retrieve the default account for a particular service
// (for example, the Service::Contacts service)
Account defaultAcct = accountService.defaultAccount(
                          Service::Contacts);

// Retrieve the default accounts for all services
QMap<Service::Type, Account> allDefaultAccts = accountService.
                                               defaultAccounts();

Not applicable

Retrieve detailed account settings

An Account object, along with its associated Provider object, contains detailed information about the account, including connection settings, synchronization settings, and so on. Settings keys represent each piece of information and they let you access the settings for a specific account and provider. Here's an example of how to retrieve a list of valid keys and use them to access the detailed settings for an account:

Not applicable

#include <bb/pim/account/AccountService>
#include <bb/pim/account/Account>

using namespace bb::pim::account;
AccountService accountService;

// Retrieve an account from the database by using an account ID
Account myAccount = accountService.account(myAccountId);

// Retrieve the settings keys for the account provider and,
// for each key that's retrieved, retrieve the property
// that's associated with the key
foreach (const QString &key, myAccount.provider().settingsKeys())
{
    const QVariant value = account.settingsProperty(key);

    // Use the settings value to do something interesting
    // ...
}

Not applicable

Last modified: 2015-05-07



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus