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

#include <TelepathyQt/OutgoingStreamTubeChannel>

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

◆ ~OutgoingStreamTubeChannel()

Tp::OutgoingStreamTubeChannel::~OutgoingStreamTubeChannel ( )

virtual

Class destructor.

◆ OutgoingStreamTubeChannel()

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

◆ create()

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.

◆ offerTcpSocket() [1/2]

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

◆ offerTcpSocket() [2/2]

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

◆ offerUnixSocket() [1/2]

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

◆ offerUnixSocket() [2/2]

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

◆ contactsForConnections()

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

◆ connectionsForSourceAddresses()

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

◆ 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

◆ FeatureCore

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.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~OutgoingStreamTubeChannel()

◆ OutgoingStreamTubeChannel()

Member Function Documentation

◆ create()

◆ offerTcpSocket() [1/2]

◆ offerTcpSocket() [2/2]

◆ offerUnixSocket() [1/2]

◆ offerUnixSocket() [2/2]

◆ contactsForConnections()

◆ connectionsForSourceAddresses()

◆ connectionsForCredentials()

Member Data Documentation

◆ FeatureCore