/
transferengineclient.html
155 lines (148 loc) · 16.3 KB
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 <TransferEngineClient></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 & <i>displayName</i>, const QUrl & <i>applicationIcon</i>, const QUrl & <i>serviceIcon</i>, const QUrl & <i>url</i>, const QString & <i>mimeType</i>, qlonglong <i>expectedFileSize</i>, const CallbackInterface & <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 & <i>displayName</i>, const QUrl & <i>applicationIcon</i>, const QUrl & <i>serviceIcon</i>, const CallbackInterface & <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 & <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. 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">"com.jolla.myapp"</span><span class="operator">,</span> <span class="string">"/com/jolla/myapp"</span><span class="operator">,</span> <span class="string">"com.jolla.myapp"</span><span class="operator">,</span>
<span class="string">"cancel"</span><span class="operator">,</span> <span class="string">"restart"</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">></span><a href="transferengineclient.html#createSyncEvent">createSyncEvent</a>(<span class="string">"Syncing data from my service"</span><span class="operator">,</span>
<span class="type">QUrl</span>(<span class="string">"image://theme/icon-launcher-my-app"</span>)<span class="operator">,</span>
<span class="type">QUrl</span>(<span class="string">"image://theme/icon-s-service-icon"</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">></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"><</span><span class="operator">=</span> <span class="number">1</span>) {
client<span class="operator">-</span><span class="operator">></span>updateProgress(transferId<span class="operator">,</span> progress);
progress <span class="operator">=</span> getProgressFoo(<span class="operator">&</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">"Something went wrong"</span>;
}
client<span class="operator">-</span><span class="operator">></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> & <i>displayName</i>, const <span class="type">QUrl</span> & <i>applicationIcon</i>, const <span class="type">QUrl</span> & <i>serviceIcon</i>, const <span class="type">QUrl</span> & <i>url</i>, const <span class="type">QString</span> & <i>mimeType</i>, <span class="type">qlonglong</span> <i>expectedFileSize</i>, const <span class="type"><a href="callbackinterface.html">CallbackInterface</a></span> & <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 "image://theme/icon-s-something". <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 &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> & <i>displayName</i>, const <span class="type">QUrl</span> & <i>applicationIcon</i>, const <span class="type">QUrl</span> & <i>serviceIcon</i>, const <span class="type"><a href="callbackinterface.html">CallbackInterface</a></span> & <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 "image://theme/icon-s-something". <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> & <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>