Tp::BaseProtocol Class Reference

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

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Tp::BaseProtocol Class Reference
Connection manager service implementation

Base class for protocol implementations. More...

`#include <TelepathyQt/BaseProtocol>`

Inherits Tp::DBusService.

## Public Types
typedef Callback2 < BaseConnectionPtr, const QVariantMap &, DBusError * > | CreateConnectionCallback
typedef Callback2< QString, const QVariantMap &, DBusError * > | IdentifyAccountCallback
typedef Callback2< QString, const QString &, DBusError * > | NormalizeContactCallback

## Public Member Functions
virtual | ~BaseProtocol ()
QString | name () const
QVariantMap | immutableProperties () const
QStringList | connectionInterfaces () const
void | setConnectionInterfaces (const QStringList &connInterfaces)
ProtocolParameterList | parameters () const
void | setParameters (const ProtocolParameterList &parameters)
RequestableChannelClassSpecList | requestableChannelClasses () const
void | setRequestableChannelClasses (const RequestableChannelClassSpecList &rccSpecs)
QString | vcardField () const
void | setVCardField (const QString &vcardField)
QString | englishName () const
void | setEnglishName (const QString &englishName)
QString | iconName () const
void | setIconName (const QString &iconName)
QStringList | authenticationTypes () const
void | setAuthenticationTypes (const QStringList &authenticationTypes)
void | setCreateConnectionCallback (const CreateConnectionCallback &cb)
Tp::BaseConnectionPtr | createConnection (const QVariantMap &parameters, DBusError *error)
void | setIdentifyAccountCallback (const IdentifyAccountCallback &cb)
QString | identifyAccount (const QVariantMap &parameters, DBusError *error)
void | setNormalizeContactCallback (const NormalizeContactCallback &cb)
QString | normalizeContact (const QString &contactId, DBusError *error)
QList < AbstractProtocolInterfacePtr > | interfaces () const
AbstractProtocolInterfacePtr | interface (const QString &interfaceName) const
bool | plugInterface (const AbstractProtocolInterfacePtr &interface)
Public Member Functions inherited from Tp::DBusService
| DBusService (const QDBusConnection &dbusConnection)
virtual | ~DBusService ()
QDBusConnection | dbusConnection () const
QString | busName () const
QString | objectPath () const
DBusObject * | dbusObject () const
bool | isRegistered () const
Public Member Functions inherited from Tp::Object
virtual | ~Object ()
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()

## Static Public Member Functions
static BaseProtocolPtr | create (const QString &name)
template<typename BaseProtocolSubclass >
static SharedPtr < BaseProtocolSubclass > | create (const QString &name)
static BaseProtocolPtr | create (const QDBusConnection &dbusConnection, const QString &name)
template<typename BaseProtocolSubclass >
static SharedPtr < BaseProtocolSubclass > | create (const QDBusConnection &dbusConnection, const QString &name)

## Protected Member Functions
| BaseProtocol (const QDBusConnection &dbusConnection, const QString &name)
virtual bool | registerObject (const QString &busName, const QString &objectPath, DBusError *error)
Protected Member Functions inherited from Tp::Object
| Object ()
void | notify (const char *propertyName)

## Additional Inherited Members
Signals inherited from Tp::Object
void | propertyChanged (const QString &propertyName)

## Detailed Description

Base class for protocol implementations.

A Protocol is a D-Bus object that implements an IM protocol (for instance, jabber or msn). The BaseProtocol class provides an easy way to implement a Protocol D-Bus object, by providing the basic functionality itself and allowing you to extend it by setting the appropriate properties and callbacks.

A BaseProtocol instance cannot be registered by itself on the bus. You should add it to a BaseConnectionManager instance using BaseConnectionManager::addProtocol(). When the BaseConnectionManager is registered on the bus, all the BaseProtocol instances will also be registered.

## Member Typedef Documentation

typedef Callback2<BaseConnectionPtr, const QVariantMap &, DBusError*> Tp::BaseProtocol::CreateConnectionCallback

typedef Callback2<QString, const QVariantMap &, DBusError*> Tp::BaseProtocol::IdentifyAccountCallback

typedef Callback2<QString, const QString &, DBusError*> Tp::BaseProtocol::NormalizeContactCallback

## Constructor & Destructor Documentation

Tp::BaseProtocol::~BaseProtocol | ( |  | ) |
| virtual

Class destructor.

Tp::BaseProtocol::BaseProtocol | ( | const QDBusConnection & | dbusConnection,
|  | const QString & | name
| ) |  |
| protected

Constructs a new BaseProtocol object.

Parameters

  dbusConnection | The D-Bus connection to use.
  name | The name of this protocol.

## Member Function Documentation

static BaseProtocolPtr Tp::BaseProtocol::create | ( | const QString & | name | ) |
| inlinestatic

template<typename BaseProtocolSubclass >

