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

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

#include <TelepathyQt4/IncomingStreamTubeChannel>

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 incoming stream tubes.

In particular, this class is meant to be used as a comfortable way for accepting incoming stream tubes. It provides an easy way for obtaining a QIODevice which can be used for communication.

Usage

Obtaining an incoming stream tube

Whenever a contact invites you to open an incoming stream tube, if you are registered as a channel handler for the channel type TELEPATHY_INTERFACE_CHANNEL_TYPE_STREAM_TUBE, you will be notified of the offer and you will be able to handle the channel. Please refer to the documentation of #AbstractClientHandler for more details on channel handling.

Supposing your channel handler has been created correctly, you would do:

 void MyChannelManager::handleChannels(const Tp::MethodInvocationContextPtr<> &context,
                               const Tp::AccountPtr &account,
                               const Tp::ConnectionPtr &connection,
                               const QList<Tp::ChannelPtr> &channels,
                               const QList<Tp::ChannelRequestPtr> &requestsSatisfied,
                               const QDateTime &userActionTime,
                               const QVariantMap &handlerInfo)
 {
     foreach(const Tp::ChannelPtr &channel, channels) {
         QVariantMap properties = channel->immutableProperties();

         if (properties[TELEPATHY_INTERFACE_CHANNEL ".ChannelType"] ==
                        TELEPATHY_INTERFACE_CHANNEL_TYPE_STREAM_TUBE) {

             // Handle the channel
             Tp::IncomingStreamTubeChannelPtr myTube =
                      Tp::IncomingStreamTubeChannelPtr::dynamicCast(channel);

          }
     }

     context->setFinished();
 }

Accepting the tube

Before being ready to accept 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.

Once your object is ready, you can use one of the overloads of acceptTubeAsTcpSocket or acceptTubeAsUnixSocket to accept a socket over the tube. Please note that the socket type is not dependent on what has been offered on the other end: choosing whether you want to accept a TCP socket or an Unix socket boils down to your personal preference only and does not affect in any way the way the communication with the other end will be handled.

Let's consider the case of accepting an Unix socket without applying any access control restriction. You would simply do:

 PendingStreamTubeConnection *pendingConnection = myTube->acceptTubeAsUnixSocket();

The returned PendingOperation serves both for monitoring the state of the tube and for obtaining, upon success, either the address of the new socket or a QIODevice ready to be used. When the operation finishes, you can do:

 void MyTubeReceiver::onStreamTubeAccepted(PendingOperation *op)
 {
     if (op->isError()) {
        return;
     }

     PendingStreamTubeConnection *pendingConnection =
                                              qobject_cast<PendingStreamTubeConnection*>(op);

     QIODevice *mySocketReadyToBeUsed = pendingConnection->device();
     // Do some stuff here
 }

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 = StreamTubeChannel::FeatureStreamTube 
) [protected]

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

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

Create a new IncomingStreamTubeChannel channel.

Parameters:
connectionConnection owning this channel, and specifying the service.
objectPathThe object path of this channel.
immutablePropertiesThe immutable properties of this channel.
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 LocalPending state.

Once called, this method will try opening the tube, and will create a QIODevice which can be used to communicate with the other end. The device is guaranteed to be opened read/write when the resulting PendingStreamTubeConnection finishes successfully. You can then access the device right from PendingStreamTubeConnection or from device().

This overload will open a tube which accepts every incoming connection from Localhost. Please note that this is the equivalent of calling acceptTubeAsTcpSocket(QHostAddress::Any, 0).

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Returns:
A PendingStreamTubeConnection which will finish as soon as the tube is ready to be used (hence in the Open state)
See also:
StreamTubeChannel::supportsIPv4SocketsWithAllowedAddress
StreamTubeChannel::supportsIPv4SocketsOnLocalhost
StreamTubeChannel::supportsIPv6SocketsWithAllowedAddress
StreamTubeChannel::supportsIPv6SocketsOnLocalhost
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 LocalPending state.

Once called, this method will try opening the tube, and will create a QIODevice which can be used to communicate with the other end. The device is guaranteed to be opened read/write when the resulting PendingStreamTubeConnection finishes successfully. You can then access the device right from PendingStreamTubeConnection or from device().

This overload lets you specify an allowed address/port combination for connecting to this socket. Otherwise, you can specify QHostAddress::Any to accept every incoming connection from localhost, or use the other overload.

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Note:
When using QHostAddress::Any, the allowedPort parameter is ignored.
Parameters:
allowedAddressan allowed address for connecting to this socket, or QHostAddress::Any
allowedPortan allowed port for connecting to this socket
Returns:
A PendingStreamTubeConnection which will finish as soon as the tube is ready to be used (hence in the Open state)
See also:
StreamTubeChannel::supportsIPv4SocketsWithAllowedAddress
StreamTubeChannel::supportsIPv4SocketsOnLocalhost
StreamTubeChannel::supportsIPv6SocketsWithAllowedAddress
StreamTubeChannel::supportsIPv6SocketsOnLocalhost
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 LocalPending state.

Once called, this method will try opening the tube, and will create a QIODevice which can be used to communicate with the other end. The device is guaranteed to be opened read/write when the resulting PendingStreamTubeConnection finishes successfully. You can then access the device right from PendingStreamTubeConnection or from device().

You can also specify whether the server should require an SCM_CREDENTIALS message upon connection instead of accepting every incoming connection from localhost.

This method requires StreamTubeChannel::FeatureStreamTube to be enabled.

Parameters:
requireCredentialsWhether the server should require an SCM_CREDENTIALS message upon connection.
Returns:
A PendingStreamTubeConnection 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
QPair< QHostAddress, quint16 > Tp::IncomingStreamTubeChannel::ipAddress ( ) const

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

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

Returns:
The IP address/port combination representing this opened tube, if the tube has been accepted as a TCP socket.
Note:
This function will return a meaningful value only if the tube has already been opened.

Reimplemented from Tp::StreamTubeChannel.

QString Tp::IncomingStreamTubeChannel::localAddress ( ) const

Return the local address of the opened tube.

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

Returns:
The local address representing this opened tube as a QString, if the tube has been accepted as an Unix socket.
Note:
This function will return a meaningful value only if the tube has already been opened.

Reimplemented from Tp::StreamTubeChannel.


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