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

Channel Class Reference
[Channel proxies]

#include <TelepathyQt4/Channel>

Inherits Tp::StatefulDBusProxy, OptionalInterfaceFactory< Channel >, Tp::ReadyObject, and Tp::RefCounted.

Inherited by FileTransferChannel, RoomListChannel, StreamedMediaChannel, and TextChannel.

List of all members.

Classes

Signals

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Group interface

Cached access to state of the group interface on the associated remote object, if the interface is present. Almost all methods return undefined values if the list returned by interfaces() doesn't include TELEPATHY_INTERFACE_CHANNEL_INTERFACE_GROUP or if the object is not ready.

Some methods can be used when targetHandleType() == HandleTypeContact, such as groupFlags(), groupCanAddContacts(), groupCanRemoveContacts(), groupSelfContact() and groupContacts().

As the Group interface state can change freely during the lifetime of the group due to events like new contacts joining the group, the cached state is automatically kept in sync with the remote object's state by hooking to the change notification signals present in the D-Bus interface.

As the cached value changes, change notification signals are emitted.

There is a change notification signal <attribute>Changed corresponding to each cached attribute. The first parameter for each of these signals is the new value of the attribute, which is suited for displaying the value of the attribute in a widget in a model-view fashion. The remaining arguments depend on the attribute, but in general include at least the delta from the previous state of the attribute to the new state.

Check the individual signals' descriptions for details.

Optional interface proxy factory

Factory functions fabricating proxies for optional Channel interfaces and interfaces for specific channel types.

Detailed Description

High-level proxy object for accessing remote Telepathy Channel objects.

It adds the following features compared to using ChannelInterface directly:

The remote object state accessor functions on this object (interfaces(), channelType(), targetHandleType(), targetHandle(), requested(), initiatorContact(), etc) don't make any DBus calls; instead, they return 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. However, their value is not defined unless the object is ready, as returned by isReady(). becomeReady should be used to make sure channel is ready.

Additionally, the state of the Group interface on the remote object (if present) will be cached in the introspection process, and also tracked for any changes.

Each Channel is owned by a Connection. If the Connection becomes dead (as signaled by Connection::statusChanged(Disconnected)) or is deleted, the Channel object will transition to closed too.


Constructor & Destructor Documentation

~Channel (  )  [virtual]

Class destructor.

Channel ( const ConnectionPtr connection,
const QString &  objectPath,
const QVariantMap &  immutableProperties 
) [protected]

Construct a new Channel object.

Parameters:
connection Connection owning this Channel, and specifying the service.
objectPath Path to the object on the service.
immutableProperties The immutable properties of the channel, as signalled by NewChannels or returned by CreateChannel or EnsureChannel


Member Function Documentation

ChannelPtr create ( const ConnectionPtr connection,
const QString &  objectPath,
const QVariantMap &  immutableProperties 
) [static]

ConnectionPtr connection (  )  const

Return the owning Connection of the Channel.

Returns:
A pointer to the Connection object that owns this Channel.

QVariantMap immutableProperties (  )  const

Return the immutable properties of the channel.

If the channel is ready (isReady() returns true), the following keys are guaranteed to be present: org.freedesktop.Telepathy.Channel.ChannelType, org.freedesktop.Telepathy.Channel.TargetHandleType, org.freedesktop.Telepathy.Channel.TargetHandle and org.freedesktop.Telepathy.Channel.Requested.

The keys and values in this map are defined by the Telepathy D-Bus specification, or by third-party extensions to that specification. These are the properties that cannot change over the lifetime of the channel; they're announced in the result of the request, for efficiency.

Returns:
A map in which the keys are D-Bus property names and the values are the corresponding values.

QString channelType (  )  const

Return the type of this channel.

Returns:
D-Bus interface name for the type of the channel.

uint targetHandleType (  )  const

Return the type of the handle returned by targetHandle().

Returns:
The type of the handle, as specified in HandleType.

uint targetHandle (  )  const

Return the handle of the remote party with which this channel communicates.

Returns:
The handle, which is of the type targetHandleType() indicates.

bool isRequested (  )  const

Return whether this channel was created in response to a local request.

Note that the value is undefined until the channel is ready.

Returns:
true if this channel was created in response to a local request, false otherwise.

ContactPtr initiatorContact (  )  const

Return the contact who initiated the channel.

Note that the value is undefined until the channel is ready.

Returns:
A Contact object representing the contact who initiated the channel, or ContactPtr that points to null(0) if it can't be retrieved.

