Tp::StreamTubeServer Class Reference

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

Classes | Signals | Public Member Functions | Static Public Member Functions | List of all members
Tp::StreamTubeServer Class Reference

The StreamTubeServer class is a Handler implementation for outgoing Stream Tube channels, allowing an application to easily export a TCP network server over Telepathy Tubes without worrying about the channel dispatching details. More...

`#include <TelepathyQt/StreamTubeServer>`

Inherits QObject, and Tp::RefCounted.

## Classes
class | ParametersGenerator
| The StreamTubeServer::ParametersGenerator abstract interface allows sending a different set of parameters with each tube offer. More...
class | RemoteContact
| The StreamTubeServer::RemoteContact class represents a contact from which a socket connection to our exported socket originates. More...
class | Tube
| The StreamTubeServer::Tube class represents a tube being handled by the server. More...

## Signals
void | tubeRequested (const Tp::AccountPtr &account, const Tp::OutgoingStreamTubeChannelPtr &tube, const QDateTime &userActionTime, const Tp::ChannelRequestHints &hints)
void | tubeClosed (const Tp::AccountPtr &account, const Tp::OutgoingStreamTubeChannelPtr &tube, const QString &error, const QString &message)
void | newTcpConnection (const QHostAddress &sourceAddress, quint16 sourcePort, const Tp::AccountPtr &account, const Tp::ContactPtr &contact, const Tp::OutgoingStreamTubeChannelPtr &tube)
void | tcpConnectionClosed (const QHostAddress &sourceAddress, quint16 sourcePort, const Tp::AccountPtr &account, const Tp::ContactPtr &contact, const QString &error, const QString &message, const Tp::OutgoingStreamTubeChannelPtr &tube)

## Public Member Functions
virtual | ~StreamTubeServer ()
ClientRegistrarPtr | registrar () const
QString | clientName () const
bool | isRegistered () const
bool | monitorsConnections () const
QPair< QHostAddress, quint16 > | exportedTcpSocketAddress () const
QVariantMap | exportedParameters () const
void | exportTcpSocket (const QHostAddress &address, quint16 port, const QVariantMap &parameters=QVariantMap())
void | exportTcpSocket (const QTcpServer *server, const QVariantMap &parameters=QVariantMap())
void | exportTcpSocket (const QHostAddress &address, quint16 port, ParametersGenerator *generator)
void | exportTcpSocket (const QTcpServer *server, ParametersGenerator *generator)
QList< Tube > | tubes () const
QHash< QPair< QHostAddress, quint16 >, RemoteContact > | tcpConnections () const
Public Member Functions inherited from Tp::RefCounted
| RefCounted ()
virtual | ~RefCounted ()

## Static Public Member Functions
static StreamTubeServerPtr | create (const QStringList &p2pServices, const QStringList &roomServices=QStringList(), const QString &clientName=QString(), bool monitorConnections=false, const AccountFactoryConstPtr &accountFactory=AccountFactory::create(QDBusConnection::sessionBus()), const ConnectionFactoryConstPtr &connectionFactory=ConnectionFactory::create(QDBusConnection::sessionBus()), const ChannelFactoryConstPtr &channelFactory=ChannelFactory::create(QDBusConnection::sessionBus()), const ContactFactoryConstPtr &contactFactory=ContactFactory::create())
static StreamTubeServerPtr | create (const QDBusConnection &bus, const AccountFactoryConstPtr &accountFactory, const ConnectionFactoryConstPtr &connectionFactory, const ChannelFactoryConstPtr &channelFactory, const ContactFactoryConstPtr &contactFactory, const QStringList &p2pServices, const QStringList &roomServices=QStringList(), const QString &clientName=QString(), bool monitorConnections=false)
static StreamTubeServerPtr | create (const AccountManagerPtr &accountManager, const QStringList &p2pServices, const QStringList &roomServices=QStringList(), const QString &clientName=QString(), bool monitorConnections=false)
static StreamTubeServerPtr | create (const ClientRegistrarPtr &registrar, const QStringList &p2pServices, const QStringList &roomServices=QStringList(), const QString &clientName=QString(), bool monitorConnections=false)

## Detailed Description

The StreamTubeServer class is a Handler implementation for outgoing Stream Tube channels, allowing an application to easily export a TCP network server over Telepathy Tubes without worrying about the channel dispatching details.

