[Telepathy] API Draft for high level tubes in tp-qt4

[Olli Salli]

On Tue, Apr 27, 2010 at 10:44 PM, Dario Freddi <drf54321 at gmail.com> wrote:
> On Tuesday 27 April 2010 21:37:59 Dario Freddi wrote:
>> On Tuesday 27 April 2010 18:30:03 Olli Salli wrote:
>> > On Sat, Apr 24, 2010 at 3:55 PM, Dario Freddi <drf54321 at gmail.com> wrote:
>> > > Hello,
>> > >
>> > > please find attached a new version of tp-qt4 high level tubes.
>> > >
>> > > This time they're really high level - I tried keeping the API (and
>> > > parameters as well) as similar as possible to tp-qt4 file transfers -
>> > > it also features the same mean of creation by using
>> > > TubeChannelCreationProperties.
>> >
>> > [snip]
>> >
>> > The device attribute I'm not really getting - why would an app
>> > requesting a tube have a relevant IO device already? Connecting
>> > sockets to sockets when implementing a "tunneling" application? I
>> > think this is cargo-cult from FT, where one provides the file to send
>> > by providing a QIODevice - this is an abstraction for giving it an
>> > existing "file" of any kind. However, the use case here is completely
>> > different. One should consider setting up an outgoing stream tube
>> > analogous to connecting a TCP socket from a client to a server for
>> > communication. One should be able to easily replace the TCP connect
>> > logic in a networked app by offering a d-bus tube with the remaining
>> > app logic remaining the same (using a QIODevice for communication,
>> > this time it being the tube instead of a QTcpSocket set up by the
>> > application).

Sorry, I was totally talking crap here :( In reality, offering a
stream tube is equivalent to starting to listen on a socket and
"advertising" "I'm listening right here", not connecting. You seem to
be well aware of this though, hope I didn't confuse you too much.
Still, I wouldn't like Offer to take QIODevices, as a generic IO
device (think a file or somesuch) can't be exported, and it's actually
QTcpServer and QLocalServer which don't derive from QIODevice that
correspond to listening sockets. You could offer QTcpServer and
QLocalServer taking overloads though. It's easy to extract the address
from those. Still, you need the bare address version too, as the
socket isn't both a qt socket AND in the same process in all cases.

>>
>> As suggested, I changed the offer function in OutgoingStreamTubeChannel to:
>>
>> PendingIODevice *offerTube(const QString &name, const QHostAddress
>> &address, const QVariantMap &parameters);
>
> Of course I meant:
>
> PendingIODevice *offerTube(const QHostAddress &address, const QVariantMap
> &parameters);

You don't need (actually even can't have) it returning a
PendingIODevice since, yeah, it's exporting a socket existing
somewhere in an address space the CM can see, NOT creating a new
socket (except implicitly by the CM when someone accepts in the other
end of the tube).

>
> And in Account:
>
> PendingChannelRequest *createStreamTube(
>            const ContactPtr &contact,
>            const QString &serviceName,
>            const QDateTime &userActionTime = QDateTime::currentDateTime(),
>            const QString &preferredHandler = QString());
>
>>
>> QHostAddress should already nicely encapsulate the needed logic for
>> address_type+address, I would appreciate if one of you could confirm that.
>>

QHostAddress is excellent for exporting TCP sockets, however we should
also expose unix sockets as supported by the spec. In addition to the
possible aforementioned QLocalServer taking overload this could be
simply an overload taking a const QString &socketName instead of the
QHostAddress. QString supports embedded NUL bytes so the abstract
socket case would be supported too.

>> I am wondering if I should also expose socket_access_control: in case it's
>> not needed, what's a sensible default? I see in FT Localhost is always
>> used, but I'm wondering if there are some use cases I'm not considering
>> here.
>>

The socket used in FT is just a temporary socket created exclusively
for transferring the file in question between the CM and the client,
enabling its type and access control to be "negotiated" by the client
and CM freely. TpQt4 FT uses IPv4 as the address type because the spec
requires all CMs to support it. For FT, Localhost access control is
sufficient for most cases, since the client and CM are running on the
same session bus, which usually means they're running on the same host
too.

For stream tubes however, the socket to export can be arbitrary
depending on the server application, and it's not necessarily
exclusively created to be exported over a Tube. It doesn't even have
to be on the same host, actually... So you do need to support
specifying the access control, but for most use cases Localhost should
be alright so it'd make sense to have it as a default parameter. One
thing buggering me is that the new stream tube D-Bus API doesn't
actually seem to have a way to provide the address for Port type
access control (old tubes api had a "access control parameter" variant
for this purpose) - so we really can't sensibly support anything other
than Localhost required or not and Credentials required or not.

So I think we're down to at least two overloads (one taking a
QHostAddress and the other taking a QString), possibly four
(additional ones taking QTcpServer and QLocalServer). Every method
should include an accessControl = Localhost parameter, and none should
return a IO device. Does this sound sensible this time around? ;)

-- 

Br,
Olli Salli