PendingOperation * requestClose (  ) 

Start an asynchronous request that the channel be closed. The returned PendingOperation object will signal the success or failure of this request; under normal circumstances, it can be expected to succeed.

Returns:
A PendingOperation, which will emit finished when the request finishes.

uint groupFlags (  )  const

Return a set of flags indicating the capabilities and behaviour of the group represented by the remote object.

Change notification is via groupFlagsChanged().

Returns:
Bitfield combination of flags, as defined in ChannelGroupFlag

bool groupCanAddContacts (  )  const

Return if contacts can be added or invited to this channel.

Returns:
true if contacts can be added, false otherwise.
See also:
groupAddContacts()

bool groupCanAddContactsWithMessage (  )  const

Return whether a message is expected when inviting contacts who are not already members to this channel.

Returns:
true if a message is expected, false otherwise.
See also:
groupAddContacts()

bool groupCanAcceptContactsWithMessage (  )  const

Return whether a message is expected when accepting contacts' requests to join this channel.

Returns:
true if a message is expected, false otherwise.
See also:
groupAddContacts()

PendingOperation * groupAddContacts ( const QList< ContactPtr > &  contacts,
const QString &  message = QString() 
)

Add contacts to this channel.

Contacts on the local pending list (those waiting for permission to join the channel) can always be added. If groupCanAcceptContactsWithMessage() returns true, an optional message is expected when doing this; if not, the message parameter is likely to be ignored (so the user should not be asked for a message, and the message parameter should be left empty).

Other contacts can only be added if groupCanAddContacts() returns true. If groupCanAddContactsWithMessage() returns true, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Parameters:
contacts Contacts to be added.
message A string message, which can be blank if desired.
Returns:
A PendingOperation which will emit PendingOperation::finished when the call has finished.
See also:
groupCanAddContacts()

bool groupCanRescindContacts (  )  const

Return whether contacts in groupRemotePendingContacts() can be removed from this channel (i.e. whether an invitation can be rescinded).

Returns:
true if contacts can be removed, false otherwise.
See also:
groupRemoveContacts()

bool groupCanRescindContactsWithMessage (  )  const

Return whether a message is expected when removing contacts who are in groupRemotePendingContacts() from this channel, i.e. rescinding an invitation.

Returns:
true if a message is expected, false otherwise.
See also:
groupRemoveContacts()

bool groupCanRemoveContacts (  )  const

Return if contacts in groupContacts() can be removed from this channel.

Note that contacts in local pending lists, and the groupSelfContact(), can always be removed from the channel.

Returns:
true if contacts can be removed, false otherwise.
See also:
groupRemoveContacts()

bool groupCanRemoveContactsWithMessage (  )  const

Return whether a message is expected when removing contacts who are in groupContacts() from this channel.

Returns:
true if a message is expected, false otherwise.
See also:
groupRemoveContacts()

bool groupCanRejectContactsWithMessage (  )  const

Return whether a message is expected when removing contacts who are in groupLocalPendingContacts() from this channel, i.e. rejecting a request to join.

Returns:
true if a message is expected, false otherwise.
See also:
groupRemoveContacts()

bool groupCanDepartWithMessage (  )  const

Return whether a message is expected when removing the groupSelfContact() from this channel, i.e. departing from the channel.

Returns:
true if a message is expected, false otherwise.
See also:
groupRemoveContacts()

PendingOperation * groupRemoveContacts ( const QList< ContactPtr > &  contacts,
const QString &  message = QString(),
uint  reason = ChannelGroupChangeReasonNone 
)

Remove contacts from this channel.

Contacts on the local pending list (those waiting for permission to join the channel) can always be removed. If groupCanRejectContactsWithMessage() returns true, an optional message is expected when doing this; if not, the message parameter is likely to be ignored (so the user should not be asked for a message, and the message parameter should be left empty).

The groupSelfContact() can also always be removed, as a way to leave the group with an optional departure message and/or departure reason indication. If groupCanDepartWithMessage() returns true, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Contacts in the group can only be removed (e.g. kicked) if groupCanRemoveContacts() returns true. If groupCanRemoveContactsWithMessage() returns true, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Contacts in the remote pending list (those who have been invited to the channel) can only be removed (have their invitations rescinded) if groupCanRescindContacts() returns true. If groupCanRescindContactsWithMessage() returns true, an optional message is expected when doing this, and if not, the message parameter is likely to be ignored.

