AccountService

Since: BlackBerry 10.0.0

#include <bb/pim/account/AccountService>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The AccountService class is the entry point for Account Management.

It provides operations to manipulate Account objects and to view Provider objects, which are used to build Account objects.

Read access to the Account's domain is automatically granted when requesting permission to another domain (access_pimdomain_messages or access_pimdomain_contacts or access_pimdomain_calendars or access_pimdomain_notebooks). Any Account calls requiring write access (to edit, add or delete an account) are not granted to third party applications and will result in failure.

A signal is emitted when accounts are added, deleted, or modified. Clients can respond to these signals.


Overview

Public Functions Index

AccountService ()
virtual ~AccountService ()
Accountaccount (AccountKey accountId)
QList< Account >accounts ()
QList< Account >accounts (Service::Type service)
QList< Account >accounts (Service::Type service, const QString &providerId)
ResultcreateAccount (const QString &providerId, Account &accountData)
ResultcreateAccount (const QString &providerId, Account &accountData, const QString &accessSecret)
AccountdefaultAccount (Service::Type service)
QMap< Service::Type, Account >defaultAccounts ()
ResultdeleteAccount (AccountKey accountId)
ObjectKeygetDefault (Service::Type service)
Providerprovider (const QString &providerId)
QList< Provider >providers ()
ResultsetDefault (Service::Type service, AccountKey accountId, ObjectKey objectId)
AccountsetDefaultAccount (Service::Type service, AccountKey accountId)
ResultsyncAccounts (Service::Type service)
ResulttestAccount (AccountKey accountId)
ResultupdateAccount (AccountKey accountId, const Account &accountData)

Signals Index

voidaccountsChanged (const bb::pim::account::AccountsChanged &notification)

Public Functions

AccountService ()

Creates a new AccountService object.

Since:

BlackBerry 10.0.0

virtual~AccountService ()

Destructor.

Since:

BlackBerry 10.0.0

Account account (
  • AccountKeyaccountId)

Retrieves a specific Account object.

Parameters
accountId

The value of the Account object's id property used to identify a specific account.

Return:

Returns the Account object whose id property is set to accountId, or an invalid Account object if no matches were found.

Since:

BlackBerry 10.0.0

QList< Account > accounts ()

Retrieves the list of Account objects currently stored on the device.

Return:

Returns a QList containing Account objects.

Since:

BlackBerry 10.0.0

