Home · All Classes · All Namespaces · Modules · Functions · Files
Signals | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions

Tp::AccountManager Class Reference
[Account manager proxies]

The AccountManager class provides an object representing a Telepathy account manager. More...

#include <TelepathyQt4/AccountManager>

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

List of all members.

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

The AccountManager class provides an object representing a Telepathy account manager.

AccountManager adds the following features compared to using Client::AccountManagerInterface directly:

The remote object accessor functions on this object (allAccountPaths(), allAccounts(), 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. Their return value is mostly undefined until the introspection process is completed, i.e. isReady() returns true. See the individual accessor descriptions for more details.

Signals are emitted to indicate that accounts are added/removed and when accounts validity changes. See accountCreated(), accountRemoved(), accountValidityChanged().

Usage

Creating an account manager 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 account manager 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 am;
 };

 MyClass::MyClass(QObject *parent)
     : QObject(parent)
       am(AccountManager::create())
 {
     connect(am->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() << "Valid accounts:";
     foreach (const QString &path, am->validAccountPaths()) {
         qDebug() << " path:" << path;
     }
 }

See Asynchronous Object Model, Shared Pointer Usage

Constructor & Destructor Documentation

Tp::AccountManager::~AccountManager (  )  [virtual]

Class destructor.

Tp::AccountManager::AccountManager (  )  [protected]

Construct a new AccountManager object using QDBusConnection::sessionBus().

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, and a channel factory creating stock Telepathy-Qt4 channel subclasses, as appropriate, with no features ready.

Deprecated:
Tp::AccountManager::AccountManager ( const QDBusConnection &  bus  )  [protected]

Construct 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, and a channel factory creating stock Telepathy-Qt4 channel subclasses, as appropriate, with no features ready.

Deprecated:
Parameters:
bus QDBusConnection to use.
Tp::AccountManager::AccountManager ( const QDBusConnection &  bus,
const AccountFactoryConstPtr &  accountFactory,
const ConnectionFactoryConstPtr &  connectionFactory,
const ChannelFactoryConstPtr &  channelFactory,
const ContactFactoryConstPtr &  contactFactory 
) [protected]

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

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.

Member Function Documentation

AccountManagerPtr Tp::AccountManager::create (  )  [static]

Create a new AccountManager object using QDBusConnection::sessionBus().

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, and a channel factory creating stock Telepathy-Qt4 channel subclasses, as appropriate, with no features ready.

Returns:
An AccountManagerPtr object pointing to the newly created AccountManager object.
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, and a channel factory creating stock Telepathy-Qt4 channel subclasses, as appropriate, 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,
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 and channel factories are passed to any Account objects created by this 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 and channel factories are passed to any Account objects created by this 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.
Returns:
An AccountManagerPtr object pointing to the newly created AccountManager object.
AccountFactoryConstPtr Tp::AccountManager::accountFactory (  )  const

Get the account factory used by this 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:
Read-only pointer to the factory.
ConnectionFactoryConstPtr Tp::AccountManager::connectionFactory (  )  const

Get the connection factory used by this 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:
Read-only pointer to the factory.
ChannelFactoryConstPtr Tp::AccountManager::channelFactory (  )  const

Get the channel factory used by this 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:
Read-only pointer to the factory.
ContactFactoryConstPtr Tp::AccountManager::contactFactory (  )  const

Get the contact factory used by this 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:
Read-only pointer to the factory.
QStringList Tp::AccountManager::validAccountPaths (  )  const

Return a list of object paths for all valid accounts.

Deprecated:
Use validAccountsSet() instead.
Returns:
A list of object paths.
QStringList Tp::AccountManager::invalidAccountPaths (  )  const

Return a list of object paths for all invalid accounts.

Deprecated:
Use invalidAccountsSet() instead.
Returns:
A list of object paths.
QStringList Tp::AccountManager::allAccountPaths (  )  const

Return a list of object paths for all accounts.

Deprecated:
Use allAccounts() instead.
Returns:
A list of object paths.
QList< AccountPtr > Tp::AccountManager::validAccounts (  ) 

Return a list of AccountPtr objects for all valid accounts.

Deprecated:
Use validAccountsSet() instead.
Returns:
A list of AccountPtr objects.
See also:
invalidAccounts(), allAccounts(), accountsForPaths()
QList< AccountPtr > Tp::AccountManager::invalidAccounts (  ) 

Return a list of AccountPtr objects for all invalid accounts.

Deprecated:
Use invalidAccountsSet() instead.
Returns:
A list of AccountPtr objects.
See also:
validAccounts(), allAccounts(), accountsForPaths()
QList< AccountPtr > Tp::AccountManager::allAccounts (  ) 

Return a list of AccountPtr objects for all accounts.

Returns:
A list of AccountPtr objects.
See also:
validAccounts(), invalidAccounts(), accountsForPaths()
AccountSetPtr Tp::AccountManager::validAccountsSet (  )  const

Return a set of accounts containing all valid accounts.

Returns:
A set of accounts containing all valid accounts.
AccountSetPtr Tp::AccountManager::invalidAccountsSet (  )  const

Return a set of accounts containing all invalid accounts.

Returns:
A set of accounts containing all invalid accounts.
AccountSetPtr Tp::AccountManager::enabledAccountsSet (  )  const

Return a set of accounts containing all enabled accounts.

Returns:
A set of accounts containing all enabled accounts.
AccountSetPtr Tp::AccountManager::disabledAccountsSet (  )  const

Return a set of accounts containing all disabled accounts.

Returns:
A set of accounts containing all disabled accounts.
AccountSetPtr Tp::AccountManager::onlineAccountsSet (  )  const

Return a set of accounts containing all online accounts.

Returns:
A set of accounts containing all online accounts.
AccountSetPtr Tp::AccountManager::offlineAccountsSet (  )  const

Return a set of accounts containing all offline accounts.

Returns:
A set of accounts containing all offline accounts.
AccountSetPtr Tp::AccountManager::textChatAccountsSet (  )  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.

Returns:
A set of accounts containing all accounts that support text chats by providing a contact identifier.
AccountSetPtr Tp::AccountManager::textChatRoomAccountsSet (  )  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.

Returns:
A set of accounts containing all accounts that support text chat rooms.
AccountSetPtr Tp::AccountManager::mediaCallAccountsSet (  )  const

Return a set of accounts containing all accounts that support media calls by providing a contact identifier.

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

Returns:
A set of accounts containing all accounts that support media calls by providing a contact identifier.
AccountSetPtr Tp::AccountManager::audioCallAccountsSet (  )  const

Return a set of accounts containing all accounts that support audio calls by providing a contact identifier.

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

Returns:
A set of accounts containing all accounts that support audio calls by providing a contact identifier.
AccountSetPtr Tp::AccountManager::videoCallAccountsSet ( bool  withAudio = true  )  const

Return a set of accounts containing all accounts that support video calls by providing a contact identifier.

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

Returns:
A set of accounts containing all accounts that support video calls by providing a contact identifier.
AccountSetPtr Tp::AccountManager::fileTransferAccountsSet (  )  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.

Returns:
A set of accounts containing all accounts that support file transfers by providing a contact identifier.
AccountSetPtr Tp::AccountManager::accountsByProtocol ( const QString &  protocolName  )  const

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

Parameters:
protocolName The name of the protocol used to filter accounts.
Returns:
A set of accounts containing all accounts for the given protocolName.
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.

Parameters:
filter The desired filter
Returns:
A set of accounts containing all accounts that match the given filter criteria.
AccountSetPtr Tp::AccountManager::filterAccounts ( const QList< AccountFilterConstPtr > &  filters  )  const

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

See AccountSet documentation for more details.

Parameters:
filters The desired filters
Returns:
A set of accounts containing all accounts that match the given filters criteria.
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()
 {
     am = AccountManager::create();
     connect(am->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 = am->filterAccounts(filter);
     // connect to AccountSet::accountAdded/accountRemoved signals
     QList<AccountPtr> accounts = filteredAccountSet->accounts();
     // do something with accounts
 }

See AccountSet documentation for more details.

Parameters:
filter The desired filter
Returns:
A set of accounts containing all accounts that match the given filter criteria.
AccountPtr Tp::AccountManager::accountForPath ( const QString &  path  ) 

Return an AccountPtr object for the given path.

This method requires AccountManager::FeatureCore to be enabled.

Parameters:
path The account object path.
Returns:
An AccountPtr object pointing to the Account object for the given path, or a null AccountPtr if path is invalid.
See also:
validAccounts(), invalidAccounts(), accountsForPaths()
QList< AccountPtr > Tp::AccountManager::accountsForPaths ( const QStringList &  paths  ) 

Return a list of AccountPtr objects 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 enabled.

Parameters:
paths List of accounts object paths.
Returns:
A list of AccountPtr objects.
See also:
validAccounts(), invalidAccounts(), allAccounts(), accountForPath()
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 Name of the connection manager to create the account for.
protocol 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()
Client::DBus::PropertiesInterface * Tp::AccountManager::propertiesInterface (  )  const [inline]

Convenience function for getting a PropertiesInterface interface proxy object for this account manager. The AccountManager interface relies on properties, so this interface is always assumed to be present.

Deprecated:
Use optionalInterface() instead.
Returns:
A pointer to the existing Client::DBus::PropertiesInterface object for this AccountManager object.
void Tp::AccountManager::accountCreated ( const QString &  path  )  [signal]

This signal is emitted when a new account is created.

Deprecated:
Use newAccount() instead.
Parameters:
path The object path of the newly created account.
See also:
accountForPath()
void Tp::AccountManager::accountRemoved ( const QString &  path  )  [signal]

This signal is emitted when an account gets removed.

Deprecated:
Use Account::removed() instead.
Parameters:
path The object path of the removed account.
See also:
accountForPath()
void Tp::AccountManager::accountValidityChanged ( const QString &  path,
bool  valid 
) [signal]

This signal is emitted when an account validity changes.

Deprecated:
Use Account::validityChanged() instead.
Parameters:
path The object path of the account in which the validity changed.
valid Whether the account is valid or not.
See also:
accountForPath()
void Tp::AccountManager::newAccount ( const Tp::AccountPtr &  account  )  [signal]
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.
void Tp::AccountManager::connectNotify ( const char *  signalName  )  [protected]

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 any AccountManager method.

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

Copyright © 2008-2010 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.4.4