transferengineclient.html 16.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- transferengineclient.cpp -->
  <title>Nemo TransferEngine 1.0: TransferEngineClient Class Reference</title>
<li>Modules</li>
<li>TransferEngineClient</li>
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
</ul>
</div>
<h1 class="title">TransferEngineClient Class Reference</h1>
<!-- $$$TransferEngineClient-brief -->
<p>The TransferEngineClient class is a simple client API for creating Download and Sync events to <a href="transferengine.html">TransferEngine</a>. <a href="#details">More...</a></p>
<!-- @@@TransferEngineClient -->
<pre class="cpp"> <span class="preprocessor">#include &lt;TransferEngineClient&gt;</span></pre><ul>
<li><a href="transferengineclient-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2>Public Types</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#Status-enum">Status</a></b> { TransferFinished, TransferCanceled, TransferInterrupted }</td></tr>
</table>
<a name="public-functions"></a>
<h2>Public Functions</h2>
<table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#TransferEngineClient">TransferEngineClient</a></b> ( QObject * <i>parent</i> = 0 )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#dtor.TransferEngineClient">~TransferEngineClient</a></b> ()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#createDownloadEvent">createDownloadEvent</a></b> ( const QString &amp; <i>displayName</i>, const QUrl &amp; <i>applicationIcon</i>, const QUrl &amp; <i>serviceIcon</i>, const QUrl &amp; <i>url</i>, const QString &amp; <i>mimeType</i>, qlonglong <i>expectedFileSize</i>, const CallbackInterface &amp; <i>callback</i> = CallbackInterface() )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> int </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#createSyncEvent">createSyncEvent</a></b> ( const QString &amp; <i>displayName</i>, const QUrl &amp; <i>applicationIcon</i>, const QUrl &amp; <i>serviceIcon</i>, const CallbackInterface &amp; <i>callback</i> = CallbackInterface() )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#finishTransfer">finishTransfer</a></b> ( int <i>transferId</i>, Status <i>status</i>, const QString &amp; <i>reason</i> = QString() )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#startTransfer">startTransfer</a></b> ( int <i>transferId</i> )</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="transferengineclient.html#updateTransferProgress">updateTransferProgress</a></b> ( int <i>transferId</i>, qreal <i>progress</i> )</td></tr>
</table>
<a name="details"></a>
<!-- $$$TransferEngineClient-description -->
<div class="descr">
<h2>Detailed Description</h2>
<p>The TransferEngineClient class is a simple client API for creating Download and Sync events to <a href="transferengine.html">TransferEngine</a>.</p>
<p>TransferEngineClient is a convenience API for create and updating Download and Sync entries to the Nemo <a href="transferengine.html">TransferEngine</a>. For Upload entries, it is required to create share plugins by implementing required interfaces provided by this <a href="transferengine.html">TransferEngine</a> library.</p>
<p>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 <a href="callbackinterface.html">CallbackInterface</a> object with properly set dbus information. See the example below.</p>
<p>For share plugin implementation:</p>
<p>To use this API to create e.g&#x2e; Sync entry see the example below:</p>
<pre class="cpp"> <span class="comment">// Create the instance of the client</span>
 TransferEngineClient <span class="operator">*</span>client <span class="operator">=</span> <span class="keyword">new</span> <a href="transferengineclient.html#TransferEngineClient">TransferEngineClient</a>(<span class="keyword">this</span>);

 <span class="comment">// Setup callback information. This is dbus interface</span>
 CallbackInterface callback(<span class="string">&quot;com.jolla.myapp&quot;</span><span class="operator">,</span> <span class="string">&quot;/com/jolla/myapp&quot;</span><span class="operator">,</span> <span class="string">&quot;com.jolla.myapp&quot;</span><span class="operator">,</span>
                            <span class="string">&quot;cancel&quot;</span><span class="operator">,</span> <span class="string">&quot;restart&quot;</span>);

 <span class="comment">// Create the sync event</span>
 <span class="type">int</span> transferId <span class="operator">=</span> client<span class="operator">-</span><span class="operator">&gt;</span><a href="transferengineclient.html#createSyncEvent">createSyncEvent</a>(<span class="string">&quot;Syncing data from my service&quot;</span><span class="operator">,</span>
                                        <span class="type">QUrl</span>(<span class="string">&quot;image://theme/icon-launcher-my-app&quot;</span>)<span class="operator">,</span>
                                        <span class="type">QUrl</span>(<span class="string">&quot;image://theme/icon-s-service-icon&quot;</span>)<span class="operator">,</span>
                                        callback);

 <span class="comment">// Start the actual transfer i.e. sync</span>
 client<span class="operator">-</span><span class="operator">&gt;</span><a href="transferengineclient.html#startTransfer">startTransfer</a>(transferId)

 <span class="comment">// Update sync progress. Usually this is done e.g. in a slot which receives sync</span>
 <span class="comment">// progress from a signal.</span>
 <span class="type">bool</span> ok;
 <span class="type">qreal</span> progress <span class="operator">=</span> <span class="number">0</span>;
 <span class="keyword">while</span> (progress <span class="operator">&lt;</span><span class="operator">=</span> <span class="number">1</span>) {
 client<span class="operator">-</span><span class="operator">&gt;</span>updateProgress(transferId<span class="operator">,</span> progress);
 progress <span class="operator">=</span> getProgressFoo(<span class="operator">&amp;</span>ok);

 <span class="keyword">if</span> (<span class="operator">!</span>ok)
     <span class="keyword">break</span>;
 }

 <span class="comment">// End the sync</span>
 TransferEngineClient status;
 <span class="type">QString</span> reason;
 <span class="keyword">if</span> (ok) {
  status <span class="operator">=</span> TransferEngineClient<span class="operator">::</span>TransferFinished;
 } <span class="keyword">else</span> {
  status <span class="operator">=</span> TnrasferEngineClient<span class="operator">::</span>TransferInterrupted;
  reason <span class="operator">=</span> <span class="string">&quot;Something went wrong&quot;</span>;
 }

 client<span class="operator">-</span><span class="operator">&gt;</span><a href="transferengineclient.html#finishTransfer">finishTransfer</a>(transferId<span class="operator">,</span> status<span class="operator">,</span> reason);</pre>
</div>
<p><b>See also </b><a href="transferplugininterface.html">TransferPluginInterface</a>, MediaTransferInterface, and TransferPluginInfo.</p>
<!-- @@@TransferEngineClient -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$Status$$$TransferFinished$$$TransferCanceled$$$TransferInterrupted -->
<h3 class="fn"><a name="Status-enum"></a>enum TransferEngineClient::<span class="name">Status</span></h3>
<p>This enum type describes different values for the Status.</p>
<table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><tt>TransferEngineClient::TransferFinished</tt></td><td class="topAlign"><tt>TransferEngineData::TransferFinished</tt></td><td class="topAlign">Transfer finished successfully</td></tr>
<tr><td class="topAlign"><tt>TransferEngineClient::TransferCanceled</tt></td><td class="topAlign"><tt>TransferEngineData::TransferCanceled</tt></td><td class="topAlign">Transfer canceled usually due user actions</td></tr>
<tr><td class="topAlign"><tt>TransferEngineClient::TransferInterrupted</tt></td><td class="topAlign"><tt>TransferEngineData::TransferInterrupted</tt></td><td class="topAlign">Transfer interrupted because of an error</td></tr>
</table>
<!-- @@@Status -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$TransferEngineClient[overload1]$$$TransferEngineClientQObject* -->
<h3 class="fn"><a name="TransferEngineClient"></a>TransferEngineClient::<span class="name">TransferEngineClient</span> ( <span class="type">QObject</span> * <i>parent</i> = 0 )</h3>
<p>Construct an instance of <a href="transferengineclient.html">TransferEngineClient</a> with optional <i>parent</i> argument.</p>
<!-- @@@TransferEngineClient -->
<!-- $$$~TransferEngineClient[overload1]$$$~TransferEngineClient -->
<h3 class="fn"><a name="dtor.TransferEngineClient"></a>TransferEngineClient::<span class="name">~TransferEngineClient</span> ()</h3>
<p>Destructor.</p>
<!-- @@@~TransferEngineClient -->
<!-- $$$createDownloadEvent[overload1]$$$createDownloadEventconstQString&constQUrl&constQUrl&constQUrl&constQString&qlonglongconstCallbackInterface& -->
<h3 class="fn"><a name="createDownloadEvent"></a><span class="type">int</span> TransferEngineClient::<span class="name">createDownloadEvent</span> ( const <span class="type">QString</span> &amp; <i>displayName</i>, const <span class="type">QUrl</span> &amp; <i>applicationIcon</i>, const <span class="type">QUrl</span> &amp; <i>serviceIcon</i>, const <span class="type">QUrl</span> &amp; <i>url</i>, const <span class="type">QString</span> &amp; <i>mimeType</i>, <span class="type">qlonglong</span> <i>expectedFileSize</i>, const <span class="type"><a href="callbackinterface.html">CallbackInterface</a></span> &amp; <i>callback</i> = CallbackInterface() )</h3>
<p>Creates a download event to the <a href="transferengine.html">TransferEngine</a>. This method requires the following parameters <i>displayName</i>, a human readable name for the entry. <i>applicationIcon</i> is the <tt>QUrl</tt> to the icon of the application, who's calling this method. Usually it can be in format &quot;image://theme/icon-s-something&quot;. <i>serviceIcon</i> is a service specific icon such as DropBox. <i>url</i> is the url to the media to be downloaded. <i>mimeType</i> is the mimeType of the media.</p>
<p>Client can define callback functions for canceling and restarting download. For that client can provide optional parameter <i>callback</i>, which is <tt>CallbackInterface</tt> object containing information about the dbus service.</p>
<p>Returns transfer id of the download event.</p>
<p>Create a download event to the <a href="transferengine.html">TransferEngine</a>. This only creates and entry, and client needs still call:</p>
<ul>
<li>TransferEngineClient::startTransfer(int transferId)</li>
<li>TransferEngineClient::updateTransferProgress(int transferId, qreal progress)</li>
<li>TransferEngineClient::finishTransfer(int transferId, Status status, const QString &amp;reason)</li>
</ul>
<p><b>See also </b><a href="transferengineclient.html#createSyncEvent">createSyncEvent</a>(), <a href="transferengineclient.html#startTransfer">startTransfer</a>(), <a href="transferengineclient.html#updateTransferProgress">updateTransferProgress</a>(), and <a href="transferengineclient.html#finishTransfer">finishTransfer</a>().</p>
<!-- @@@createDownloadEvent -->
<!-- $$$createSyncEvent[overload1]$$$createSyncEventconstQString&constQUrl&constQUrl&constCallbackInterface& -->
<h3 class="fn"><a name="createSyncEvent"></a><span class="type">int</span> TransferEngineClient::<span class="name">createSyncEvent</span> ( const <span class="type">QString</span> &amp; <i>displayName</i>, const <span class="type">QUrl</span> &amp; <i>applicationIcon</i>, const <span class="type">QUrl</span> &amp; <i>serviceIcon</i>, const <span class="type"><a href="callbackinterface.html">CallbackInterface</a></span> &amp; <i>callback</i> = CallbackInterface() )</h3>
<p>Create a sync event to the <a href="transferengine.html">TransferEngine</a>. This method is very similar to</p>
<p><i>displayName</i>, a human readable name for the entry. <i>applicationIcon</i> is the <tt>QUrl</tt> to the icon of the application, who's calling this method. Usually it can be in format &quot;image://theme/icon-s-something&quot;. <i>serviceIcon</i> is a service specific icon such as email account.</p>
<p>Client can define callback functions for canceling and restarting sync. For that client can provide optional parameter <i>callback</i>, which is <tt>CallbackInterface</tt> object containing information about the dbus service.</p>
<p>Returns transfer id of the sync event.</p>
<p><b>See also </b>createDownload(), except, createSyncEvent(), takes, less, parameters, ., createSyncEvent(), <a href="transferengineclient.html#startTransfer">startTransfer</a>(), <a href="transferengineclient.html#updateTransferProgress">updateTransferProgress</a>(), and <a href="transferengineclient.html#finishTransfer">finishTransfer</a>().</p>
<!-- @@@createSyncEvent -->
<!-- $$$finishTransfer[overload1]$$$finishTransferintStatusconstQString& -->
<h3 class="fn"><a name="finishTransfer"></a><span class="type">void</span> TransferEngineClient::<span class="name">finishTransfer</span> ( <span class="type">int</span> <i>transferId</i>, <span class="type"><a href="transferengineclient.html#Status-enum">Status</a></span> <i>status</i>, const <span class="type">QString</span> &amp; <i>reason</i> = QString() )</h3>
<p>Finalize the transfer with <i>transferId</i>. There are three options for finalizing the transfer by setting the <i>status</i> parameter value:</p>
<ul>
<li><a href="transferengineclient.html#Status-enum">TransferEngineClient::TransferFinished</a> - success</li>
<li><a href="transferengineclient.html#Status-enum">TransferEngineClient::TransferCanceled</a> - user cancelation</li>
<li><a href="transferengineclient.html#Status-enum">TransferEngineClient::TransferInterrupted</a> - an error</li>
</ul>
<p>If the client wants to provide reason for finishing the transfer, it's possible to provide <i>reason</i> parameter.</p>
<!-- @@@finishTransfer -->
<!-- $$$startTransfer[overload1]$$$startTransferint -->
<h3 class="fn"><a name="startTransfer"></a><span class="type">void</span> TransferEngineClient::<span class="name">startTransfer</span> ( <span class="type">int</span> <i>transferId</i> )</h3>
<p>Start the transfer for the existing transfer entry with <i>transferId</i>. This changes the status of the transfer from idle to started.These status changes are handled by Nemo <a href="transferengine.html">TransferEngine</a> internally, but after this method has been called, the transfer is possible to cancel, interrupt or finish.</p>
<!-- @@@startTransfer -->
<!-- $$$updateTransferProgress[overload1]$$$updateTransferProgressintqreal -->
<h3 class="fn"><a name="updateTransferProgress"></a><span class="type">void</span> TransferEngineClient::<span class="name">updateTransferProgress</span> ( <span class="type">int</span> <i>transferId</i>, <span class="type">qreal</span> <i>progress</i> )</h3>
<p>Update the progress of the existing transfer with <i>transferId</i>. The <i>progress</i> must be a <tt>qreal</tt> value between 0 to 1.</p>
<!-- @@@updateTransferProgress -->
</div>
</body>
</html>