Home · All Classes · All Namespaces · Modules · Functions · Files
Public Member Functions | Static Public Member Functions | Protected Member Functions
Tp::OutgoingStreamTubeChannel Class Reference

The IncomingStreamTubeChannel class represents a Telepathy channel of type StreamTube for outgoing stream tubes. More...

#include <TelepathyQt4/OutgoingStreamTubeChannel>

Inherits Tp::StreamTubeChannel.

List of all members.

Public Member Functions

Static Public Member Functions

Protected Member Functions


Detailed Description

The IncomingStreamTubeChannel class represents a Telepathy channel of type StreamTube for outgoing stream tubes.

In particular, this class is meant to be used as a comfortable way for exposing new stream tubes. It provides a set of overloads for exporting a variety of sockets over a stream tube.

Usage

Creating an outgoing stream tube

The easiest way to create account objects is through Account. One can just use the Account convenience methods such as Account::createStreamTube() to get a brand new stream tube channel ready to be used.

To create such a channel, it is required to pass Account::createStreamTube() the contact identifier and the service name which will be used over the tube. For example:

 AccountPtr myaccount = getMyAccountSomewhere();
 ContactPtr myfriend = getMyFriendSomewhereElse();

 PendingChannelRequest *tube = myaccount->createStreamTube(myfriend, "rsync");

Be sure to track the pending request to retrieve your outgoing stream tube upon success.

Offering the tube

Before being ready to offer the tube, we must be sure the required features on our object are ready. In this case, we need to enable TubeChannel::FeatureTube and StreamTubeChannel::FeatureStreamTube.

 Features features = Features() << TubeChannel::FeatureTube
                                << StreamTubeChannel::FeatureStreamTube;
 connect(myTube->becomeReady(features),
         SIGNAL(finished(Tp::PendingOperation *)),
         SLOT(onStreamTubeChannelReady(Tp::PendingOperation *)));

To learn more on how to use introspectable and features, please see Making account ready to use.

You can also enable StreamTubeChannel::FeatureConnectionMonitoring if the tube supports it. Have a look at #StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress to learn more about this.

Once your object is ready, you can use one of the overloads of offerTcpSocket or offerUnixSocket to offer an existing socket over the tube. For example, if you wanted to offer an existing QTcpServer without applying any restrictions on the access control, you would simply do

 QTcpServer *server = getMyServer();

 PendingOperation *op = myTube->offerTcpSocket(server, QVariantMap());

You can now monitor the returned operation to know when the tube will be ready. It is guaranteed that when the operation finishes, the tube will be already opened and ready to be used.

See Asynchronous Object Model, Shared Pointer Usage


Constructor & Destructor Documentation

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

Class destructor.

Tp::OutgoingStreamTubeChannel::OutgoingStreamTubeChannel ( const ConnectionPtr &  connection,
const QString objectPath,
const QVariantMap &  immutableProperties,
const Feature coreFeature = StreamTubeChannel::FeatureStreamTube 
) [protected]

Construct a new OutgoingStreamTubeChannel object.

Parameters:
connectionConnection owning this channel, and specifying the service.
objectPathThe object path of this channel.
immutablePropertiesThe immutable properties of this channel.

Member Function Documentation

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

Create a new OutgoingStreamTubeChannel channel.

Parameters:
connectionConnection owning this channel, and specifying the service.
objectPathThe object path of this channel.
immutablePropertiesThe immutable properties of this channel.
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 an IPv4/IPv6 socket over the tube

