Tp::OutgoingStreamTubeChannel Class Reference [Channel proxies]

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

#include <TelepathyQt4/OutgoingStreamTubeChannel>

Inherits Tp::StreamTubeChannel.

List of all members.

Public Member Functions

• virtual ~OutgoingStreamTubeChannel ()
• PendingOperation * offerTcpSocket (const QHostAddress &address, quint16 port, const QVariantMap &parameters)
• PendingOperation * offerTcpSocket (const QTcpServer *server, const QVariantMap &parameters)
• PendingOperation * offerUnixSocket (const QString &socketAddress, const QVariantMap &parameters, bool requireCredentials=false)
• PendingOperation * offerUnixSocket (const QLocalServer *server, const QVariantMap &parameters, bool requireCredentials=false)
• QHash< uint, Tp::ContactPtr > contactsForConnections () const
• QHash< QPair< QHostAddress,
  quint16 >, uint > connectionsForSourceAddresses () const
• QHash< uchar, uint > connectionsForCredentials () const

Static Public Member Functions

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

Static Public Attributes

• static const Feature FeatureCore

Protected Member Functions

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

---

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.

Reimplemented from Tp::StreamTubeChannel.

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

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 TelepathyQt4 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
	)

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,
		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 TelepathyQt4 in the other end.

This method requires OutgoingStreamTubeChannel::FeatureCore to be ready.

Parameters:

	address	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,
		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.

Reimplemented from Tp::StreamTubeChannel.