[Telepathy] tp-qt4 FileTransfer API proposal

[George Goldberg]

Andre Moreira Magalhaes wrote:
> Hi,
>
Hi,

Having looked at this a bit more, I've got a couple more things to add.
> One more API sketch for review. This time we are going to implement
> FileTransfer
> support on tp-qt4 and I would like to have some review comments on the
> API.
>
> For those not familiar with FileTransfer please refer to
> http://telepathy.freedesktop.org/spec.html#org.freedesktop.Telepathy.Channel.Type.FileTransfer
>
>
> Aditional methods that will be added to Account:
>
> class Account ...
> {
>     ...
>
>    PendingChannelRequest *createFileTransfer(
>            const QString &contactIdentifier,
>            const QString &fileName,
>            const QString &contentType,
>            qulonglong size,
>            FileHashType contentHashType = (FileHashType) -1,
>            const QString &contentHash = QString(),
>            const QString &description = QString(),
>            QDateTime lastModificationTime = QDateTime(),
>            QDateTime userActionTime = QDateTime::currentDateTime(),
>            const QString &preferredHandler = QString());
>    PendingChannelRequest *createFileTransfer(
>            const ContactPtr &contact,
>            const QString &fileName,
>            const QString &contentType,
>            qulonglong size,
>            FileHashType contentHashType = (FileHashType) -1,
>            const QString &contentHash = QString(),
>            const QString &description = QString(),
>            QDateTime lastModificationTime = QDateTime(),
>            QDateTime userActionTime = QDateTime::currentDateTime(),
>            const QString &preferredHandler = QString());
>               ...
> }
I like Will's suggestion in the previous mail. It makes these methods
considerably less frightening.
>
> Additional methods added to FileTransferChannel
>
> class FileTransferChannel ...
> {
>    ...
>       QString fileName() const;
>    QString contentType() const;
>    qulonglong size() const;
>
>    FileHashType contentHashType() const;
>    QString contentHash() const;
>
>    QString description() const;
>
>    QDateTime lastModificationTime() const;
>
>    qulonglong initialOffset() const;
>
>    qulonglong transferredBytes() const;
>
>    PendingOperation *profileFile(QIODevice *device);
>    PendingIODevice *acceptFile(qulonglong offset);
>
> Q_SIGNALS:
>    void stateChanged(FileTransferState state, FileTransferStateReason
> reason);
>    void transferredBytesChanged(qulonglong count);
>    void initialOffsetDefined(qulonglong offset);
>
>    ...
> }
>
> In order to provide a file one has to call
> FileTransferChannel::provideFile with
> a QIODevice as param. The idea is that internally we will create a
> socket to be
> used to transfer the file, but this is transparent to the user.
> QIODevice was
> choosen because it abstracts I/O devices access (file, buffer, socket,
> ...).
>
> To accept a file, FileTransferChannel::acceptFile should be called,
> which will return
> a PendingIODevice, that will contain a QIODevice where the user can
> read from it,
> when the method returns.
I like this design a lot :) QIODevice would be a really familiar way of
doing things.

One slight ugliness here, however, is that you can only accept/provide
one file per channel, and then the channel is dead. This feels really
bizarre with this API, but then, it doesn't really feel much nicer with
the raw Telepathy spec, imho. Again, I don't really see that we can make
this any better.
> I am not sure if we should provide more "low-level" methods to provide
> file and
> accept file that should take sockets as params, but I believe the
> above methods
> should be enough.
I don't really see a reason for this. If you want, you can use the
autogenerated classes directly. However, if there is a reason for adding
support for the raw sockets, then I have no objection.


George

--
George Goldberg