This method offers an IPv4/IPv6 socket over this tube. The socket is represented through a QHostAddress. If you are already handling a Tcp logic in your application, you can also use an overload which accepts a QTcpServer.

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

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Parameters:
addressA valid IPv4 or IPv6 address pointing to an existing socket
portThe port the socket is listening for connections to
parametersA dictionary of arbitrary Parameters to send with the tube offer. Please read the specification for more details.
Returns:
A PendingOperation which will finish as soon as the tube is ready to be used (hence in the Open state)
Note:
The library will try to use Port access control whenever possible, as it allows to map connections to the socket's source address. This means that if #StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress (or #StreamTubeChannel::supportsIPv6SocketsWithSpecifiedAddress, depending on the type of the offered socket) returns true, this method will automatically enable the connection tracking feature, as long as StreamTubeChannel::FeatureConnectionMonitoring has been enabled.
See also:
StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress
StreamTubeChannel::supportsIPv4SocketsOnLocalhost
StreamTubeChannel::supportsIPv6SocketsWithSpecifiedAddress
StreamTubeChannel::supportsIPv6SocketsOnLocalhost
PendingOperation * Tp::OutgoingStreamTubeChannel::offerTcpSocket ( const QTcpServer server,
const QVariantMap &  parameters 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Offer an IPv4/IPv6 socket over the tube.

This method offers an IPv4/IPv6 socket over this tube through a QTcpServer.

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

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Parameters:
serverA valid QTcpServer, which should be already listening for incoming connections.
parametersA dictionary of arbitrary Parameters to send with the tube offer. Please read the specification for more details.
Returns:
A PendingOperation which will finish as soon as the tube is ready to be used (hence in the Open state)
Note:
The library will try to use Port access control whenever possible, as it allows to map connections to the socket's source address. This means that if #StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress (or #StreamTubeChannel::supportsIPv6SocketsWithSpecifiedAddress, depending on the type of the offered socket) returns true, this method will automatically enable the connection tracking feature, as long as StreamTubeChannel::FeatureConnectionMonitoring has been enabled.
See also:
StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress
StreamTubeChannel::supportsIPv4SocketsOnLocalhost
StreamTubeChannel::supportsIPv6SocketsWithSpecifiedAddress
StreamTubeChannel::supportsIPv6SocketsOnLocalhost
PendingOperation * Tp::OutgoingStreamTubeChannel::offerUnixSocket ( const QString socketAddress,
const QVariantMap &  parameters,
bool  requireCredentials = false 
)

Offer a Unix socket over the tube.

This method offers a Unix socket over this tube. The socket is represented through a QString, which should contain the path to the socket. You can also expose an abstract Unix socket, by including the leading null byte in the address

If you are already handling a local socket logic in your application, you can also use an overload which accepts a QLocalServer.

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

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Parameters:
addressA valid path to an existing Unix socket or abstract Unix socket
parametersA dictionary of arbitrary Parameters to send with the tube offer. Please read the specification for more details.
requireCredentialsWhether the server should require an SCM_CREDENTIALS message upon connection.
Returns:
A PendingOperation which will finish as soon as the tube is ready to be used (hence in the Open state)
See also:
StreamTubeChannel::supportsAbstractUnixSocketsOnLocalhost
StreamTubeChannel::supportsAbstractUnixSocketsWithCredentials
StreamTubeChannel::supportsUnixSocketsOnLocalhost
StreamTubeChannel::supportsUnixSocketsWithCredentials
PendingOperation * Tp::OutgoingStreamTubeChannel::offerUnixSocket ( const QLocalServer server,
const QVariantMap &  parameters,
bool  requireCredentials = false 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Offer a Unix socket over the tube.

This method offers a Unix socket over this tube through a QLocalServer.

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

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Parameters:
serverA valid QLocalServer, which should be already listening for incoming connections.
parametersA dictionary of arbitrary Parameters to send with the tube offer. Please read the specification for more details.
requireCredentialsWhether the server should require an SCM_CREDENTIALS message upon connection.
Returns:
A PendingOperation which will finish as soon as the tube is ready to be used (hence in the Open state)
See also:
StreamTubeChannel::supportsAbstractUnixSocketsOnLocalhost
StreamTubeChannel::supportsAbstractUnixSocketsWithCredentials
StreamTubeChannel::supportsUnixSocketsOnLocalhost
StreamTubeChannel::supportsUnixSocketsWithCredentials
QHash< uint, ContactPtr > Tp::OutgoingStreamTubeChannel::contactsForConnections ( ) const

If StreamTubeChannel::FeatureConnectionMonitoring has been enabled, this function returns a map from a connection ID to the associated contact.

This method requires StreamTubeChannel::FeatureConnectionMonitoring to be enabled.

Returns:
an hash mapping a connection ID to the associated contact.
Note:
The tube has to be open for calling this function
See also:
connectionsForSourceAddresses
StreamTubeChannel::addressType
QHash< QPair< QHostAddress, quint16 >, uint > Tp::OutgoingStreamTubeChannel::connectionsForSourceAddresses ( ) const

If StreamTubeChannel::FeatureConnectionMonitoring has been enabled, the socket address type of this tube is IPv4 or IPv6, and if the tube supports connection with an specified address, this function returns a map from a source address to its connection ID. It is useful to track an address which connected to your socket to a contact (by using contactsForConnections).

This method requires StreamTubeChannel::FeatureConnectionMonitoring to be enabled.

Returns:
an hash mapping a source address to its connection ID
Note:
The tube has to be open for calling this function
See also:
contactsForConnections
StreamTubeChannel::addressType
StreamTubeChannel::supportsIPv4SocketsWithSpecifiedAddress
StreamTubeChannel::supportsIPv6SocketsWithSpecifiedAddress


Copyright © 2008-2011 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.7.1