• Modules
  • TransferEngine
  • Contents

    TransferEngine Class Reference

    The TransferEngine class implements the functionality for different transfer types. More...

     #include <TransferEngine>

    Public Functions

    TransferEngine ( QObject * parent = 0 )
    ~TransferEngine ()

    Public Slots

    void cancelTransfer ( int transferId )
    void clearTransfers ()
    int createDownload ( const QString & displayName, const QString & applicationIcon, const QString & serviceIcon, const QString & filePath, const QString & mimeType, qlonglong expectedFileSize, const QStringList & callback, const QString & cancelMethod, const QString & restartMethod )
    int createSync ( const QString & displayName, const QString & applicationIcon, const QString & serviceIcon, const QStringList & callback, const QString & cancelMethod, const QString & restartMethod )
    void enableNotifications ( bool enable )
    void finishTransfer ( int transferId, int status, const QString & reason )
    bool notificationsEnabled ()
    void restartTransfer ( int transferId )
    void startTransfer ( int transferId )
    QList<TransferMethodInfo> transferMethods ()
    QList<TransferDBRecord> transfers ()
    void updateTransferProgress ( int transferId, double progress )
    int uploadMediaItem ( const QString & source, const QString & serviceId, const QString & mimeType, bool metadataStripped, const QVariantMap & userData )
    int uploadMediaItemContent ( const QVariantMap & content, const QString & serviceId, const QVariantMap & userData )

    Signals

    void progressChanged ( int transferId, double progress )
    void statusChanged ( int transferId, int status )
    void transferMethodListChanged ()
    void transfersChanged ()

    Detailed Description

    The TransferEngine class implements the functionality for different transfer types.

    TransferEngine is the central place for:

    For Downloads and Syncs, the Transfer Engine acts only a place to keep track of these operations. The actual Download and Sync is executed by a client using TransferEngine API. For sharing the TransferEngine provides an API containing a few interaces, which a share plugin must implement. TransferEngine also takes care of loading and executing the sharing, based on the API it defines.

    The most essential thing to remember is that Transfer Engine provides share plugin API, DBus API e.g. for creating Transfer UI or Share UIs, it stores data to the local sqlite database using DbManager and that's it.

    How to implement a share plugin see: TransferPluginInterface, MediaTransferInterface, MediaItem, TransferPluginInfo

    TransferEngine provides DBus API, but instead of using it directly, it's recommended to use TransferEngineClient. If there is a need to create UI to display e.g. transfer statuses, then the DBus API is the recommend way to implement it.

    Member Function Documentation

    TransferEngine::TransferEngine ( QObject * parent = 0 )

    Constructor with optional parent arguement.

    TransferEngine::~TransferEngine ()

    Destructor.

    void TransferEngine::cancelTransfer ( int transferId ) [slot]

    DBus adaptor calls this method to cancel an existing transfer with a transferId.

    If the transfer is Upload, then this method calls MediaTransferInterface instance's cancel method. In a case of Sync or Download this method calls client's cancel callback method, if the one exists.

    Calling this method causes statusChanged() signal to be emitted.

    void TransferEngine::clearTransfers () [slot]

    DBus adaptor calls this method to clear all the finished, canceled or interrupted transfers in the database.

    int TransferEngine::createDownload ( const QString & displayName, const QString & applicationIcon, const QString & serviceIcon, const QString & filePath, const QString & mimeType, qlonglong expectedFileSize, const QStringList & callback, const QString & cancelMethod, const QString & restartMethod ) [slot]

    DBus adaptor calls this method to create a download entry. Note that this is purely write-only method and doesn't involve anything else from TransferEngine side than creating a new DB record of type 'Download'.

    This method returns the transfer id of the created Download transfer. Note that this method only creates an entry to the database. To start the actual transfer, the startTransfer() method must be called.

    See also startTransfer(), restartTransfer(), finishTransfer(), and updateTransferProgress().

    int TransferEngine::createSync ( const QString & displayName, const QString & applicationIcon, const QString & serviceIcon, const QStringList & callback, const QString & cancelMethod, const QString & restartMethod ) [slot]

    DBus adaptor calls this method to create a Sync entry. Note that this is purely write-only method and doesn't involve anything else from TransferEngine side than creating a new DB record of type 'Download'.

    This method returns the transfer id of the created Download transfer. Note that this method only creates an entry to the database. To start the actual transfer, the startTransfer() method must be called.

    See also startTransfer(), restartTransfer(), finishTransfer(), and updateTransferProgress().

    void TransferEngine::enableNotifications ( bool enable ) [slot]

    DBus adaptor calls this method to enable or disable transfer speicific notifications based on enable argument.

    void TransferEngine::finishTransfer ( int transferId, int status, const QString & reason ) [slot]

    Finish an existing Sync or Download transfer with a transferId. Transfer can be finished with different status e.g for successfully finish status can be set to TransferEngineData::TransferFinished, for canceling TransferEngineData::Canceled and for failure with TransferEngineData::TransferInterrupted. In a case of failure, the client can also provide a reason.

    This method causes statusChanged() signal to be emitted. If a sync has been successfully finished, then it will also be removed from the database automatically which causes transferChanged() signal to be emitted.

    bool TransferEngine::notificationsEnabled () [slot]

    DBus adaptor calls this method. Returns true or false depending if notifications are enabled or disabled.

    void TransferEngine::progressChanged ( int transferId, double progress ) [signal]

    void TransferEngine::restartTransfer ( int transferId ) [slot]

    DBus adaptor calls this method to restart a canceled or failed transfer with a \transferId. In a case of Upload, this method creates MediaItem instance of the existing transfer and instantiates the required share plugin. The MediaItem instance is passed to the plugin and sharing is restarted.

    For Sync and Download entries, this method calls their callbacks methods, if a callback interface has been defined by the client originally created the Sync or Download entry.

    void TransferEngine::startTransfer ( int transferId ) [slot]

    DBus adaptor calls this method to start the actual transfer. This method changes the transfer status of the existing transfer with a key to TransferEngineData::TransferStarted. This method can only be called for Sync and Download transfers.

    Calling this method causes the corresponding statusChanged() signal to be emitted.

    void TransferEngine::statusChanged ( int transferId, int status ) [signal]

    void TransferEngine::transferMethodListChanged () [signal]

    QList<TransferMethodInfo> TransferEngine::transferMethods () [slot]

    DBus adaptor calls this method to fetch a list of transfer methods. This method returns QList<TransferMethodInfo>.

    Transfer methods are basically a list of share plugins installed to the system.

    QList<TransferDBRecord> TransferEngine::transfers () [slot]

    DBus adaptor calls this method to fetch a list of transfers. This method returns QList<TransferDBRecord>.

    void TransferEngine::transfersChanged () [signal]

    void TransferEngine::updateTransferProgress ( int transferId, double progress ) [slot]

    DBus adaptor calls this method to update transfer progress of the transfer with a transferId and with a new progress.

    int TransferEngine::uploadMediaItem ( const QString & source, const QString & serviceId, const QString & mimeType, bool metadataStripped, const QVariantMap & userData ) [slot]

    DBus adaptor calls this method to start uploading a media item. The minimum information needed to start an upload and to create an entry to the transfer database is: source the path to the media item to be downloaded. serviceId the ID of the share plugin. See TransferPluginInterface::pluginId() for more details. mimeType is the MimeType of the media item e.g. "image/jpeg". metadataStripped boolean to indicate if the metadata should be kept or removed before uploading. userData is various kind of data which share UI may provide to the engine. UserData is QVariant map i.e. the data must be provided as key-value pairs, where the keys must be QStrings.

    TransferEngine handles the following user defined data automatically and stores them to the database:

    In practice this method instantiates a share plugin with serviceId and passes a MediaItem instance filled with required data to it. When the plugin has been loaded, the MediaTransferInterface::start() method is called and the actual sharing starts.

    This method returns a transfer ID which can be used later to fetch information of this specific transfer.

    int TransferEngine::uploadMediaItemContent ( const QVariantMap & content, const QString & serviceId, const QVariantMap & userData ) [slot]

    DBus adaptor calls this method to start uploading media item content. Sometimes the content to be shared is not a file, but data e.g. contact information in vcard format. In order to avoid serializing data to a file, pass url to the file, reading the data, deleting the file, TransferEngine provides this convenience API.

    content is the media item content to be shared. serviceId is the id of the share plugin. See TransferPluginInterface::pluginId() for more details. userData is a QVariantMap containing share plugin specific data. See TransferEngine::uploadMediaItem for more details.

    This method returns a transfer ID which can be used later to fetch information of this specific transfer.