Telepathy Tubes is a technology for connecting arbitrary applications together through the IM network (and sometimes with direct peer-to-peer connections), such that issues like firewall/NAT traversal are automatically handled. Stream Tubes in particular offer properties similar to SOCK_STREAM sockets. The StreamTubeServer class exports such a bytestream socket server over the tubes it handles as a Telepathy Handler Client; the StreamTubeClient class is the counterpart, enabling TCP/UNIX socket clients to connect to services from such exported servers offered to them via tubes.

Both peer-to-peer (`TargetHandleType` == HandleTypeContact) and group (`TargetHandleType` == HandleTypeRoom) channels are supported, and it's possible to specify the tube services to handle for each separately. It is also possible to not advertise handling capability for ANY tube service; instead just using the StreamTubeServer to handle tubes on an one-off basis by passing its corresponding Client service name as the preferredHandler when requesting tubes via the Account::createStreamTube() methods (or equivalent).

Connection monitoring allows associating incoming connections on the exported server socket with the corresponding remote contacts. This allows an application to show the details of and/or initiate further communication with the remote contacts, without considering the actual tube channels the connections are being made through at all (in particular, their Channel::targetContact() accessor for peer-to-peer and the OutgoingStreamTubeChannel::connectionsForSourceAddresses() accessor for group tubes).

