Tp::OutgoingStreamTubeChannel Class Reference

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

Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Tp::OutgoingStreamTubeChannel Class Reference
Channel proxies

The OutgoingStreamTubeChannel class represents an outgoing Telepathy channel of type StreamTube. More...

`#include <TelepathyQt/OutgoingStreamTubeChannel>`

Inherits Tp::StreamTubeChannel.

## Public Member Functions
virtual | ~OutgoingStreamTubeChannel ()
PendingOperation * | offerTcpSocket (const QHostAddress &address, quint16 port, const QVariantMap &parameters=QVariantMap())
PendingOperation * | offerTcpSocket (const QTcpServer *server, const QVariantMap &parameters=QVariantMap())
PendingOperation * | offerUnixSocket (const QString &socketAddress, const QVariantMap &parameters=QVariantMap(), bool requireCredentials=false)
PendingOperation * | offerUnixSocket (const QLocalServer *server, const QVariantMap &parameters=QVariantMap(), bool requireCredentials=false)
QHash< uint, Tp::ContactPtr > | contactsForConnections () const
QHash< QPair< QHostAddress, quint16 >, uint > | connectionsForSourceAddresses () const
QHash< uchar, uint > | connectionsForCredentials () const
Public Member Functions inherited from Tp::StreamTubeChannel
virtual | ~StreamTubeChannel ()
QString | service () const
bool | supportsIPv4SocketsOnLocalhost () const
bool | supportsIPv4SocketsWithSpecifiedAddress () const
bool | supportsIPv6SocketsOnLocalhost () const
bool | supportsIPv6SocketsWithSpecifiedAddress () const
bool | supportsUnixSocketsOnLocalhost () const
bool | supportsUnixSocketsWithCredentials () const
bool | supportsAbstractUnixSocketsOnLocalhost () const
bool | supportsAbstractUnixSocketsWithCredentials () const
QSet< uint > | connections () const
SocketAddressType | addressType () const
QPair< QHostAddress, quint16 > | ipAddress () const
QString | localAddress () const
Public Member Functions inherited from Tp::TubeChannel
virtual | ~TubeChannel ()
TubeChannelState | state () const
QVariantMap | parameters () const
Public Member Functions inherited from Tp::Channel
virtual | ~Channel ()
ConnectionPtr | connection () const
QVariantMap | immutableProperties () const
QString | channelType () const
HandleType | targetHandleType () const
uint | targetHandle () const
QString | targetId () const
ContactPtr | targetContact () const
bool | isRequested () const
ContactPtr | initiatorContact () const
PendingOperation * | requestClose ()
PendingOperation * | requestLeave (const QString &message=QString(), ChannelGroupChangeReason reason=ChannelGroupChangeReasonNone)
bool | isConference () const
Contacts | conferenceInitialInviteeContacts () const
QList< ChannelPtr > | conferenceChannels () const
QList< ChannelPtr > | conferenceInitialChannels () const
QHash< uint, ChannelPtr > | conferenceOriginalChannels () const
bool | supportsConferenceMerging () const
PendingOperation * | conferenceMergeChannel (const ChannelPtr &channel)
bool | supportsConferenceSplitting () const
PendingOperation * | conferenceSplitChannel ()
ChannelGroupFlags | groupFlags () const
bool | groupCanAddContacts () const
bool | groupCanAddContactsWithMessage () const
bool | groupCanAcceptContactsWithMessage () const
PendingOperation * | groupAddContacts (const QList< ContactPtr > &contacts, const QString &message=QString())
bool | groupCanRescindContacts () const
bool | groupCanRescindContactsWithMessage () const
bool | groupCanRemoveContacts () const
bool | groupCanRemoveContactsWithMessage () const
bool | groupCanRejectContactsWithMessage () const
bool | groupCanDepartWithMessage () const
PendingOperation * | groupRemoveContacts (const QList< ContactPtr > &contacts, const QString &message=QString(), ChannelGroupChangeReason reason=ChannelGroupChangeReasonNone)
Contacts | groupContacts (bool includeSelfContact=true) const
Contacts | groupLocalPendingContacts (bool includeSelfContact=true) const
Contacts | groupRemotePendingContacts (bool includeSelfContact=true) const
GroupMemberChangeDetails | groupLocalPendingContactChangeInfo (const ContactPtr &contact) const
GroupMemberChangeDetails | groupSelfContactRemoveInfo () const
bool | groupAreHandleOwnersAvailable () const
HandleOwnerMap | groupHandleOwners () const
bool | groupIsSelfContactTracked () const
ContactPtr | groupSelfContact () const
Public Member Functions inherited from Tp::StatefulDBusProxy
| StatefulDBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~StatefulDBusProxy ()
Public Member Functions inherited from Tp::DBusProxy
| DBusProxy (const QDBusConnection &dbusConnection, const QString &busName, const QString &objectPath, const Feature &featureCore)
virtual | ~DBusProxy ()
QDBusConnection | dbusConnection () const
QString | busName () const
QString | objectPath () const
bool | isValid () const
QString | invalidationReason () const
QString | invalidationMessage () const
Public Member Functions inherited from Tp::Object
virtual | ~Object ()
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()
Public Member Functions inherited from Tp::ReadyObject
| ReadyObject (RefCounted *object, const Feature &featureCore)
| ReadyObject (DBusProxy *proxy, const Feature &featureCore)
virtual | ~ReadyObject ()
virtual bool | isReady (const Features &features=Features()) const
virtual PendingReady * | becomeReady (const Features &requestedFeatures=Features())
virtual Features | requestedFeatures () const
virtual Features | actualFeatures () const
virtual Features | missingFeatures () const
Public Member Functions inherited from Tp::OptionalInterfaceFactory< Channel >
| OptionalInterfaceFactory (Channel *this_)
| ~OptionalInterfaceFactory ()
QStringList | interfaces () const
bool | hasInterface (const QString &name) const
Interface * | optionalInterface (InterfaceSupportedChecking check=CheckInterfaceSupported) const
Interface * | interface () const

