TelepathyQt4: Tp::CapabilitiesBase Class Reference

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

# Tp::CapabilitiesBase Class Reference
[Connection proxies]

The CapabilitiesBase class provides an object representing the capabilities a Connection or a Contact supports. More...

`#include <TelepathyQt4/CapabilitiesBase>`

Inherited by Tp::ConnectionCapabilities, and Tp::ContactCapabilities.

List of all members.

## Public Member Functions

- virtual ~CapabilitiesBase ()
- RequestableChannelClassList requestableChannelClasses () const
- bool isSpecificToContact () const
- bool supportsTextChats () const
- bool supportsMediaCalls () const
- bool supportsAudioCalls () const
- bool supportsVideoCalls (bool withAudio=true) const
- bool supportsUpgradingCalls () const

## Protected Member Functions

- CapabilitiesBase (bool specificToContact)
- CapabilitiesBase (const RequestableChannelClassList &classes, bool specificToContact)
- virtual void updateRequestableChannelClasses (const RequestableChannelClassList &classes)

## Detailed Description

The CapabilitiesBase class provides an object representing the capabilities a Connection or a Contact supports.

## Constructor & Destructor Documentation

Tp::CapabilitiesBase::~CapabilitiesBase | ( |  | ) | `[virtual]`

Class destructor.

Tp::CapabilitiesBase::CapabilitiesBase | ( | bool | specificToContact | ) | `[protected]`

Construct a new CapabilitiesBase object.

Parameters:

  | specificToContact | Whether this object describes the capabilities of a particular contact.

Tp::CapabilitiesBase::CapabilitiesBase | ( | const RequestableChannelClassList & | classes,
|  | bool | specificToContact |
| ) |  |  | `[protected]`

Construct a new CapabilitiesBase object using the given classes.

Parameters:

  | classes | RequestableChannelClassList representing the capabilities of a connection or contact.
  | specificToContact | Whether this object describes the capabilities of a particular contact.

## Member Function Documentation

RequestableChannelClassList Tp::CapabilitiesBase::requestableChannelClasses | ( |  | ) | const

Return the underlying data structure used by Telepathy to represent the requests that can succeed.

This can be used by advanced clients to determine whether an unusually complex request would succeed. See the Telepathy D-Bus API Specification for details of how to interpret the returned list of QVariantMap objects.

The higher-level methods like supportsTextChats() are likely to be more useful to the majority of clients.

Returns:
  A RequestableChannelClassList indicating the parameters to Account::createChannel, Account::ensureChannel, Connection::createChannel and Connection::ensureChannel that can be expected to work.

bool Tp::CapabilitiesBase::isSpecificToContact | ( |  | ) | const

Return whether this object accurately describes the capabilities of a particular contact, or if it's only a guess based on the capabilities of the underlying connection.

In protocols like XMPP where each contact advertises their capabilities to others, Contact::capabilities() will generally return an object where this method returns true.

In protocols like SIP where contacts' capabilities are not known, Contact::capabilities() will return an object where this method returns false, whose methods supportsTextChats() etc. are based on what the underlying connection supports.

This reflects the fact that the best assumption an application can make is that every contact supports every channel type supported by the connection, while indicating that requests to communicate might fail if the contact does not actually have the necessary functionality.

Returns:
  `true` if this object describes the capabilities of a particular contact, `false` otherwise.

bool Tp::CapabilitiesBase::supportsTextChats | ( |  | ) | const

Return whether private text channels can be established by providing a contact identifier.

If the protocol is such that text chats can be established, but only via a more elaborate D-Bus API than normal (because more information is needed), then this method will return false.

Returns:
  `true` if Account::ensureTextChat() can be expected to work, `false` otherwise.

bool Tp::CapabilitiesBase::supportsMediaCalls | ( |  | ) | const

Return whether private audio and/or video calls can be established by providing a contact identifier.

If the protocol is such that these calls can be established, but only via a more elaborate D-Bus API than normal (because more information is needed), then this method will return false.

Returns:
  `true` if Account::ensureMediaCall() can be expected to work, `false` otherwise.

See also:
  supportsAudioCalls(), supportsVideoCalls()

bool Tp::CapabilitiesBase::supportsAudioCalls | ( |  | ) | const

Return whether private audio calls can be established by providing a contact identifier.

Call supportsUpgradingCalls() to determine whether such calls are likely to be upgradable to have a video stream later.

If the protocol is such that these calls can be established, but only via a more elaborate D-Bus API than normal (because more information is needed), then this method will return false.

In some older connection managers, supportsAudioCalls() and supportsVideoCalls() might both return false, even though supportsMediaCalls() returns true. This indicates that only an older API is supported - clients of these connection managers must call Account::ensureMediaCall() to get an empty call, then add audio and/or video streams to it.

Returns:
  `true` if Account::ensureAudioCall() can be expected to work, `false` otherwise.

See also:
  supportsMediaCalls(), supportsVideoCalls()

bool Tp::CapabilitiesBase::supportsVideoCalls | ( | bool | withAudio = `true` | ) | const

Return whether private video calls can be established by providing a contact identifier.

The same comments as for supportsAudioCalls() apply to this method.

Parameters:

  | withAudio | If true (the default), check for the ability to make calls with both audio and video; if false, do not require the ability to include an audio stream.

Returns:
  `true` if Account::ensureVideoCall() can be expected to work, if given the same withAudio parameter, `false` otherwise

See also:
  supportsMediaCalls(), supportsAudioCalls()

bool Tp::CapabilitiesBase::supportsUpgradingCalls | ( |  | ) | const

Return whether the protocol supports adding streams of a different type to ongoing media calls.

In some protocols and clients (such as XMPP Jingle), all calls potentially support both audio and video. This is indicated by returning true.

In other protocols and clients (such as MSN, and the variant of XMPP Jingle used by Google clients), the streams are fixed at the time the call is started, so if you will ever want video, you have to ask for it at the beginning, for instance with ensureVideoCall(). This is indicated by returning false.

User interfaces can use this method as a UI hint. If it returns false, then a UI wishing to support both audio and video calls will have to provide separate "audio call" and "video call" buttons or menu items; if it returns true, a single button that makes an audio call is sufficient, because video can be added later.

(The underlying Telepathy feature is the ImmutableStreams property; if this method returns true, then ImmutableStreams is false, and vice versa).

Returns:
  `true` if audio calls can be upgraded to audio + video, `false` otherwise.

void Tp::CapabilitiesBase::updateRequestableChannelClasses | ( | const RequestableChannelClassList & | classes | ) | `[protected, virtual]`