QList< Account > accounts (

Retrieves the list of Account objects currently stored on the device and currently synchronizing data for the service.

Parameters
service

The value for which we seek the Account::isServiceSupported(service) function to be set to true.

Return:

Returns a QList containing Account objects, or an empty QList if no matches were found.

Since:

BlackBerry 10.0.0

QList< Account > accounts (

Retrieves the list of Account objects currently stored on the device, currently synchronizing data for the service and created from a specific provider.

Parameters
service

The value for which we seek the Account::isServiceSupported(service) function to be set to true.

providerId

The value of the Provider object's id property used to identify the provider to match with the Account::provider() function.

Return:

Returns a QList containing Account objects, or an empty QList if no matches were found.

Since:

BlackBerry 10.0.0

Result createAccount (

Creates an Account object.

Parameters
providerId

The value of a Provider object's id property used to identify the specific provider to use in creating a new Account object.

accountData

The data used to create the Account object. Initially, the accountData should be created using the Account constructor that takes a provider object as an argument. This will generate the account with the provider's default values. You can change the default values using the setters available before calling this function to create the account. The id property should not be included in accountData as a new identifier will be generated. The newly-created account will be returned in accountData if the function is successful.

Return:

Returns a Result object with success set to true if the account creation is successful. If the account creation fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

Result createAccount (

Creates an Account object specifying an access secret.

Parameters
providerId

The value of a Provider object's id property used to identify the specific provider to use in creating a new Account object.

accountData

The data used to create the Account object. Initially, the accountData should be created using the Account constructor that takes a provider object as an argument. This will generate the account with the provider's default values. You can change the default values using the setters available before calling this function to create the account. The id property should not be included in accountData as a new identifier will be generated. The newly-created account will be returned in accountData if the function is successful.

accessSecret

The secret needed to be passed by clients to access this account. The secret can only be passed at creation time and never modified. Clients pass this secret into SessionManagementService::setSessionSecret() before making any PIM Lib calls. Doing so allows access to this account; otherwise the account is hidden from the client.

Return:

Returns a Result object with success set to true if the account creation is successful. If the account creation fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.2.0

Account defaultAccount (

Retrieves the default account set for a specific service.

The default account is used by applications to specify the output outlet. For example, the default account for Service::Messages specifies the account from which an email application to send email from.

Parameters
service

The value of service for which we seek the default account.

Return:

Returns the default account for the specific service, or an invalid account if no default exists for that service.

Since:

BlackBerry 10.0.0

QMap< Service::Type, Account > defaultAccounts ()

Retrieves the default accounts set for all services.

Return:

Returns a QMap containing the default accounts that are set for all services.

Since:

BlackBerry 10.0.0

Result deleteAccount (
  • AccountKeyaccountId)

Deletes an Account object.

Parameters
accountId

The value of a Account object's id property used to identify the account to delete.

Return:

Returns a Result object with success set to true if the account deletion is successful. If the account deletion fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

ObjectKey getDefault (

Retrieves the object ID set as the default for a specific service.

This is useful for Service::Calendars which requires an account as well as a calendar folder as the default. This functionality is also available by using the CalendarService::defaultCalendarFolder() function. It is recommended that the latter be used.

Parameters
service

The value of service for which we seek the default account and object.

Return:

Returns the object ID set as the default for service, and Account::InvalidKey if no default exists for that service.

Since:

BlackBerry 10.0.0

Provider provider (

Retrieves a specific Provider object.

Parameters
providerId

The value of the Provider object's id property used to identify a specific provider.

Return:

Returns the Provider object whose id property is set to providerId, or an invalid Provider object if no matches were found.

Since:

BlackBerry 10.0.0

QList< Provider > providers ()

Retrieves the list of all Provider objects.

Return:

Returns a QList of Provider objects.

Since:

BlackBerry 10.0.0

Result setDefault (

Associates a specific account and object as the default for a specific service.

Note: Changing the default for a specific service affects all applications that are using the default account functionality.

This is useful for Service::Calendars which requires an account as well as a calendar folder as the default. This functionality is also available by using the CalendarService::setDefaultCalendarFolder() function. It is recommended that the latter be used.

Parameters
service

The value of service for which we seek to change the default account and object.

accountId

The value of an Account object's id property used to identify the account to set as the default. The account in question must exist and it must currently support service to be considered as the default account.

objectId

The value of an object located within the Account object specified by accountId.

Return:

Returns a Result object with success set to true if setting the new default is successful. If setting the new default fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

Account setDefaultAccount (

Associates a specific account as the default for a specific service.

Note: Changing the default for a specific service affects all applications that are using the default account functionality.

For Service::Calendars, this call will be ignored and the current default account will be returned. To set the default calendar, use CalendarService::setDefaultCalendarFolder instead.

Parameters
service

The value of service for which we seek to change the default account.

accountId

The value of an Account object's id property used to identify the account to set as the default. The account in question must exist and it must currently support service to be considered as the default account.

Return:

Returns the default account for service. For Service::Calendars, this call will be ignored and the current default account will be returned.

Since:

BlackBerry 10.0.0

Result syncAccounts (

Synchronizes the data for service of all Account objects that currently support it.

Parameters
service

The value of service for which we seek to synchronize the data.

Return:

Returns a Result object with success set to true if the synchronization is successful. If the synchronization fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

Result testAccount (
  • AccountKeyaccountId)

Validates an Account object based on provider-specific checks.

Parameters
accountId

The value of a Account object's id property used to identify the account to test.

Return:

Returns a Result object with success set to true if the account validation is successful. If the account validation fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

Result updateAccount (
  • AccountKeyaccountId,
  • const Account &accountData )

Updates an Account object.

Parameters
accountId

The value of this Account object's id property. This value must match the id property found in accountData.

accountData

The data used to update the Account object. Initially, the accountData should be created using the already existing account with property specified by accountId. The user may then choose to change some of the values using the setters available before calling this function to update the account. The id property of accountData must match the value in accountId.

Return:

Returns a Result object with success set to true if the account update is successful. If the account update fails, returns a Result object with success set to false and message containing the detailed error message that caused the failure.

Since:

BlackBerry 10.0.0

Signals

void accountsChanged (

Represents the signal emitted when one or more Account objects have been changed (added, updated, or deleted).

Parameters
notification

The lists of account ids for added, updated, or deleted accounts. See the AccountsChanged class for more details.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus