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

Tp::ClientRegistrar Class Reference

The ClientRegistrar class is responsible for registering Telepathy clients (Observer, Approver, Handler). More...

#include <TelepathyQt4/ClientRegistrar>

Inherits Tp::RefCounted.

List of all members.

Public Member Functions

Static Public Member Functions


Detailed Description

The ClientRegistrar class is responsible for registering Telepathy clients (Observer, Approver, Handler).

Clients should inherit AbstractClientObserver, AbstractClientApprover, AbstractClientHandler or some combination of these, by using multiple inheritance, and register themselves using registerClient().

See the individual classes descriptions for more details.

Usage

Creating a client registrar object

One way to create a ClientRegistrar object is to just call the create method. For example:

 ClientRegistrarPtr cr = ClientRegistrar::create(); 

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

 ClientRegistrarPtr cr = ClientRegistrar::create(QDBusConnection::systemBus()); 

Registering a client

To register a client, just call registerClient with a given AbstractClientPtr pointing to a valid AbstractClient instance.

 class MyClient : public AbstractClientObserver, public AbstractClientHandler
 {
     ...
 };

 ...

 ClientRegistrarPtr cr = ClientRegistrar::create();
 SharedPtr<MyClient> client = SharedPtr<MyClient>(new MyClient(...));
 cr->registerClient(AbstractClientPtr::dynamicCast(client), "myclient");
See also:
AbstractClientObserver, AbstractClientApprover, AbstractClientHandler

Constructor & Destructor Documentation

Tp::ClientRegistrar::~ClientRegistrar (  ) 

Class destructor.


Member Function Documentation

ClientRegistrarPtr Tp::ClientRegistrar::create ( const QDBusConnection &  bus = QDBusConnection::sessionBus()  )  [static]

Create a new client registrar object using the given bus.

ClientRegistrar instances are unique per D-Bus connection. The returned ClientRegistrarPtr will point to the same ClientRegistrar instance on successive calls with the same bus, unless the instance had already been destroyed, in which case a new instance will be returned.

The resulting instance will use factories from a previous ClientRegistrar with the same bus, if any, otherwise factories returning stock TpQt4 subclasses as approriate, with no features prepared. This gives fully backwards compatible behavior for this function if the factory variants are never used.

Todo:
API/ABI break: Drop the bus-wide singleton guarantee, it's awkward and the associated name registration checks have always been implemented incorrectly anyway. We need this for the account friendly channel request and handle API at least.
Parameters:
bus QDBusConnection to use.
Returns:
A ClientRegistrarPtr object pointing to the ClientRegistrar.
ClientRegistrarPtr Tp::ClientRegistrar::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 client registrar object using QDBusConnection::sessionBus() and the given factories.

ClientRegistrar instances are unique per D-Bus connection. The returned ClientRegistrarPtr will point to the same ClientRegistrar instance on successive calls, unless the instance for QDBusConnection::sessionBus() had already been destroyed, in which case a new instance will be returned. Therefore, the factory settings have no effect if there already is a ClientRegistrar for QDBusConnection::sessionBus().

Todo:
API/ABI break: Drop the bus-wide singleton guarantee, it's awkward and the associated name registration checks have always been implemented incorrectly anyway. We need this for the account friendly channel request and handle API at least.
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:
A ClientRegistrarPtr object pointing to the ClientRegistrar.
ClientRegistrarPtr Tp::ClientRegistrar::create ( const QDBusConnection &  bus,
const AccountFactoryConstPtr accountFactory,
const ConnectionFactoryConstPtr connectionFactory,
const ChannelFactoryConstPtr channelFactory,
const ContactFactoryConstPtr contactFactory 
) [static]

Create a new client registrar object using the given bus and the given factories.

ClientRegistrar instances are unique per D-Bus connection. The returned ClientRegistrarPtr will point to the same ClientRegistrar instance on successive calls with the same bus, unless the instance had already been destroyed, in which case a new instance will be returned. Therefore, the factory settings have no effect if there already is a ClientRegistrar for the given bus.