static SharedPtr<BaseProtocolSubclass> Tp::BaseProtocol::create | ( | const QString & | name | ) |
| inlinestatic

static BaseProtocolPtr Tp::BaseProtocol::create | ( | const QDBusConnection & | dbusConnection,
|  | const QString & | name
| ) |  |
| inlinestatic

template<typename BaseProtocolSubclass >

static SharedPtr<BaseProtocolSubclass> Tp::BaseProtocol::create | ( | const QDBusConnection & | dbusConnection,
|  | const QString & | name
| ) |  |
| inlinestatic

QString Tp::BaseProtocol::name | ( |  | ) | const

Return the protocol's name, as given on the constructor.

Returns
  The protocol's name.

QVariantMap Tp::BaseProtocol::immutableProperties | ( |  | ) | const
| virtual

Return the immutable properties of this protocol object.

Immutable properties cannot change after the object has been registered on the bus with registerObject().

Returns
  The immutable properties of this protocol object.

Implements Tp::DBusService.

QStringList Tp::BaseProtocol::connectionInterfaces | ( |  | ) | const

Return the list of interface names that have been set with setConnectionInterfaces().

This list is exposed as the ConnectionInterfaces property of this Protocol object on the bus and represents interface names that might be in the Interfaces property of a Connection to this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The list of interface names that have been set with setConnectionInterfaces().

See Also
  setConnectionInterfaces()

void Tp::BaseProtocol::setConnectionInterfaces | ( | const QStringList & | connInterfaces | ) |

Set the interface names that may appear on Connection objects of this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  connInterfaces | The list of interface names to set.

See Also
  connectionInterfaces()

ProtocolParameterList Tp::BaseProtocol::parameters | ( |  | ) | const

Return the list of parameters that have been set with setParameters().

This list is exposed as the Parameters property of this Protocol object on the bus and represents the parameters which may be specified in the Parameters property of an Account for this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The list of parameters that have been set with setParameters().

See Also
  setParameters()

void Tp::BaseProtocol::setParameters | ( | const ProtocolParameterList & | parameters | ) |

Set the parameters that may be specified in the Parameters property of an Account for this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  parameters | The list of parameters to set.

See Also
  parameters()

RequestableChannelClassSpecList Tp::BaseProtocol::requestableChannelClasses | ( |  | ) | const

Return the list of requestable channel classes that have been set with setRequestableChannelClasses().

This list is exposed as the RequestableChannelClasses property of this Protocol object on the bus and represents the channel classes which might be requestable from a Connection to this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The list of requestable channel classes that have been set with setRequestableChannelClasses()

See Also
  setRequestableChannelClasses()

void Tp::BaseProtocol::setRequestableChannelClasses | ( | const RequestableChannelClassSpecList & | rccSpecs | ) |

Set the channel classes which might be requestable from a Connection to this protocol.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  rccSpecs | The list of requestable channel classes to set.

See Also
  requestableChannelClasses()

QString Tp::BaseProtocol::vcardField | ( |  | ) | const

Return the name of the vcard field that has been set with setVCardField().

This is exposed as the VCardField property of this Protocol object on the bus and represents the name of the most common vcard field used for this protocol's contact identifiers, normalized to lower case.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The name of the vcard field that has been set with setVCardField().

See Also
  setVCardField()

void Tp::BaseProtocol::setVCardField | ( | const QString & | vcardField | ) |

Set the name of the most common vcard field used for this protocol's contact identifiers, normalized to lower case.

For example, this would be x-jabber for Jabber/XMPP (including Google Talk), or tel for the PSTN.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  vcardField | The name of the vcard field to set.

See Also
  vcardField()

QString Tp::BaseProtocol::englishName | ( |  | ) | const

Return the name that has been set with setEnglishName().

This is exposed as the EnglishName property of this Protocol object on the bus and represents the name of the protocol in a form suitable for display to users, such as "AIM" or "Yahoo!".

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The name that has been set with setEnglishName().

See Also
  setEnglishName()

void Tp::BaseProtocol::setEnglishName | ( | const QString & | englishName | ) |

Set the name of the protocol in a form suitable for display to users, such as "AIM" or "Yahoo!".

This string should be in the C (english) locale. Clients are expected to lookup a translation on their own translation catalogs and fall back to this name if they have no translation for it.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  englishName | The name to set.

See Also
  englishName()

QString Tp::BaseProtocol::iconName | ( |  | ) | const

Return the icon name that has been set with setIconName().

This is exposed as the Icon property of this Protocol object on the bus and represents the name of an icon in the system's icon theme suitable for this protocol, such as "im-msn".

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The icon name set with setIconName().

See Also
  setIconName()

void Tp::BaseProtocol::setIconName | ( | const QString & | iconName | ) |

Set the name of an icon in the system's icon theme suitable for this protocol, such as "im-msn".

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  iconName | The icon name to set.