Enabling connection monitoring adds a small overhead and latency to handling each incoming tube and signaling each new incoming connection over them, though, so use it only when needed. Additionally, some protocol backends or environments they're running in might not support the SocketAccessControlPort mechanism, in which case the source address won't be reported for connections through them. Even in this case, the remote contacts can be associated by accepting one incoming socket connection at a time, and waiting for the corresponding contact to be signaled (although its source address will be invalid, it's the only possibility given its the only accepted connection). However, it's not necessary to do this e.g. with the Gabble XMPP backend, because it fully supports the required mechanism.

A service activated Handler can be implemented using StreamTubeServer by passing a predefined clientName manually to the chosen create() method, and installing Telepathy ``.client and D-Bus ``.service files declaring the implemented tube services as channel classes and a path to the executable. If this is not needed, the clientName can be omitted, in which case a random unique client name is generated and used instead.

StreamTubeServer shares Account, Connection and Channel proxies and Contact objects with the rest of the application as long as a reference to the AccountManager, ClientRegistrar, or the factories used elsewhere is passed to the create() method. A stand-alone tube service Handler can get away without passing these however, or just passing select factories to make the desired features prepared and subclasses employed for these objects for their own convenience.

Whichever method is used, the ChannelFactory (perhaps indirectly) given must construct OutgoingStreamTubeChannel instances or subclasses thereof for all channel classes corresponding to the tube services to handle. This is the default; overriding it without obeying these constraints using ChannelFactory::setSubclassForOutgoingStreamTubes() or the related methods for room tubes prevents StreamTubeServer from operating correctly.

Todo:

  Coin up a small Python script or alike to easily generate the .client and .service files. (fd.o #41614)

  Support exporting Unix sockets as well. (fd.o #41615)

## Constructor & Destructor Documentation

Tp::StreamTubeServer::~StreamTubeServer | ( |  | ) |
| virtual

Class destructor.

## Member Function Documentation

StreamTubeServerPtr Tp::StreamTubeServer::create | ( | const QStringList & | p2pServices,
|  | const QStringList & | roomServices = `QStringList()`,
|  | const QString & | clientName = `QString()`,
|  | bool | monitorConnections = `false`,
|  | const AccountFactoryConstPtr & | accountFactory = `AccountFactory::create(QDBusConnection::sessionBus())`,
|  | const ConnectionFactoryConstPtr & | connectionFactory = `ConnectionFactory::create(QDBusConnection::sessionBus())`,
|  | const ChannelFactoryConstPtr & | channelFactory = `ChannelFactory::create(QDBusConnection::sessionBus())`,
|  | const ContactFactoryConstPtr & | contactFactory = `ContactFactory::create()`
| ) |  |
| static

Create a new StreamTubeServer, which will register itself on the session bus using an internal ClientRegistrar and use the given factories.

Parameters

  p2pServices | Names of the tube services to handle on peer-to-peer tube channels.
  roomServices | Names of the tube services to handle on room/group tube channels.
  clientName | The client name (without the `org.freedesktop.Telepathy.Client`. prefix).
  monitorConnections | Whether to enable connection monitoring or not.
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.

StreamTubeServerPtr Tp::StreamTubeServer::create | ( | const QDBusConnection & | bus,
|  | const AccountFactoryConstPtr & | accountFactory,
|  | const ConnectionFactoryConstPtr & | connectionFactory,
|  | const ChannelFactoryConstPtr & | channelFactory,
|  | const ContactFactoryConstPtr & | contactFactory,
|  | const QStringList & | p2pServices,
|  | const QStringList & | roomServices = `QStringList()`,
|  | const QString & | clientName = `QString()`,
|  | bool | monitorConnections = `false`
| ) |  |
| static

Create a new StreamTubeServer, which will register itself on the given bus using an internal ClientRegistrar and use the given factories.

The factories must all be created for the given bus.

Parameters

  bus | Connection to the bus to register on.
  accountFactory | The account factory to use.
  connectionFactory | The connection factory to use.
  channelFactory | The channel factory to use.
  contactFactory | The contact factory to use.
  p2pServices | Names of the tube services to handle on peer-to-peer tube channels.
  roomServices | Names of the tube services to handle on room/group tube channels.
  clientName | The client name (without the `org.freedesktop.Telepathy.Client`. prefix).
  monitorConnections | Whether to enable connection monitoring or not.

StreamTubeServerPtr Tp::StreamTubeServer::create | ( | const AccountManagerPtr & | accountManager,
|  | const QStringList & | p2pServices,
|  | const QStringList & | roomServices = `QStringList()`,
|  | const QString & | clientName = `QString()`,
|  | bool | monitorConnections = `false`
| ) |  |
| static

Create a new StreamTubeServer, which will register itself on the bus of and share objects with the given accountManager, creating an internal ClientRegistrar.

Parameters

  accountManager | A pointer to the account manager to link up with.
  p2pServices | Names of the tube services to handle on peer-to-peer tube channels.
  roomServices | Names of the tube services to handle on room/group tube channels.
  clientName | The client name (without the `org.freedesktop.Telepathy.Client`. prefix).
  monitorConnections | Whether to enable connection monitoring or not.

StreamTubeServerPtr Tp::StreamTubeServer::create | ( | const ClientRegistrarPtr & | registrar,
|  | const QStringList & | p2pServices,
|  | const QStringList & | roomServices = `QStringList()`,
|  | const QString & | clientName = `QString()`,
|  | bool | monitorConnections = `false`
| ) |  |
| static

Create a new StreamTubeServer, which will register itself on the bus of and using the given client registrar, and share objects with it.

Parameters

  registrar | The client registrar to use.
  p2pServices | Names of the tube services to handle on peer-to-peer tube channels.
  roomServices | Names of the tube services to handle on room/group tube channels.
  clientName | The client name (without the `org.freedesktop.Telepathy.Client`. prefix).
  monitorConnections | Whether to enable connection monitoring or not.

ClientRegistrarPtr Tp::StreamTubeServer::registrar | ( |  | ) | const

Return the client registrar used by the server to register itself as a Handler client.

This is the registrar originally passed to create(const ClientRegistrarPtr &, const QStringList &, const QStringList &, const QString &, bool) if that was used, and an internally constructed one otherwise. In any case, it can be used to e.g. register further clients like any other ClientRegistrar.

Returns
  A pointer to the registrar.

QString Tp::StreamTubeServer::clientName | ( |  | ) | const

Return the Telepathy Client name of the server.

Returns
  The name, without the `org.freedesktop.Telepathy.Client`. prefix of the full D-Bus service name.

bool Tp::StreamTubeServer::isRegistered | ( |  | ) | const

Return whether the server has been successfully registered or not.

Registration is attempted, at the latest, when a socket is first exported using exportTcpSocket(). It can fail e.g. because the connection to the bus has failed, or a predefined clientName has been passed to create(), and a Client with the same name is already registered. Typically, failure registering would be a fatal error for a stand-alone tube handler, but only a warning event for an application serving other purposes. In any case, a high-quality user of the API will check the return value of this accessor after exporting their socket.

Returns
  `true` if the server has been successfully registered, `false` if not.

bool Tp::StreamTubeServer::monitorsConnections | ( |  | ) | const

Return whether connection monitoring is enabled on this server.

For technical reasons, connection monitoring can't be enabled when the server is already running, so there is no corresponding setter method. It has to be enabled by passing `true` as the monitorConnections parameter to the create() method.

If connection monitoring isn't enabled, newTcpConnection() and tcpConnectionClosed() won't be emitted and tcpConnections() won't be populated.

Returns
  `true` if monitoring is enabled, `false` if not.

QPair< QHostAddress, quint16 > Tp::StreamTubeServer::exportedTcpSocketAddress | ( |  | ) | const

Return the host address and port of the currently exported TCP socket, if any.

QHostAddress::Null is reported as the address and 0 as the port if no TCP socket has yet been successfully exported.

Returns
  The host address and port values in a pair structure.

QVariantMap Tp::StreamTubeServer::exportedParameters | ( |  | ) | const

Return the fixed parameters, if any, which are sent along when offering the exported socket on all handled tubes.

To prevent accidentally leaving the current parameters to be sent when offering a different socket, or vice versa, the parameters can only be set together with the socket using exportTcpSocket(). Parameters often contain sensitive information such as session identifiers or authentication credentials, which could then be used to maliciously access the service listening on the other socket.

If a custom dynamic ParametersGenerator was passed to exportTcpSocket() instead of a set of fixed parameters, an empty set of parameters is returned.

Returns
  The parameters in a string-variant map.

void Tp::StreamTubeServer::exportTcpSocket | ( | const QHostAddress & | address,
|  | quint16 | port,
|  | const QVariantMap & | parameters = `QVariantMap()`
| ) |  |

Set the server to offer the socket listening at the given (address, port) combination as the local endpoint of tubes handled in the future.

A fixed set of protocol bootstrapping parameters can optionally be set to be sent along with all tube offers until the next call to exportTcpSocket(). See the ParametersGenerator documentation for an in-depth description of the parameter transfer mechanism, and a more flexible way to vary the parameters between each handled tube.

The handler is registered on the bus at the latest when this method or another exportTcpSocket() overload is called for the first time, so one should check the return value of isRegistered() at that point to verify that was successful.

Parameters

  address | The listen address of the socket.
  port | The port of the socket.
  parameters | The bootstrapping parameters in a string-value map.

void Tp::StreamTubeServer::exportTcpSocket | ( | const QTcpServer * | server,
|  | const QVariantMap & | parameters = `QVariantMap()`
| ) |  |

Set the StreamTubeServer to offer the already listening TCP server as the local endpoint of tubes handled in the future.

This is just a convenience wrapper around exportTcpSocket(const QHostAddress &, quint16, const QVariantMap &) to be used when the TCP server code is implemented using the QtNetwork facilities.

A fixed set of protocol bootstrapping parameters can optionally be set to be sent along with all tube offers until the next call to exportTcpSocket(). See the ParametersGenerator documentation for an in-depth description of the parameter transfer mechanism, and a more flexible way to vary the parameters between each handled tube.

Parameters

  server | A pointer to the TCP server.
  parameters | The bootstrapping parameters in a string-value map.

void Tp::StreamTubeServer::exportTcpSocket | ( | const QHostAddress & | address,
|  | quint16 | port,
|  | ParametersGenerator * | generator
| ) |  |

Set the server to offer the socket listening at the given address - port combination as the local endpoint of tubes handled in the future, sending the parameters from the given generator along with the offers.

The handler is registered on the bus at the latest when this method or another exportTcpSocket() overload is called for the first time, so one should check the return value of isRegistered() at that point to verify that was successful.

Parameters

  address | The listen address of the socket.
  port | The port of the socket.
  generator | A pointer to the bootstrapping parameters generator.

void Tp::StreamTubeServer::exportTcpSocket | ( | const QTcpServer * | server,
|  | ParametersGenerator * | generator
| ) |  |

Set the server to offer the already listening TCP server as the local endpoint of tubes handled in the future, sending the parameters from the given generator along with the offers.

This is just a convenience wrapper around exportTcpSocket(const QHostAddress &, quint16, ParametersGenerator *) to be used when the TCP server code is implemented using the QtNetwork facilities.

Parameters

  server | A pointer to the TCP server.
  generator | A pointer to the bootstrapping parameters generator.

QList< StreamTubeServer::Tube > Tp::StreamTubeServer::tubes | ( |  | ) | const

Return the tubes currently handled by the server.

Returns
  A list of Tube structures containing pointers to the account and tube channel for each tube.

QHash< QPair< QHostAddress, quint16 >, StreamTubeServer::RemoteContact > Tp::StreamTubeServer::tcpConnections | ( |  | ) | const

Return the ongoing TCP connections over tubes handled by this server.

The returned mapping has the connection source addresses as keys and the contacts along with the accounts which can be used to reach them as values. Connections through protocol backends which don't support SocketAccessControlPort will be included as the potentially many values for the null source address key, the pair (`QHostAddress::Null`, 0).

This is effectively a state recovery accessor corresponding to the change notification signals newTcpConnection() and tcpConnectionClosed().

The mapping is only populated if connection monitoring was requested when creating the server (so monitorsConnections() returns `true`).

Returns
  The connections in a mapping with pairs of their source host addresses and ports as keys and structures containing pointers to the account and remote contacts they're from as values.

void Tp::StreamTubeServer::tubeRequested | ( | const Tp::AccountPtr & | account,
|  | const Tp::OutgoingStreamTubeChannelPtr & | tube,
|  | const QDateTime & | userActionTime,
|  | const Tp::ChannelRequestHints & | hints
| ) |  |
| signal

Emitted when a tube has been requested for one of our services, and we've began handling it.

This is emitted before invoking the ParametersGenerator, if any, for the tube.

Parameters

  account | A pointer to the account from which the tube was requested from.
  tube | A pointer to the actual tube channel.
  userActionTime | The time the request occurred at, if it was an user action. Should be used for focus stealing prevention.
  hints | The hints passed to the request, if any.

void Tp::StreamTubeServer::tubeClosed | ( | const Tp::AccountPtr & | account,
|  | const Tp::OutgoingStreamTubeChannelPtr & | tube,
|  | const QString & | error,
|  | const QString & | message
| ) |  |
| signal

Emitted when a tube we've been handling (previously announced with tubeRequested()) has encountered an error or has otherwise been closed from further communication.

Parameters

  account | A pointer to the account from which the tube was requested from.
  tube | A pointer to the actual tube channel.
  error | The D-Bus error name corresponding to the reason for the closure.
  message | A freeform debug message associated with the error.

void Tp::StreamTubeServer::newTcpConnection | ( | const QHostAddress & | sourceAddress,
|  | quint16 | sourcePort,
|  | const Tp::AccountPtr & | account,
|  | const Tp::ContactPtr & | contact,
|  | const Tp::OutgoingStreamTubeChannelPtr & | tube
| ) |  |
| signal

Emitted when we have picked up a new TCP connection to the (current or previous) exported server socket. This can be used to associate connections the protocol backend relays to the exported socket with the remote contact who originally initiated them in the other end of the tube.

This is only emitted if connection monitoring was enabled when creating the StreamTubeServer. Additionally, if the protocol backend the connection is from doesn't support the SocketAccessControlPort mechanism, the source address and port will always be invalid.

Parameters

  sourceAddress | The source address of the connection, or QHostAddress::Null if it can't be resolved.
  sourcePort | The source port of the connection, or 0 if it can't be resolved.
  account | A pointer to the account through which the remote contact can be reached.
  contact | A pointer to the remote contact object.
  tube | A pointer to the tube channel through which the connection has been made.

void Tp::StreamTubeServer::tcpConnectionClosed | ( | const QHostAddress & | sourceAddress,
|  | quint16 | sourcePort,
|  | const Tp::AccountPtr & | account,
|  | const Tp::ContactPtr & | contact,
|  | const QString & | error,
|  | const QString & | message,
|  | const Tp::OutgoingStreamTubeChannelPtr & | tube
| ) |  |
| signal

Emitted when a TCP connection (previously announced with newTcpConnection()) through one of our handled tubes has been closed due to an error or by a graceful disconnect (in which case the error is TP_QT_ERROR_DISCONNECTED).

This is only emitted if connection monitoring was enabled when creating the StreamTubeServer. Additionally, if the protocol backend the connection is from doesn't support the SocketAccessControlPort mechanism, the source address and port will always be invalid.

Parameters

  sourceAddress | The source address of the connection, or QHostAddress::Null if it couldn't be resolved.
  sourcePort | The source port of the connection, or 0 if it couldn't be resolved.
  account | A pointer to the account through which the remote contact can be reached.
  contact | A pointer to the remote contact object.
  error | The D-Bus error name corresponding to the reason for the closure.
  message | A freeform debug message associated with the error.
  tube | A pointer to the tube channel through which the connection has been made.