Tp::AccountManager Class Reference

| Home · All Classes · All Namespaces · Modules · Functions · Files

Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::AccountManager Class Reference
Account manager proxies

The AccountManager class represents a Telepathy account manager. More...

`#include <TelepathyQt/AccountManager>`

Inherits Tp::StatelessDBusProxy, and Tp::OptionalInterfaceFactory< AccountManager >.

## Signals
void | newAccount (const Tp::AccountPtr &account)
Signals inherited from Tp::DBusProxy
void | invalidated (Tp::DBusProxy *proxy, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::Object
void | propertyChanged (const QString &propertyName)

## Public Member Functions
virtual | ~AccountManager ()
AccountFactoryConstPtr | accountFactory () const
ConnectionFactoryConstPtr | connectionFactory () const
ChannelFactoryConstPtr | channelFactory () const
ContactFactoryConstPtr | contactFactory () const
QList< AccountPtr > | allAccounts () const
AccountSetPtr | validAccounts () const
AccountSetPtr | invalidAccounts () const
AccountSetPtr | enabledAccounts () const
AccountSetPtr | disabledAccounts () const
AccountSetPtr | onlineAccounts () const
AccountSetPtr | offlineAccounts () const
AccountSetPtr | textChatAccounts () const
AccountSetPtr | textChatroomAccounts () const
AccountSetPtr | audioCallAccounts () const
AccountSetPtr | videoCallAccounts () const
AccountSetPtr | streamedMediaCallAccounts () const
AccountSetPtr | streamedMediaAudioCallAccounts () const
AccountSetPtr | streamedMediaVideoCallAccounts () const
AccountSetPtr | streamedMediaVideoCallWithAudioAccounts () const
AccountSetPtr | fileTransferAccounts () const
AccountSetPtr | accountsByProtocol (const QString &protocolName) const
AccountSetPtr | filterAccounts (const AccountFilterConstPtr &filter) const
AccountSetPtr | filterAccounts (const QVariantMap &filter) const
AccountPtr | accountForObjectPath (const QString &path) const
AccountPtr | accountForPath (const QString &path) const
QList< AccountPtr > | accountsForObjectPaths (const QStringList &paths) const
QList< AccountPtr > | accountsForPaths (const QStringList &paths) const
QStringList | supportedAccountProperties () const
PendingAccount * | createAccount (const QString &connectionManager, const QString &protocol, const QString &displayName, const QVariantMap &parameters, const QVariantMap &properties=QVariantMap())
Public Member Functions inherited from Tp::StatelessDBusProxy
| StatelessDBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~StatelessDBusProxy ()
Public Member Functions inherited from Tp::DBusProxy
| DBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~DBusProxy ()
QDBusConnection | dbusConnection () const
QString | busName () const
QString | objectPath () const
bool | isValid () const
QString | invalidationReason () const
QString | invalidationMessage () const
Public Member Functions inherited from Tp::Object
virtual | ~Object ()
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()
Public Member Functions inherited from Tp::ReadyObject
| ReadyObject (RefCounted *object, const Feature &featureCore)
| ReadyObject (DBusProxy *proxy, const Feature &featureCore)
virtual | ~ReadyObject ()
virtual bool | isReady (const Features &features=Features()) const
virtual PendingReady * | becomeReady (const Features &requestedFeatures=Features())
virtual Features | requestedFeatures () const
virtual Features | actualFeatures () const
virtual Features | missingFeatures () const
Public Member Functions inherited from Tp::OptionalInterfaceFactory< AccountManager >
| OptionalInterfaceFactory (AccountManager *this_)
| ~OptionalInterfaceFactory ()
QStringList | interfaces () const
bool | hasInterface (const QString &name) const
Interface * | optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
Interface * | interface () const

## Static Public Member Functions
static AccountManagerPtr | create (const QDBusConnection &bus)
static AccountManagerPtr | create (const AccountFactoryConstPtr &accountFactory=AccountFactory::create(QDBusConnection::sessionBus(), Account::FeatureCore), const ConnectionFactoryConstPtr &connectionFactory=ConnectionFactory::create(QDBusConnection::sessionBus()), const ChannelFactoryConstPtr &channelFactory=ChannelFactory::create(QDBusConnection::sessionBus()), const ContactFactoryConstPtr &contactFactory=ContactFactory::create())
static AccountManagerPtr | create (const QDBusConnection &bus, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory=ContactFactory::create())

## Static Public Attributes
static const Feature | FeatureCore

## Protected Member Functions
| AccountManager (const QDBusConnection &bus, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory, const Feature &coreFeature)
Client::AccountManagerInterface * | baseInterface () const
Protected Member Functions inherited from Tp::DBusProxy
void | setBusName (const QString &busName)
void | invalidate (const QString &reason, const QString &message)
void | invalidate (const QDBusError &error)
Protected Member Functions inherited from Tp::Object
| Object ()
void | notify (const char *propertyName)
Protected Member Functions inherited from Tp::ReadyObject
ReadinessHelper * | readinessHelper () const
Protected Member Functions inherited from Tp::OptionalInterfaceFactory< AccountManager >
void | setInterfaces (const QStringList &interfaces)

## Additional Inherited Members
Public Types inherited from Tp::OptionalInterfaceFactory< AccountManager >
enum | InterfaceSupportedChecking

## Detailed Description

The AccountManager class represents a Telepathy account manager.

The remote object accessor functions on this object (allAccounts(), validAccounts(), and so on) don't make any D-Bus calls; instead, they return/use values cached from a previous introspection run. The introspection process populates their values in the most efficient way possible based on what the service implements.

To avoid unnecessary D-Bus traffic, some accessors only return valid information after AccountManager::FeatureCore has been enabled. See the individual methods descriptions for more details.

AccountManager features can be enabled by calling becomeReady() with the desired set of features as an argument (currently only AccountManager::FeatureCore is supported), and waiting for the resulting PendingOperation to finish.

All accounts returned by AccountManager are guaranteed to have the features set in the AccountFactory used by it ready.

A signal is emitted to indicate that accounts are added. See newCreated() for more details.

# Usage

## Creating an AccountManager object

One way to create an AccountManager object is to just call the create method. For example:

AccountManagerPtr am = AccountManager::create();

An AccountManagerPtr object is returned, which will automatically keep track of object lifetime.

You can also provide a D-Bus connection as a QDBusConnection:

AccountManagerPtr am = AccountManager::create(QDBusConnection::sessionBus());

## Making AccountManager ready to use

An AccountManager object needs to become ready before usage, meaning that the introspection process finished and the object accessors can be used.

To make the object ready, use becomeReady() and wait for the PendingOperation::finished() signal to be emitted.

*
* class MyClass : public QObject
* {
* QOBJECT
*
* public:
* MyClass(QObject *parent = 0);
* ~MyClass() { }
*
* private Q_SLOTS:
* void onAccountManagerReady(Tp::PendingOperation*);
*
* private:
* AccountManagerPtr mAM;
* };
*
* MyClass::MyClass(QObject *parent)
* : QObject(parent)
* mAM(AccountManager::create())
* {
* connect(mAM->becomeReady(),
* SIGNAL(finished(Tp::PendingOperation*)),
* SLOT(onAccountManagerReady(Tp::PendingOperation*)));
* }
*
* void MyClass::onAccountManagerReady(Tp::PendingOperation *op)
* {
* if (op->isError()) {
* qWarning() << "Account manager cannot become ready:" <<
* op->errorName() << "-" << op->errorMessage();
* return;
* }
*
* // AccountManager is now ready
* qDebug() << "All accounts:";
* foreach (const Tp::AccountPtr &acc, mAM->allAccounts()) {
* qDebug() << " path:" << acc->objectPath();
* }
* }
*
*

See Asynchronous Object Model, Shared Pointer Usage

## Constructor & Destructor Documentation

Tp::AccountManager::~AccountManager | ( |  | ) |
| virtual

Class destructor.

Tp::AccountManager::AccountManager | ( | const QDBusConnection & | bus,
|  | const AccountFactoryConstPtr & | accountFactory,
|  | const ConnectionFactoryConstPtr & | connectionFactory,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory,
|  | const Feature & | coreFeature
| ) |  |
| protected

Construct a new AccountManager object using the given bus and the given factories.

The connection, channel and contact factories are passed to any Account objects created by this account manager object. In fact, they're not used directly by AccountManager at all.

A warning is printed if the factories are not for bus.

Parameters

  bus | QDBusConnection to use.
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.
  coreFeature | The core feature of the Account subclass. The corresponding introspectable should depend on AccountManager::FeatureCore.

## Member Function Documentation

AccountManagerPtr Tp::AccountManager::create | ( | const QDBusConnection & | bus | ) |
| static

Create a new AccountManager object using the given bus.

The instance will use an account factory creating Tp::Account objects with Account::FeatureCore ready, a connection factory creating Tp::Connection objects with no features ready, a channel factory creating stock Tp::Channel subclasses, as appropriate, with no features ready, and a contact factory creating Tp::Contact objects with no features ready.

Parameters

  bus | QDBusConnection to use.

Returns
  An AccountManagerPtr object pointing to the newly created AccountManager object.

AccountManagerPtr Tp::AccountManager::create | ( | const AccountFactoryConstPtr & | accountFactory = `AccountFactory::create(QDBusConnection::sessionBus(), Account::FeatureCore)`,
|  | const ConnectionFactoryConstPtr & | connectionFactory = `ConnectionFactory::create(QDBusConnection::sessionBus())`,
|  | const ChannelFactoryConstPtr & | channelFactory = `ChannelFactory::create(QDBusConnection::sessionBus())`,
|  | const ContactFactoryConstPtr & | contactFactory = `ContactFactory::create()`
| ) |  |
| static

Create a new AccountManager using QDBusConnection::sessionBus() and the given factories.

The connection, channel and contact factories are passed to any Account objects created by this account manager object. In fact, they're not used directly by AccountManager at all.

A warning is printed if the factories are for a bus different from QDBusConnection::sessionBus().

Parameters

  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

Returns
  An AccountManagerPtr object pointing to the newly created AccountManager object.

AccountManagerPtr Tp::AccountManager::create | ( | const QDBusConnection & | bus,
|  | const AccountFactoryConstPtr & | accountFactory,
|  | const ConnectionFactoryConstPtr & | connectionFactory,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory = `ContactFactory::create()`
| ) |  |
| static

Create a new AccountManager using the given bus and the given factories.

The connection, channel and contact factories are passed to any Account objects created by this account manager object. In fact, they're not used directly by AccountManager at all.

A warning is printed if the factories are not for bus.

Parameters

  bus | QDBusConnection to use.
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

Returns
  An AccountManagerPtr object pointing to the newly created AccountManager object.

AccountFactoryConstPtr Tp::AccountManager::accountFactory | ( |  | ) | const

Return the account factory used by this account manager.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the manager would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the AccountFactory object.

ConnectionFactoryConstPtr Tp::AccountManager::connectionFactory | ( |  | ) | const

Return the connection factory used by this account manager.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the manager would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the ConnectionFactory object.

ChannelFactoryConstPtr Tp::AccountManager::channelFactory | ( |  | ) | const

Return the channel factory used by this account manager.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the manager would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the ChannelFactory object.

ContactFactoryConstPtr Tp::AccountManager::contactFactory | ( |  | ) | const

Return the contact factory used by this account manager.

Only read access is provided. This allows constructing object instances and examining the object construction settings, but not changing settings. Allowing changes would lead to tricky situations where objects constructed at different times by the manager would have unpredictably different construction settings (eg. subclass).

Returns
  A read-only pointer to the ContactFactory object.

QList< AccountPtr > Tp::AccountManager::allAccounts | ( |  | ) | const

Return a list containing all accounts.

Newly accounts added and/or discovered are signaled via newAccount().

This method requires AccountManager::FeatureCore to be ready.

Returns
  A list of pointers to Account objects.

AccountSetPtr Tp::AccountManager::validAccounts | ( |  | ) | const

Return a set of accounts containing all valid accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::invalidAccounts | ( |  | ) | const

Return a set of accounts containing all invalid accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::enabledAccounts | ( |  | ) | const

Return a set of accounts containing all enabled accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::disabledAccounts | ( |  | ) | const

Return a set of accounts containing all disabled accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::onlineAccounts | ( |  | ) | const

Return a set of accounts containing all online accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::offlineAccounts | ( |  | ) | const

Return a set of accounts containing all offline accounts.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::textChatAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support text chats by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::textChatroomAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support text chat rooms.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::audioCallAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support audio calls (using the Call interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::videoCallAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support video calls (using the Call interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::streamedMediaCallAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support media calls (using the StreamedMedia interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::streamedMediaAudioCallAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support audio calls (using the StreamedMedia interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::streamedMediaVideoCallAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support video calls (using the StreamedMedia interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::streamedMediaVideoCallWithAudioAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support video calls with audio (using the StreamedMedia interface) by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::fileTransferAccounts | ( |  | ) | const

Return a set of accounts containing all accounts that support file transfers by providing a contact identifier.

For this method to work, you must use an AccountFactory which makes Account::FeatureCapabilities ready.

This method requires AccountManager::FeatureCore to be ready.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::accountsByProtocol | ( | const QString & | protocolName | ) | const

Return a set of accounts containing all accounts for the given protocolName.

This method requires AccountManager::FeatureCore to be ready.

Parameters

  protocolName | The name of the protocol used to filter accounts.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::filterAccounts | ( | const AccountFilterConstPtr & | filter | ) | const

Return a set of accounts containing all accounts that match the given filter criteria.

For AccountCapabilityFilter filtering, an AccountFactory which makes Account::FeatureCapabilities ready must be used.

See AccountSet documentation for more details.

This method requires AccountManager::FeatureCore to be ready.

Parameters

  filter | The desired filter.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountSetPtr Tp::AccountManager::filterAccounts | ( | const QVariantMap & | filter | ) | const

Return a set of accounts containing all accounts that match the given filter criteria.

The filter is composed by Account property names and values as map items.

The following example will return all jabber accounts that are enabled:

*
* void MyClass::init()
* {
* mAM = AccountManager::create();
* connect(mAM->becomeReady(),
* SIGNAL(finished(Tp::PendingOperation*)),
* SLOT(onAccountManagerReady(Tp::PendingOperation*)));
* }
*
* void MyClass::onAccountManagerReady(Tp::PendingOperation *op)
* {
* if (op->isError()) {
* qWarning() << "Account manager cannot become ready:" <<
* op->errorName() << "-" << op->errorMessage();
* return;
* }
*
* QVariantMap filter;
* filter.insert(QLatin1String("protocolName"), QLatin1String("jabber"));
* filter.insert(QLatin1String("enabled"), true);
* filteredAccountSet = mAM->filterAccounts(filter);
* // connect to AccountSet::accountAdded/accountRemoved signals
* QList<AccountPtr> accounts = filteredAccountSet->accounts();
* // do something with accounts
* }
*
*

See AccountSet documentation for more details.

This method requires AccountManager::FeatureCore to be ready.

Parameters

  filter | The desired filter.

Returns
  A pointer to an AccountSet object containing the matching accounts.

AccountPtr Tp::AccountManager::accountForObjectPath | ( | const QString & | path | ) | const

Return the account for the given path.

This method requires AccountManager::FeatureCore to be ready.

Parameters

  path | The account object path.

Returns
  A pointer to an AccountSet object containing the matching accounts.

See Also
  allAccounts(), accountsForObjectPaths()

AccountPtr Tp::AccountManager::accountForPath | ( | const QString & | path | ) | const

Deprecated:
  See accountForObjectPath()

QList< AccountPtr > Tp::AccountManager::accountsForObjectPaths | ( | const QStringList & | paths | ) | const

Return a list of accounts for the given paths.

The returned list will have one AccountPtr object for each given path. If a given path is invalid the returned AccountPtr object will point to 0. AccountPtr::isNull() will return true.

This method requires AccountManager::FeatureCore to be ready.

Parameters

  paths | List of accounts object paths.

Returns
  A list of pointers to Account objects for the given paths. Null AccountPtr objects will be used as list elements for each invalid path.

See Also
  allAccounts(), accountForObjectPath()

QList< AccountPtr > Tp::AccountManager::accountsForPaths | ( | const QStringList & | paths | ) | const

Deprecated:
  See accountsForObjectPaths()

QStringList Tp::AccountManager::supportedAccountProperties | ( |  | ) | const

Return a list of the fully qualified names of properties that can be set when calling createAccount().

Returns
  A list of fully qualified D-Bus property names, such as "org.freedesktop.Telepathy.Account.Enabled".

See Also
  createAccount()

PendingAccount * Tp::AccountManager::createAccount | ( | const QString & | connectionManager,
|  | const QString & | protocol,
|  | const QString & | displayName,
|  | const QVariantMap & | parameters,
|  | const QVariantMap & | properties = `QVariantMap()`
| ) |  |

Create an account with the given parameters.

The optional properties argument can be used to set any property listed in supportedAccountProperties() at the time the account is created.

Parameters

  connectionManager | The name of the connection manager to create the account for.
  protocol | The name of the protocol to create the account for.
  displayName | The account display name.
  parameters | The account parameters.
  properties | An optional map from fully qualified D-Bus property names such as "org.freedesktop.Telepathy.Account.Enabled" to their values.

Returns
  A PendingAccount object which will emit PendingAccount::finished when the account has been created of failed its creation process.

See Also
  supportedAccountProperties()

void Tp::AccountManager::newAccount | ( | const Tp::AccountPtr & | account | ) |
| signal

Emitted when a new account is created.

The new account will have the features set in the AccountFactory used by this account manager ready and the same connection, channel and contact factories as used by this account manager.

Parameters

  account | The newly created account.

Client::AccountManagerInterface * Tp::AccountManager::baseInterface | ( |  | ) | const
| protected

Return the Client::AccountManagerInterface interface proxy object for this account manager. This method is protected since the convenience methods provided by this class should generally be used instead of calling D-Bus methods directly.

Returns
  A pointer to the existing Client::AccountManagerInterface object for this AccountManager object.

## Member Data Documentation

const Feature Tp::AccountManager::FeatureCore
| static

Feature representing the core that needs to become ready to make the AccountManager object usable.

Note that this feature must be enabled in order to use most AccountManager methods.

When calling isReady(), becomeReady(), this feature is implicitly added to the requested features.