The IncomingStreamTubeChannel class represents an incoming Telepathy channel of type StreamTube. More...

#include <TelepathyQt4/IncomingStreamTubeChannel>

Inherits Tp::StreamTubeChannel.

Public Member Functions

virtual ~IncomingStreamTubeChannel ()
PendingStreamTubeConnection * acceptTubeAsTcpSocket ()
PendingStreamTubeConnection * acceptTubeAsTcpSocket (const QHostAddress &allowedAddress, quint16 allowedPort)
PendingStreamTubeConnection * acceptTubeAsUnixSocket (bool requireCredentials=false)
QPair< QHostAddress, quint16 > ipAddress () const
QString localAddress () const

Static Public Member Functions

static IncomingStreamTubeChannelPtr create (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties)

Static Public Attributes

static const Feature FeatureCore

Protected Member Functions

IncomingStreamTubeChannel (const ConnectionPtr &connection, const QString &objectPath, const QVariantMap &immutableProperties, const Feature &coreFeature=IncomingStreamTubeChannel::FeatureCore)

Detailed Description

The IncomingStreamTubeChannel class represents an incoming Telepathy channel of type StreamTube.

In particular, this class is meant to be used as a comfortable way for accepting incoming stream tubes. Tubes can be accepted as TCP and/or Unix sockets with various access control methods depending on what the service supports using the various overloads of acceptTubeAsTcpSocket() and acceptTubeAsUnixSocket().

Once a tube is successfully accepted and open (the PendingStreamTubeConnection returned from the accepting methods has finished), the application can connect to the socket the address of which can be retrieved from PendingStreamTubeConnection::ipAddress() and/or PendingStreamTubeConnection::localAddress() depending on which accepting method was used. Connecting to this socket will open a tunneled connection to the service listening at the offering end of the tube.

For more details, please refer to Telepathy specification.

See Asynchronous Object Model, Shared Pointer Usage

Constructor & Destructor Documentation

Tp::IncomingStreamTubeChannel::~IncomingStreamTubeChannel ( ) [virtual]

Class destructor.

Tp::IncomingStreamTubeChannel::IncomingStreamTubeChannel	(	const ConnectionPtr &	connection,
		const QString &	objectPath,
		const QVariantMap &	immutableProperties,
		const Feature &	coreFeature = `IncomingStreamTubeChannel::FeatureCore`
	)		`[protected]`

Construct a new IncomingStreamTubeChannel 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 IncomingStreamTubeChannel::FeatureCore.

Member Function Documentation

IncomingStreamTubeChannelPtr Tp::IncomingStreamTubeChannel::create	(	const ConnectionPtr &	connection,
		const QString &	objectPath,
		const QVariantMap &	immutableProperties
	)		`[static]`

Create a new IncomingStreamTubeChannel object.

Parameters:

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

Returns:: A IncomingStreamTubeChannelPtr object pointing to the newly created IncomingStreamTubeChannel object.

Reimplemented from Tp::StreamTubeChannel.

PendingStreamTubeConnection * Tp::IncomingStreamTubeChannel::acceptTubeAsTcpSocket ( )

Accept an incoming stream tube as a TCP socket.

This method accepts an incoming connection request for a stream tube. It can be called only if the tube is in the TubeStateLocalPending state.

The connection manager will open a TCP socket for the application to connect to. The address of the socket will be returned in PendingStreamTubeConnection::ipAddress() once the operation has finished successfully.

Using this overload, the connection manager will accept every incoming connection from localhost.

This accept method must be supported by all connection managers adhering to the Telepathy specification.

This method requires IncomingStreamTubeChannel::FeatureCore to be ready.

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

PendingStreamTubeConnection * Tp::IncomingStreamTubeChannel::acceptTubeAsTcpSocket	(	const QHostAddress &	allowedAddress,
		quint16	allowedPort
	)

Accept an incoming stream tube as a TCP socket.

This method accepts an incoming connection request for a stream tube. It can be called only if the tube is in the TubeStateLocalPending state.

The connection manager will open a TCP socket for the application to connect to. The address of the socket will be returned in PendingStreamTubeConnection::ipAddress() once the operation has finished successfully.

This overload lets you specify an allowed address/port combination for connecting to the CM socket. Connections with other source addresses won't be accepted. The accessors supportsIPv4SocketsWithSpecifiedAddress() and supportsIPv6SocketsWithSpecifiedAddress() can be used to verify that the connection manager supports this kind of access control; otherwise, this method will always fail unless QHostAddress::Any or QHostAddress::AnyIPv6 is passed, in which case the behavior is identical to the always supported acceptTubeAsTcpSocket() overload.

Note that when using QHostAddress::Any or QHostAddress::AnyIPv6, allowedPort is ignored.

This method requires IncomingStreamTubeChannel::FeatureCore to be ready.

Parameters:

allowedAddress	An allowed address for connecting to the socket.
allowedPort	An allowed port for connecting to the socket.

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

PendingStreamTubeConnection * Tp::IncomingStreamTubeChannel::acceptTubeAsUnixSocket ( bool requireCredentials = false )

Accept an incoming stream tube as a Unix socket.

This method accepts an incoming connection request for a stream tube. It can be called only if the tube is in the TubeStateLocalPending state.

An Unix socket (can be used with QLocalSocket or alike) will be opened by the connection manager as the local tube endpoint. This is only supported if supportsUnixSocketsOnLocalhost() is true.

You can also specify whether the CM should require an SCM_CREDS or SCM_CREDENTIALS message upon connection instead of accepting every incoming connection from localhost. This provides additional security, but requires sending the byte retrieved from PendingStreamTubeConnection::credentialByte() in-line in the socket byte stream (in a credentials message if available on the platform), which might not be compatible with all protocols or libraries. Also, only connection managers for which supportsUnixSocketsWithCredentials() is true support this type of access control.

This method requires IncomingStreamTubeChannel::FeatureCore to be ready.

Parameters:

requireCredentials Whether the CM should require an SCM_CREDS or SCM_CREDENTIALS message upon connection.

Returns:: A PendingStreamTubeConnection which will emit PendingStreamTubeConnection::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()

QPair< QHostAddress, quint16 > Tp::IncomingStreamTubeChannel::ipAddress ( ) const

Return the IP address/port combination of the opened stream tube.

Calling this method when the tube has not been opened will cause it to return an undefined value. The same will happen if the tube has been accepted as an Unix socket. Use localAddress() if that is the case.

Returns:: Pair of IP address as QHostAddress and port if using a TCP socket, or an undefined value otherwise.

See also:: acceptTubeAsTcpSocket(), localAddress()

Reimplemented from Tp::StreamTubeChannel.

QString Tp::IncomingStreamTubeChannel::localAddress ( ) const

Return the local address of the opened stream tube.

Calling this method when the tube has not been opened will cause it to return an undefined value. The same will happen if the tube has been accepted as a TCP socket. Use ipAddress() if that is the case.

Returns:: Unix socket address if using an Unix socket, or an undefined value otherwise.

See also:: acceptTubeAsUnixSocket(), ipAddress()

Reimplemented from Tp::StreamTubeChannel.

Member Data Documentation

const Feature Tp::IncomingStreamTubeChannel::FeatureCore [static]

Feature representing the core that needs to become ready to make the IncomingStreamTubeChannel 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.

Reimplemented from Tp::StreamTubeChannel.