Parameters:
contacts Contacts to be removed.
message A string message, which can be blank if desired.
reason Reason of the change, as specified in ChannelGroupChangeReason
Returns:
A PendingOperation which will emit PendingOperation::finished when the call has finished.
See also:
groupCanRemoveContacts()

Contacts groupContacts (  )  const

Return the current contacts of the group.

Returns:
List of contact objects.

Contacts groupLocalPendingContacts (  )  const

Return the contacts currently waiting for local approval to join the group.

Returns:
List of contacts.

Contacts groupRemotePendingContacts (  )  const

Return the contacts currently waiting for remote approval to join the group.

Returns:
List of contacts.

Channel::GroupMemberChangeDetails groupLocalPendingContactChangeInfo ( const ContactPtr contact  )  const

Return information of a local pending contact change. If no information is available, an object for which GroupMemberChangeDetails::isValid() returns false is returned.

Parameters:
contact A Contact object that is on the local pending contacts list.
Returns:
The change info in a GroupMemberChangeDetails object.

Channel::GroupMemberChangeDetails groupSelfContactRemoveInfo (  )  const

Return information on the removal of the local user from the group. If the user hasn't been removed from the group, an object for which GroupMemberChangeDetails::isValid() Return false is returned.

This method should be called only after the channel has been closed. This is useful for getting the remove information after missing the corresponding groupMembersChanged() signal, as the local user being removed usually causes the remote Channel to be closed.

The returned information is not guaranteed to be correct if groupIsSelfHandleTracked() Return false and a self handle change has occurred on the remote object.

Returns:
The remove info in a GroupMemberChangeDetails object.

bool groupAreHandleOwnersAvailable (  )  const

Return whether globally valid handles can be looked up using the channel-specific handle on this channel using this object.

Handle owner lookup is only available if:

If this function Return false, the return value of groupHandleOwners() is undefined and groupHandleOwnersChanged() will never be emitted.

The value returned by this function will stay fixed for the entire time the object is ready, so no change notification is provided.

Returns:
If handle owner lookup functionality is available.

HandleOwnerMap groupHandleOwners (  )  const

Return a mapping of handles specific to this channel to globally valid handles.

The mapping includes at least all of the channel-specific handles in this channel's members, local-pending and remote-pending sets as keys. Any handle not in the keys of this mapping is not channel-specific in this channel. Handles which are channel-specific, but for which the owner is unknown, appear in this mapping with 0 as owner.

Returns:
A mapping from group-specific handles to globally valid handles.

bool groupIsSelfContactTracked (  )  const

Return whether the value returned by groupSelfContact() is guaranteed to stay synchronized with what groupInterface()->GetSelfHandle() would return. Older services not providing group properties don't necessarily emit the SelfHandleChanged signal either, so self contact changes can't be reliably tracked.

Returns:
Whether or not changes to the self contact are tracked.

ContactPtr groupSelfContact (  )  const

Return a Contact object representing the user in the group if the user is a member of the group, otherwise either a Contact object representing the user or 0.

Returns:
A contact handle representing the user, if possible.

DBus::PropertiesInterface * propertiesInterface (  )  const [inline]

Convenience function for getting a Properties interface proxy. The Properties interface is not necessarily reported by the services, so a check parameter is not provided, and the interface is always assumed to be present.

Returns:
optionalInterface<DBus::PropertiesInterface>(BypassInterfaceCheck)

ChannelInterfaceCallStateInterface * callStateInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a CallState interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceCallStateInterface>(check)

ChannelInterfaceChatStateInterface * chatStateInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a ChatState interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceChatStateInterface>(check)

ChannelInterfaceDTMFInterface * DTMFInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a DTMF interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceDTMFInterface>(check)

ChannelInterfaceHoldInterface * holdInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a Hold interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceHoldInterface>(check)

ChannelInterfaceMediaSignallingInterface * mediaSignallingInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a MediaSignalling interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceMediaSignallingInterface>(check)

Client::ChannelInterfaceMessagesInterface* messagesInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

ChannelInterfacePasswordInterface * passwordInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a Password interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfacePasswordInterface>(check)

template< class Interface > Interface * typeInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Return a pointer to a valid instance of a given Channel type interface class, associated with the same remote object the Channel is associated with, and destroyed together with the Channel.

