• Modules
  • TransferEngineClient
  • Contents

    TransferEngineClient Class Reference

    The TransferEngineClient class is a simple client API for creating Download and Sync events to TransferEngine. More...

     #include <TransferEngineClient>

    Public Types

    enum Status { TransferFinished, TransferCanceled, TransferInterrupted }

    Public Functions

    TransferEngineClient ( QObject * parent = 0 )
    ~TransferEngineClient ()
    int createDownloadEvent ( const QString & displayName, const QUrl & applicationIcon, const QUrl & serviceIcon, const QUrl & url, const QString & mimeType, qlonglong expectedFileSize, const CallbackInterface & callback = CallbackInterface() )
    int createSyncEvent ( const QString & displayName, const QUrl & applicationIcon, const QUrl & serviceIcon, const CallbackInterface & callback = CallbackInterface() )
    void finishTransfer ( int transferId, Status status, const QString & reason = QString() )
    void startTransfer ( int transferId )
    void updateTransferProgress ( int transferId, qreal progress )

    Detailed Description

    The TransferEngineClient class is a simple client API for creating Download and Sync events to TransferEngine.

    TransferEngineClient is a convenience API for create and updating Download and Sync entries to the Nemo TransferEngine. For Upload entries, it is required to create share plugins by implementing required interfaces provided by this TransferEngine library.

    If the client using this interface wants to enable cancel and restart functionality, it means that the client process must provide DBus API, which Nemo Transfer Engine can call in a case of canceling or restarting the operation. In order to do that client must provide CallbackInterface object with properly set dbus information. See the example below.

    For share plugin implementation:

    To use this API to create e.g. Sync entry see the example below:

     // Create the instance of the client
     TransferEngineClient *client = new TransferEngineClient(this);
    
     // Setup callback information. This is dbus interface
     CallbackInterface callback("com.jolla.myapp", "/com/jolla/myapp", "com.jolla.myapp",
                                "cancel", "restart");
    
     // Create the sync event
     int transferId = client->createSyncEvent("Syncing data from my service",
                                            QUrl("image://theme/icon-launcher-my-app"),
                                            QUrl("image://theme/icon-s-service-icon"),
                                            callback);
    
     // Start the actual transfer i.e. sync
     client->startTransfer(transferId)
    
     // Update sync progress. Usually this is done e.g. in a slot which receives sync
     // progress from a signal.
     bool ok;
     qreal progress = 0;
     while (progress <= 1) {
     client->updateProgress(transferId, progress);
     progress = getProgressFoo(&ok);
    
     if (!ok)
         break;
     }
    
     // End the sync
     TransferEngineClient status;
     QString reason;
     if (ok) {
      status = TransferEngineClient::TransferFinished;
     } else {
      status = TnrasferEngineClient::TransferInterrupted;
      reason = "Something went wrong";
     }
    
     client->finishTransfer(transferId, status, reason);

    See also TransferPluginInterface, MediaTransferInterface, and TransferPluginInfo.

    Member Type Documentation

    enum TransferEngineClient::Status

    This enum type describes different values for the Status.

    ConstantValueDescription
    TransferEngineClient::TransferFinishedTransferEngineData::TransferFinishedTransfer finished successfully
    TransferEngineClient::TransferCanceledTransferEngineData::TransferCanceledTransfer canceled usually due user actions
    TransferEngineClient::TransferInterruptedTransferEngineData::TransferInterruptedTransfer interrupted because of an error

    Member Function Documentation

    TransferEngineClient::TransferEngineClient ( QObject * parent = 0 )

    Construct an instance of TransferEngineClient with optional parent argument.

    TransferEngineClient::~TransferEngineClient ()

    Destructor.

    int TransferEngineClient::createDownloadEvent ( const QString & displayName, const QUrl & applicationIcon, const QUrl & serviceIcon, const QUrl & url, const QString & mimeType, qlonglong expectedFileSize, const CallbackInterface & callback = CallbackInterface() )

    Creates a download event to the TransferEngine. This method requires the following parameters displayName, a human readable name for the entry. applicationIcon is the QUrl to the icon of the application, who's calling this method. Usually it can be in format "image://theme/icon-s-something". serviceIcon is a service specific icon such as DropBox. url is the url to the media to be downloaded. mimeType is the mimeType of the media.

    Client can define callback functions for canceling and restarting download. For that client can provide optional parameter callback, which is CallbackInterface object containing information about the dbus service.

    Returns transfer id of the download event.

    Create a download event to the TransferEngine. This only creates and entry, and client needs still call:

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

    int TransferEngineClient::createSyncEvent ( const QString & displayName, const QUrl & applicationIcon, const QUrl & serviceIcon, const CallbackInterface & callback = CallbackInterface() )

    Create a sync event to the TransferEngine. This method is very similar to

    displayName, a human readable name for the entry. applicationIcon is the QUrl to the icon of the application, who's calling this method. Usually it can be in format "image://theme/icon-s-something". serviceIcon is a service specific icon such as email account.

    Client can define callback functions for canceling and restarting sync. For that client can provide optional parameter callback, which is CallbackInterface object containing information about the dbus service.

    Returns transfer id of the sync event.

    See also createDownload(), except, createSyncEvent(), takes, less, parameters, ., createSyncEvent(), startTransfer(), updateTransferProgress(), and finishTransfer().

    void TransferEngineClient::finishTransfer ( int transferId, Status status, const QString & reason = QString() )

    Finalize the transfer with transferId. There are three options for finalizing the transfer by setting the status parameter value:

    If the client wants to provide reason for finishing the transfer, it's possible to provide reason parameter.

    void TransferEngineClient::startTransfer ( int transferId )

    Start the transfer for the existing transfer entry with transferId. This changes the status of the transfer from idle to started.These status changes are handled by Nemo TransferEngine internally, but after this method has been called, the transfer is possible to cancel, interrupt or finish.

    void TransferEngineClient::updateTransferProgress ( int transferId, qreal progress )

    Update the progress of the existing transfer with transferId. The progress must be a qreal value between 0 to 1.