See Also
  iconName()

QStringList Tp::BaseProtocol::authenticationTypes | ( |  | ) | const

Return the list of interfaces that have been set with setAuthenticationTypes().

This is exposed as the AuthenticationTypes property of this Protocol object on the bus and represents a list of D-Bus interfaces which provide information as to what kind of authentication channels can possibly appear before the connection reaches the CONNECTED state.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  The list of authentication types that have been set with setAuthenticationTypes().

See Also
  setAuthenticationTypes()

void Tp::BaseProtocol::setAuthenticationTypes | ( | const QStringList & | authenticationTypes | ) |

Set a list of D-Bus interfaces which provide information as to what kind of authentication channels can possibly appear before the connection reaches the CONNECTED state.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  authenticationTypes | The list of interfaces to set.

See Also
  authenticationTypes()

void Tp::BaseProtocol::setCreateConnectionCallback | ( | const CreateConnectionCallback & | cb | ) |

Set a callback that will be called to create a new connection, when this has been requested by a client.

Parameters

  cb | The callback to set.

See Also
  createConnection()

BaseConnectionPtr Tp::BaseProtocol::createConnection | ( | const QVariantMap & | parameters,
|  | Tp::DBusError * | error
| ) |  |

Create a new connection object by calling the callback that has been set with setCreateConnectionCallback().

Parameters

  parameters | The connection parameters.
  error | A pointer to a DBusError instance where any possible error will be stored.

Returns
  A pointer to the new connection, or a null BaseConnectionPtr if no connection could be created, in which case error will contain an appropriate error.

See Also
  setCreateConnectionCallback()

void Tp::BaseProtocol::setIdentifyAccountCallback | ( | const IdentifyAccountCallback & | cb | ) |

Set a callback that will be called from a client to identify an account.

This callback will be called when the IdentifyAccount method on the Protocol D-Bus object has been called.

Parameters

  cb | The callback to set.

See Also
  identifyAccount()

QString Tp::BaseProtocol::identifyAccount | ( | const QVariantMap & | parameters,
|  | Tp::DBusError * | error
| ) |  |

Return a string which uniquely identifies the account to which the given parameters would connect, by calling the callback that has been set with setIdentifyAccountCallback().

Parameters

  parameters | The connection parameters, as they would be provided to createConnection().
  error | A pointer to a DBusError instance where any possible error will be stored.

Returns
  A string which uniquely identifies the account to which the given parameters would connect, or an empty string if no callback to create this string has been set with setIdentifyAccountCallback().

See Also
  setIdentifyAccountCallback()

void Tp::BaseProtocol::setNormalizeContactCallback | ( | const NormalizeContactCallback & | cb | ) |

Set a callback that will be called from a client to normalize a contact id.

Parameters

  cb | The callback to set.

See Also
  normalizeContact()

QString Tp::BaseProtocol::normalizeContact | ( | const QString & | contactId,
|  | Tp::DBusError * | error
| ) |  |

Return a normalized version of the given contactId, by calling the callback that has been set with setNormalizeContactCallback().

Parameters

  contactId | The contact ID to normalize.
  error | A pointer to a DBusError instance where any possible error will be stored.

Returns
  A normalized version of the given contactId, or an empty string if no callback to do the normalization has been set with setNormalizeContactCallback().

See Also
  setNormalizeContactCallback()

QList< AbstractProtocolInterfacePtr > Tp::BaseProtocol::interfaces | ( |  | ) | const

Return a list of interfaces that have been plugged into this Protocol D-Bus object with plugInterface().

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Returns
  A list containing all the Protocol interface implementation objects.

See Also
  plugInterface(), interface()

AbstractProtocolInterfacePtr Tp::BaseProtocol::interface | ( | const QString & | interfaceName | ) | const

Return a pointer to the interface with the given name.

Parameters

  interfaceName | The D-Bus name of the interface, ex. TP_QT_IFACE_PROTOCOL_INTERFACE_ADDRESSING.

Returns
  A pointer to the AbstractProtocolInterface object that implements the D-Bus interface with the given name, or a null pointer if such an interface has not been plugged into this object.

See Also
  plugInterface(), interfaces()

bool Tp::BaseProtocol::plugInterface | ( | const AbstractProtocolInterfacePtr & | interface | ) |

Plug a new interface into this Protocol D-Bus object.

This property is immutable and cannot change after this Protocol object has been registered on the bus with registerObject().

Parameters

  interface | An AbstractProtocolInterface instance that implements the interface that is to be plugged.

Returns
  `true` on success or `false` otherwise

See Also
  interfaces(), interface()

bool Tp::BaseProtocol::registerObject | ( | const QString & | busName,
|  | const QString & | objectPath,
|  | DBusError * | error
| ) |  |
| protectedvirtual

Reimplemented from DBusService.

Reimplemented from Tp::DBusService.