## Static Public Member Functions
static OutgoingStreamTubeChannelPtr | create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
Static Public Member Functions inherited from Tp::StreamTubeChannel
static StreamTubeChannelPtr | create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
Static Public Member Functions inherited from Tp::TubeChannel
static TubeChannelPtr | create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
Static Public Member Functions inherited from Tp::Channel
static ChannelPtr | create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)
Static Public Member Functions inherited from Tp::StatefulDBusProxy
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique)
static QString | uniqueNameFrom (const QDBusConnection &bus, const QString &wellKnownOrUnique, QString &error, QString &message)

## Static Public Attributes
static const Feature | FeatureCore
Static Public Attributes inherited from Tp::StreamTubeChannel
static const Feature | FeatureCore
static const Feature | FeatureConnectionMonitoring
Static Public Attributes inherited from Tp::TubeChannel
static const Feature | FeatureCore
Static Public Attributes inherited from Tp::Channel
static const Feature | FeatureCore
static const Feature | FeatureConferenceInitialInviteeContacts

## Protected Member Functions
| OutgoingStreamTubeChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature=OutgoingStreamTubeChannel::FeatureCore)
Protected Member Functions inherited from Tp::StreamTubeChannel
| StreamTubeChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature=StreamTubeChannel::FeatureCore)
void | addConnection (uint connection)
void | removeConnection (uint connection, const QString &error, const QString &message)
void | setAddressType (SocketAddressType type)
SocketAccessControl | accessControl () const
void | setAccessControl (SocketAccessControl accessControl)
void | setIpAddress (const QPair< QHostAddress, quint16 > &address)
void | setLocalAddress (const QString &address)
bool | isDroppingConnections () const
Protected Member Functions inherited from Tp::TubeChannel
| TubeChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature=TubeChannel::FeatureCore)
void | setParameters (const QVariantMap &parameters)
Protected Member Functions inherited from Tp::Channel
| Channel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature)
Client::ChannelInterface * | baseInterface () const
bool | groupSelfHandleIsLocalPending () const
Protected Member Functions inherited from Tp::DBusProxy
void | setBusName (const QString &busName)
void | invalidate (const QString &reason, const QString &message)
void | invalidate (const QDBusError &error)
Protected Member Functions inherited from Tp::Object
| Object ()
void | notify (const char *propertyName)
Protected Member Functions inherited from Tp::ReadyObject
ReadinessHelper * | readinessHelper () const
Protected Member Functions inherited from Tp::OptionalInterfaceFactory< Channel >
void | setInterfaces (const QStringList &interfaces)