Todo:
API/ABI break: Drop the bus-wide singleton guarantee, it's awkward and the associated name registration checks have always been implemented incorrectly anyway. We need this for the account friendly channel request and handle API at least.
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:
A ClientRegistrarPtr object pointing to the ClientRegistrar.
ClientRegistrarPtr Tp::ClientRegistrar::create ( const AccountManagerPtr manager  )  [static]

Create a new client registrar object using the bus and factories of the given Account manager.

ClientRegistrar instances are unique per D-Bus connection. The returned ClientRegistrarPtr will point to the same ClientRegistrar instance on successive calls with the same bus, unless the instance had already been destroyed, in which case a new instance will be returned. Therefore, the factory settings have no effect if there already is a ClientRegistrar for the bus of the given manager.

Using this create() method will enable (like any other way of passing the same factories to an AM and a registrar) getting the same Account/Connection etc. proxy instances from both AccountManager and AbstractClient implementations.

Todo:
API/ABI break: Drop the bus-wide singleton guarantee, it's awkward and the associated name registration checks have always been implemented incorrectly anyway. We need this for the account friendly channel request and handle API at least.
Parameters:
manager The AccountManager the bus and factories of which should be used.
Returns:
A ClientRegistrarPtr object pointing to the ClientRegistrar.
QDBusConnection Tp::ClientRegistrar::dbusConnection (  )  const

Return the D-Bus connection being used by this client registrar.

Returns:
QDBusConnection being used.
AccountFactoryConstPtr Tp::ClientRegistrar::accountFactory (  )  const

Get the account factory used by this client registrar.

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 registrar would have unpredictably different construction settings (eg. subclass).

Returns:
Read-only pointer to the factory.
ConnectionFactoryConstPtr Tp::ClientRegistrar::connectionFactory (  )  const

Get the connection factory used by this client registrar.

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 registrar would have unpredictably different construction settings (eg. subclass).

Returns:
Read-only pointer to the factory.
ChannelFactoryConstPtr Tp::ClientRegistrar::channelFactory (  )  const

Get the channel factory used by this client registrar.

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 registrar would have unpredictably different construction settings (eg. subclass).

Returns:
Read-only pointer to the factory.
ContactFactoryConstPtr Tp::ClientRegistrar::contactFactory (  )  const

Get the contact factory used by this client registrar.

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 registrar would have unpredictably different construction settings (eg. subclass).

Returns:
Read-only pointer to the factory.
QList< AbstractClientPtr > Tp::ClientRegistrar::registeredClients (  )  const

Return a list of clients registered using registerClient() on this client registrar.

Returns:
A list of registered clients.
See also:
registerClient()
bool Tp::ClientRegistrar::registerClient ( const AbstractClientPtr client,
const QString &  clientName,
bool  unique = false 
)

Register a client on D-Bus.

The client registrar will export the appropriate D-Bus interfaces, based on the abstract classes subclassed by

Parameters:
client. If each of a client instance should be able to manipulate channels separately, set unique to true.

The client name MUST be a non-empty string of ASCII digits, letters, dots and/or underscores, starting with a letter, and without sets of two consecutive dots or a dot followed by a digit.

This method will do nothing if the client is already registered, and true will be returned.

To unregister a client use unregisterClient().

Parameters:
client The client to register.
clientName The client name used to register.
unique Whether each of a client instance is able to manipulate channels separately.
Returns:
true if client was successfully registered, false otherwise.
See also:
registeredClients(), unregisterClient()
bool Tp::ClientRegistrar::unregisterClient ( const AbstractClientPtr client  ) 

Unregister a client registered using registerClient() on this client registrar.

If client was not registered previously, false will be returned.

Parameters:
client The client to unregister.
Returns:
true if client was successfully unregistered, false otherwise.
See also:
registeredClients(), registerClient()
void Tp::ClientRegistrar::unregisterClients (  ) 

Unregister all clients registered using registerClient() on this client registrar.

See also:
registeredClients(), registerClient(), unregisterClient()


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