If the interface name returned by channelType() isn't equivalent to the name of the requested interface, or the Channel is not ready, 0 is returned. This check can be bypassed by specifying BypassInterfaceCheck for check, in which case a valid instance is always returned.

Convenience functions are provided for well-known channel types. However, there is no convenience getter for TypeContactList because the proxy for that interface doesn't actually have any functionality.

See also:
OptionalInterfaceFactory::interface
Template Parameters:
Interface Class of the optional interface to get.
Parameters:
check Should an instance be returned even if it can't be determined that the remote object is of the requested channel type.
Returns:
Pointer to an instance of the interface class, or 0.

ChannelTypeRoomListInterface * roomListInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a TypeRoomList interface proxy.

Parameters:
check Passed to typeInterface()
Returns:
typeInterface<ChannelTypeRoomListInterface>(check)

ChannelTypeStreamedMediaInterface * streamedMediaInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a TypeStreamedMedia interface proxy.

Parameters:
check Passed to typeInterface()
Returns:
typeInterface<ChannelTypeStreamedMediaInterface>(check)

ChannelTypeTextInterface * textInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a TypeText interface proxy.

Parameters:
check Passed to typeInterface()
Returns:
typeInterface<ChannelTypeTextInterface>(check)

ChannelTypeTubesInterface * tubesInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline]

Convenience function for getting a TypeTubes interface proxy.

Parameters:
check Passed to typeInterface()
Returns:
typeInterface<ChannelTypeTubesInterface>(check)

void groupFlagsChanged ( uint  flags,
uint  added,
uint  removed 
) [signal]

Emitted when the value returned by groupFlags() changes.

Parameters:
flags The value which would now be returned by groupFlags().
added Flags added compared to the previous value.
removed Flags removed compared to the previous value.

void groupCanAddContactsChanged ( bool  canAddContacts  )  [signal]

void groupCanRemoveContactsChanged ( bool  canRemoveContacts  )  [signal]

void groupCanRescindContactsChanged ( bool  canRescindContacts  )  [signal]

void groupMembersChanged ( const Tp::Contacts groupMembersAdded,
const Tp::Contacts groupLocalPendingMembersAdded,
const Tp::Contacts groupRemotePendingMembersAdded,
const Tp::Contacts groupMembersRemoved,
const Tp::Channel::GroupMemberChangeDetails details 
) [signal]

Emitted when the value returned by groupContacts(), groupLocalPendingContacts() or groupRemotePendingContacts() changes.

Parameters:
groupMembersAdded The contacts that were added to this channel.
groupLocalPendingMembersAdded The local pending contacts that were added to this channel.
groupRemotePendingMembersAdded The remote pending contacts that were added to this channel.
groupMembersRemoved The contacts removed from this channel.
details Additional details such as the contact requesting or causing the change.

void groupHandleOwnersChanged ( const Tp::HandleOwnerMap owners,
const Tp::UIntList added,
const Tp::UIntList removed 
) [signal]

Emitted when the value returned by groupHandleOwners() changes.

Parameters:
owners The value which would now be returned by groupHandleOwners().
added Handles which have been added to the mapping as keys, or existing handle keys for which the mapped-to value has changed.
removed Handles which have been removed from the mapping.

void groupSelfContactChanged (  )  [signal]

Emitted when the value returned by groupSelfContact() changes.

Client::ChannelInterface * baseInterface (  )  const [protected]

Get the ChannelInterface for this Channel class. This method is protected since the convenience methods provided by this class should always be used instead of the interface by users of the class.

Returns:
A pointer to the existing ChannelInterface for this Channel

ChannelInterfaceGroupInterface * groupInterface ( InterfaceSupportedChecking  check = CheckInterfaceSupported  )  const [inline, protected]

Convenience function for getting a Group interface proxy.

Parameters:
check Passed to optionalInterface()
Returns:
optionalInterface<ChannelInterfaceGroupInterface>(check)

bool groupSelfHandleIsLocalPending (  )  const [protected]

Return whether the local user is in the "local pending" state. This indicates that the local user needs to take action to accept an invitation, an incoming call, etc.

Returns:
Whether the local user is in this channel's local-pending set.

PendingOperation * groupAddSelfHandle (  )  [protected, slot]

Attempt to add the local user to this channel. In some channel types, such as Text and StreamedMedia, this is used to accept an invitation or an incoming call.

Returns:
A pending operation which will emit finished on success or failure


Member Data Documentation

const Feature FeatureCore [static]


Copyright © 2009 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.1.10