## Additional Inherited Members
Public Types inherited from Tp::OptionalInterfaceFactory< Channel >
enum | InterfaceSupportedChecking
Signals inherited from Tp::StreamTubeChannel
void | newConnection (uint connectionId)
void | connectionClosed (uint connectionId, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::TubeChannel
void | stateChanged (Tp::TubeChannelState state)
Signals inherited from Tp::Channel
void | groupFlagsChanged (Tp::ChannelGroupFlags flags, Tp::ChannelGroupFlags added, Tp::ChannelGroupFlags removed)
void | groupCanAddContactsChanged (bool canAddContacts)
void | groupCanRemoveContactsChanged (bool canRemoveContacts)
void | groupCanRescindContactsChanged (bool canRescindContacts)
void | groupMembersChanged (const Tp::Contacts &groupMembersAdded, const Tp::Contacts &groupLocalPendingMembersAdded, const Tp::Contacts &groupRemotePendingMembersAdded, const Tp::Contacts &groupMembersRemoved, const Tp::Channel::GroupMemberChangeDetails &details)
void | groupHandleOwnersChanged (const Tp::HandleOwnerMap &owners, const Tp::UIntList &added, const Tp::UIntList &removed)
void | groupSelfContactChanged ()
void | conferenceChannelMerged (const Tp::ChannelPtr &channel)
void | conferenceChannelRemoved (const Tp::ChannelPtr &channel, const Tp::Channel::GroupMemberChangeDetails &details)
Signals inherited from Tp::DBusProxy
void | invalidated (Tp::DBusProxy *proxy, const QString &errorName, const QString &errorMessage)
Signals inherited from Tp::Object
void | propertyChanged (const QString &propertyName)
Protected Slots inherited from Tp::Channel
PendingOperation * | groupAddSelfHandle ()

## Detailed Description

The OutgoingStreamTubeChannel class represents an outgoing Telepathy channel of type StreamTube.

Outgoing (locally initiated/requested) tubes are initially in the TubeChannelStateNotOffered state. The various offer methods in this class can be used to offer a local listening TCP or Unix socket for the tube's target to connect to, at which point the tube becomes TubeChannelStateRemotePending. If the target accepts the connection request, the state goes TubeChannelStateOpen and the connection manager will start tunneling any incoming connections from the recipient side to the local service.

## Constructor & Destructor Documentation

Tp::OutgoingStreamTubeChannel::~OutgoingStreamTubeChannel | ( |  | ) |
| virtual

Class destructor.

Tp::OutgoingStreamTubeChannel::OutgoingStreamTubeChannel | ( | const ConnectionPtr & | connection,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties,
|  | const Feature & | coreFeature = `OutgoingStreamTubeChannel::FeatureCore`
| ) |  |
| protected

Construct a new OutgoingStreamTubeChannel object.

Parameters

  connection | Connection owning this channel, and specifying the service.
  objectPath | The channel object path.
  immutableProperties | The channel immutable properties.
  coreFeature | The core feature of the channel type, if any. The corresponding introspectable should depend on OutgoingStreamTubeChannel::FeatureCore.

## Member Function Documentation

OutgoingStreamTubeChannelPtr Tp::OutgoingStreamTubeChannel::create | ( | const ConnectionPtr & | connection,
|  | const QString & | objectPath,
|  | const QVariantMap & | immutableProperties
| ) |  |
| static

Create a new OutgoingStreamTubeChannel object.

Parameters

  connection | Connection owning this channel, and specifying the service.
  objectPath | The channel object path.
  immutableProperties | The channel immutable properties.

Returns
  A OutgoingStreamTubeChannelPtr object pointing to the newly created OutgoingStreamTubeChannel object.

PendingOperation * Tp::OutgoingStreamTubeChannel::offerTcpSocket | ( | const QHostAddress & | address,
|  | quint16 | port,
|  | const QVariantMap & | parameters = `QVariantMap()`
| ) |  |

Offer a TCP socket over this stream tube.

This method offers a TCP socket over this tube. The socket's address is given as a QHostAddress and a numerical port in native byte order.

If your application uses QTcpServer as the local TCP server implementation, you can use the offerTcpSocket(const QTcpServer *, const QVariantMap &) overload instead to more easily pass the server's listen address.

It is guaranteed that when the PendingOperation returned by this method will be completed, the tube will be opened and ready to be used.

Connection managers adhering to the Telepathy specification should always support offering IPv4 TCP sockets. IPv6 sockets are only supported if supportsIPv6SocketsOnLocalhost() is `true`.

Note that the library will try to use SocketAccessControlPort access control whenever possible, as it allows to map connections to users based on their source addresses. If supportsIPv4SocketsWithSpecifiedAddress() or supportsIPv6SocketsWithSpecifiedAddress() for IPv4 and IPv6 sockets respectively is `false`, this feature is not available, and the connectionsForSourceAddresses() map won't contain useful distinct keys.

Arbitrary parameters can be associated with the offer to bootstrap legacy protocols; these will in particular be available as IncomingStreamTubeChannel::parameters() for a tube receiver implemented using TelepathyQt in the other end.

This method requires OutgoingStreamTubeChannel::FeatureCore to be ready.

Parameters

  address | A valid IPv4 or IPv6 address pointing to an existing socket.
  port | The port the socket is listening for connections to.
  parameters | A dictionary of arbitrary parameters to send with the tube offer.

Returns
  A PendingOperation which will emit PendingOperation::finished when the stream tube is ready to be used (hence in the TubeStateOpen state).

PendingOperation * Tp::OutgoingStreamTubeChannel::offerTcpSocket | ( | const QTcpServer * | server,
|  | const QVariantMap & | parameters = `QVariantMap()`
| ) |  |

Offer a TCP socket over this stream tube.

Otherwise identical to offerTcpSocket(const QHostAddress &, quint16, const QVariantMap &), but allows passing the local service's address in an already listening QTcpServer.

Parameters

  server | A valid QTcpServer, which should be already listening for incoming connections.
  parameters | A dictionary of arbitrary parameters to send with the tube offer.

Returns
  A PendingOperation which will emit PendingOperation::finished when the stream tube is ready to be used (hence in the TubeStateOpen state).

PendingOperation * Tp::OutgoingStreamTubeChannel::offerUnixSocket | ( | const QString & | socketAddress,
|  | const QVariantMap & | parameters = `QVariantMap()`,
|  | bool | requireCredentials = `false`
| ) |  |

Offer an Unix socket over this stream tube.

This method offers an Unix socket over this stream tube. The socket address is given as a a QString, which should contain the path to the socket. Abstract Unix sockets are also supported, and are given as addresses prefixed with a `NUL` byte.

If your application uses QLocalServer as the local Unix server implementation, you can use the offerUnixSocket(const QLocalServer *, const QVariantMap &, bool) overload instead to more easily pass the server's listen address.

Note that only connection managers for which supportsUnixSocketsOnLocalhost() or supportsAbstractUnixSocketsOnLocalhost() is `true` support exporting Unix sockets.

If supportsUnixSocketsWithCredentials() or supportsAbstractUnixSocketsWithCredentials(), as appropriate, returns `true`, the `requireCredentials` parameter can be set to `true` to make the connection manager pass an SCM_CREDS or SCM_CREDENTIALS message as supported by the platform when making a new connection. This enables preventing other local users from connecting to the service, but might not be possible to use with all protocols as the message is in-band in the data stream.

Arbitrary parameters can be associated with the offer to bootstrap legacy protocols; these will in particular be available as IncomingStreamTubeChannel::parameters() for a tube receiver implemented using TelepathyQt in the other end.

This method requires OutgoingStreamTubeChannel::FeatureCore to be ready.

Parameters

  socketAddress | A valid path to an existing Unix socket or abstract Unix socket.
  parameters | A dictionary of arbitrary parameters to send with the tube offer.
  requireCredentials | Whether the server requires a SCM_CREDS or SCM_CREDENTIALS message upon connection.

Returns
  A PendingOperation which will emit PendingOperation::finished when the stream tube is ready to be used (hence in the TubeStateOpen state).

PendingOperation * Tp::OutgoingStreamTubeChannel::offerUnixSocket | ( | const QLocalServer * | server,
|  | const QVariantMap & | parameters = `QVariantMap()`,
|  | bool | requireCredentials = `false`
| ) |  |

Offer an Unix socket over the tube.

Otherwise identical to offerUnixSocket(const QString &, const QVariantMap &, bool), but allows passing the local service's address as an already listening QLocalServer.

This method requires OutgoingStreamTubeChannel::FeatureCore to be ready.

Parameters

  server | A valid QLocalServer, which should be already listening for incoming connections.
  parameters | A dictionary of arbitrary parameters to send with the tube offer.
  requireCredentials | Whether the server should require a SCM_CRED or SCM_CREDENTIALS message upon connection.

Returns
  A PendingOperation which will emit PendingOperation::finished when the stream tube is ready to be used (hence in the TubeStateOpen state).

See Also
  StreamTubeChannel::supportsUnixSocketsOnLocalhost(), StreamTubeChannel::supportsUnixSocketsWithCredentials(), StreamTubeChannel::supportsAbstractUnixSocketsOnLocalhost(), StreamTubeChannel::supportsAbstractUnixSocketsWithCredentials()

QHash< uint, ContactPtr > Tp::OutgoingStreamTubeChannel::contactsForConnections | ( |  | ) | const

Return a map from connection ids to the associated contact.

Note that this function will only return valid data after the tube has been opened.

This method requires StreamTubeChannel::FeatureConnectionMonitoring to be ready.

Returns
  The map from connection ids to pointer to Contact objects.

See Also
  connectionsForSourceAddresses(), connectionsForCredentials(), StreamTubeChannel::addressType()

QHash< QPair< QHostAddress, quint16 >, uint > Tp::OutgoingStreamTubeChannel::connectionsForSourceAddresses | ( |  | ) | const

Return a map from a source address to the corresponding connections ids.

The connection ids retrieved here can be used to map a source address which connected to your socket to a connection ID (for error reporting) and further, to a contact (by using contactsForConnections()).

This method is only useful if a TCP socket was offered on this tube and the connection manager supports SocketAccessControlPort, which can be discovered using supportsIPv4SocketsWithSpecifiedAddress() and supportsIPv6SocketsWithSpecifiedAddress() for IPv4 and IPv6 sockets respectively.

Note that this function will only return valid data after the tube has been opened.

This method requires StreamTubeChannel::FeatureConnectionMonitoring to be ready.

Returns
  The map from source addresses as (QHostAddress, port in native byte order) pairs to the corresponding connection ids.

See Also
  connectionsForCredentials()

QHash< uchar, uint > Tp::OutgoingStreamTubeChannel::connectionsForCredentials | ( |  | ) | const

Return a map from a credential byte to the corresponding connections ids.

The connection ids retrieved here can be used to map a source address which connected to your socket to a connection ID (for error reporting) and further, to a contact (by using contactsForConnections()).

This method is only useful if this tube was offered using an Unix socket and passing credential bytes was enabled (`requireCredentials` == true).

Note that this function will only return valid data after the tube has been opened.

This method requires StreamTubeChannel::FeatureConnectionMonitoring to be ready.

Returns
  The map from credential bytes to the corresponding connection ids.

See Also
  connectionsForSourceAddresses()

## Member Data Documentation

const Feature Tp::OutgoingStreamTubeChannel::FeatureCore
| static

Feature representing the core that needs to become ready to make the OutgoingStreamTubeChannel object usable.

This is currently the same as StreamTubeChannel::FeatureCore, but may change to include more.

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