Debian Codegraph @

doc/html/gdbus-org.freedesktop.UDisks2.Job.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>org.freedesktop.UDisks2.Job: UDisks Reference Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="UDisks Reference Manual">
8 <link rel="up" href="ch03.html" title="D-Bus Interfaces">
9 <link rel="prev" href="gdbus-org.freedesktop.UDisks2.Loop.html" title="org.freedesktop.UDisks2.Loop">
10 <link rel="next" href="gdbus-org.freedesktop.UDisks2.NVMe.Controller.html" title="org.freedesktop.UDisks2.NVMe.Controller">
11 <meta name="generator" content="GTK-Doc V1.35.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts">
17 <a href="#" class="shortcut">Top</a><span id="nav_description">  <span class="dim">|</span> 
18 <a href="#gdbus-org.freedesktop.UDisks2.Job.description" class="shortcut">Description</a></span><span id="nav_properties">  <span class="dim">|</span> 
19 <a href="#gdbus-org.freedesktop.UDisks2.Job.properties" class="shortcut">Properties</a></span><span id="nav_signals">  <span class="dim">|</span> 
20 <a href="#gdbus-org.freedesktop.UDisks2.Job.signals" class="shortcut">Signals</a></span>
21 </td>
22 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
23 <td><a accesskey="u" href="ch03.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
24 <td><a accesskey="p" href="gdbus-org.freedesktop.UDisks2.Loop.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
25 <td><a accesskey="n" href="gdbus-org.freedesktop.UDisks2.NVMe.Controller.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
26 </tr></table>
27 <div class="refentry">
28 <a name="gdbus-org.freedesktop.UDisks2.Job"></a><div class="titlepage"></div>
29 <div class="refnamediv"><table width="100%"><tr>
30 <td valign="top">
31 <h2><span class="refentrytitle"><a name="gdbus-interface-org-freedesktop-UDisks2-Job.top_of_page"></a>org.freedesktop.UDisks2.Job</span></h2>
32 <p>org.freedesktop.UDisks2.Job — Long-running tasks</p>
33 </td>
34 <td class="gallery_image" valign="top" align="right"></td>
35 </tr></table></div>
36 <div class="refsynopsisdiv">
37 <h2>Methods</h2>
38 <pre class="synopsis">
39 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-method-org-freedesktop-UDisks2-Job.Cancel" title="The Cancel() method">Cancel</a> (IN a{sv} options);
40 </pre>
41 </div>
42 <div class="refsect1">
43 <a name="id-1.3.3.13.4"></a><h2>Signals</h2>
44 <pre class="synopsis">
45 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-signal-org-freedesktop-UDisks2-Job.Completed" title='The "Completed" signal'>Completed</a> (b success,
46 s message);
47 </pre>
48 </div>
49 <div class="refsect1">
50 <a name="id-1.3.3.13.5"></a><h2>Properties</h2>
51 <pre class="synopsis">
52 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Operation" title='The "Operation" property'>Operation</a> readable s
53 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Progress" title='The "Progress" property'>Progress</a> readable d
54 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.ProgressValid" title='The "ProgressValid" property'>ProgressValid</a> readable b
55 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Bytes" title='The "Bytes" property'>Bytes</a> readable t
56 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Rate" title='The "Rate" property'>Rate</a> readable t
57 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.StartTime" title='The "StartTime" property'>StartTime</a> readable t
58 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.ExpectedEndTime" title='The "ExpectedEndTime" property'>ExpectedEndTime</a> readable t
59 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Objects" title='The "Objects" property'>Objects</a> readable ao
60 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.StartedByUID" title='The "StartedByUID" property'>StartedByUID</a> readable u
61 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Cancelable" title='The "Cancelable" property'>Cancelable</a> readable b
62 </pre>
63 </div>
64 <div class="refsect1">
65 <a name="gdbus-interface-org-freedesktop-UDisks2-Job"></a><h2>Description</h2>
66 <p>
67 Some operations may take a long time (hours) to complete, that
68 is, to actually send the D-Bus reply message back. One example
69 of such an operation is the
70 <a class="link" href="gdbus-org.freedesktop.UDisks2.Block.html#gdbus-method-org-freedesktop-UDisks2-Block.Format" title="The Format() method">Format()</a> method that is used to
71 format a block device.
72 </p>
73 <p>
74 When such operations are initiated, a job object implementing
75 this interface may be created so the progress can be tracked by
76 the caller (and also other observers).
77 </p>
78 <p>
79 The object(s) that a job affects (such as block devices or
80 drives) can be determined by looking at the
81 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Objects" title='The "Objects" property'>"Objects"</a> property. Among other
82 things, this can be used to draw a spinner in the user interface
83 next to e.g. an icon for the drive or device in question.
84 </p>
85 <p>
86 The <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Operation" title='The "Operation" property'>"Operation"</a> property is used to
87 convey the type of job currently in progress.
88 </p>
89 <p>
90 The user id of the user who started the job is set in the
91 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.StartedByUID" title='The "StartedByUID" property'>"StartedByUID"</a> property.
92 </p>
93 <p>
94 A job <span class="emphasis"><em>may</em></span> convey how much progress has been
95 made, see the <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Progress" title='The "Progress" property'>"Progress"</a> and
96 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.ProgressValid" title='The "ProgressValid" property'>"ProgressValid"</a> properties.
97 </p>
98 <p>
99 When a job completes, the <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-signal-org-freedesktop-UDisks2-Job.Completed" title='The "Completed" signal'>"Completed"</a> signal
100 is emitted.
101 </p>
102 <p>
103 A job may or may not be cancelable, see the
104 <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Cancelable" title='The "Cancelable" property'>"Cancelable"</a> property. To cancel a
105 job use the <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-method-org-freedesktop-UDisks2-Job.Cancel" title="The Cancel() method">Cancel()</a> method. This
106 will cause the job to complete (with <em class="parameter"><code>success</code></em> set to <code class="constant">FALSE</code>) and
107 the D-Bus method used to initiate the operation to return,
108 usually returning the
109 <code class="literal">org.freedesktop.UDisks2.Error.Cancelled</code>
110 error. Once cancellation is requested it may take some time before
111 the job is actually completed as there might be ongoing I/O.
112 </p>
113 </div>
114 <div class="refsect1">
115 <a name="gdbus-methods-org.freedesktop.UDisks2.Job"></a><h2>Method Details</h2>
116 <div class="refsect2">
117 <a name="gdbus-method-org-freedesktop-UDisks2-Job.Cancel"></a><h3>The Cancel() method</h3>
118 <pre class="programlisting">
119 Cancel (IN a{sv} options);
120 </pre>
121 <p>
122 Cancels the job. Fails with the
123 <code class="literal">org.freedesktop.UDisks2.Error.Failed</code> error
124 if <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Cancelable" title='The "Cancelable" property'>"Cancelable"</a> is <code class="constant">FALSE</code>.
125 </p>
126 <div class="variablelist"><table border="0" class="variablelist">
127 <colgroup>
128 <col align="left" valign="top">
129 <col>
130 </colgroup>
131 <tbody><tr>
132 <td><p><span class="term"><code class="literal">IN a{sv} <em class="parameter"><code>options</code></em></code>:</span></p></td>
133 <td><p>
134 Options (currently unused except for <a class="link" href="udisks-std-options.html" title="The options parameter">standard options</a>).
135 </p></td>
136 </tr></tbody>
137 </table></div>
138 </div>
139 </div>
140 <div class="refsect1">
141 <a name="gdbus-signals-org.freedesktop.UDisks2.Job"></a><h2>Signal Details</h2>
142 <div class="refsect2">
143 <a name="gdbus-signal-org-freedesktop-UDisks2-Job.Completed"></a><h3>The "Completed" signal</h3>
144 <pre class="programlisting">
145 Completed (b success,
146 s message);
147 </pre>
148 <p>
149 Emitted when a job completes.
150 </p>
151 <div class="variablelist"><table border="0" class="variablelist">
152 <colgroup>
153 <col align="left" valign="top">
154 <col>
155 </colgroup>
156 <tbody>
157 <tr>
158 <td><p><span class="term"><code class="literal">b <em class="parameter"><code>success</code></em></code>:</span></p></td>
159 <td><p>
160 If <code class="constant">TRUE</code>, the job completed successfully.
161 </p></td>
162 </tr>
163 <tr>
164 <td><p><span class="term"><code class="literal">s <em class="parameter"><code>message</code></em></code>:</span></p></td>
165 <td><p>
166 A message describing the completion of the job, e.g. an error message.
167 </p></td>
168 </tr>
169 </tbody>
170 </table></div>
171 </div>
172 </div>
173 <div class="refsect1">
174 <a name="gdbus-properties-org.freedesktop.UDisks2.Job"></a><h2>Property Details</h2>
175 <div class="refsect2">
176 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Operation"></a><h3>The "Operation" property</h3>
177 <pre class="programlisting">
178 Operation readable s
179 </pre>
180 <p>
181 </p>
182 <p>
183 The type of the operation that the job represents.
184 </p>
185 <p>
186 Known job operation types include:
187 </p>
188 <div class="variablelist"><table border="0" class="variablelist">
189 <colgroup>
190 <col align="left" valign="top">
191 <col>
192 </colgroup>
193 <tbody>
194 <tr>
195 <td><p><span class="term">ata-smart-selftest</span></p></td>
196 <td><p>SMART self-test operation.</p></td>
197 </tr>
198 <tr>
199 <td><p><span class="term">drive-eject</span></p></td>
200 <td><p>Ejecting the medium from a drive.</p></td>
201 </tr>
202 <tr>
203 <td><p><span class="term">encrypted-unlock</span></p></td>
204 <td><p>Unlocking encrypted device.</p></td>
205 </tr>
206 <tr>
207 <td><p><span class="term">encrypted-lock</span></p></td>
208 <td><p>Locking encrypted device.</p></td>
209 </tr>
210 <tr>
211 <td><p><span class="term">encrypted-modify</span></p></td>
212 <td><p>Modifying encrypted device.</p></td>
213 </tr>
214 <tr>
215 <td><p><span class="term">encrypted-resize</span></p></td>
216 <td><p>Resizing encrypted device.</p></td>
217 </tr>
218 <tr>
219 <td><p><span class="term">encrypted-convert</span></p></td>
220 <td><p>Converting encrypted device.</p></td>
221 </tr>
222 <tr>
223 <td><p><span class="term">swapspace-start</span></p></td>
224 <td><p>Starting swapspace.</p></td>
225 </tr>
226 <tr>
227 <td><p><span class="term">swapspace-stop</span></p></td>
228 <td><p>Stopping swapspace.</p></td>
229 </tr>
230 <tr>
231 <td><p><span class="term">swapspace-modify</span></p></td>
232 <td><p>Modifying swapspace.</p></td>
233 </tr>
234 <tr>
235 <td><p><span class="term">filesystem-mount</span></p></td>
236 <td><p>Mounting a filesystem.</p></td>
237 </tr>
238 <tr>
239 <td><p><span class="term">filesystem-unmount</span></p></td>
240 <td><p>Unmounting a filesystem.</p></td>
241 </tr>
242 <tr>
243 <td><p><span class="term">filesystem-modify</span></p></td>
244 <td><p>Modifying a filesystem.</p></td>
245 </tr>
246 <tr>
247 <td><p><span class="term">filesystem-resize</span></p></td>
248 <td><p>Resizing a filesystem.</p></td>
249 </tr>
250 <tr>
251 <td><p><span class="term">format-erase</span></p></td>
252 <td><p>Erasing a device.</p></td>
253 </tr>
254 <tr>
255 <td><p><span class="term">format-mkfs</span></p></td>
256 <td><p>Creating a filesystem.</p></td>
257 </tr>
258 <tr>
259 <td><p><span class="term">loop-setup</span></p></td>
260 <td><p>Setting up a loop device.</p></td>
261 </tr>
262 <tr>
263 <td><p><span class="term">partition-modify</span></p></td>
264 <td><p>Modifying a partition.</p></td>
265 </tr>
266 <tr>
267 <td><p><span class="term">partition-delete</span></p></td>
268 <td><p>Deleting a partition.</p></td>
269 </tr>
270 <tr>
271 <td><p><span class="term">partition-create</span></p></td>
272 <td><p>Creating a partition.</p></td>
273 </tr>
274 <tr>
275 <td><p><span class="term">cleanup</span></p></td>
276 <td><p>Cleaning up devices that were removed without being properly unmounted or shut down.</p></td>
277 </tr>
278 <tr>
279 <td><p><span class="term">ata-secure-erase</span></p></td>
280 <td><p>ATA Secure Erase.</p></td>
281 </tr>
282 <tr>
283 <td><p><span class="term">ata-enhanced-secure-erase</span></p></td>
284 <td><p>ATA Enhanced Secure Erase.</p></td>
285 </tr>
286 <tr>
287 <td><p><span class="term">md-raid-stop</span></p></td>
288 <td><p>Stopping a RAID Array.</p></td>
289 </tr>
290 <tr>
291 <td><p><span class="term">md-raid-start</span></p></td>
292 <td><p>Starting a RAID Array.</p></td>
293 </tr>
294 <tr>
295 <td><p><span class="term">md-raid-fault-device</span></p></td>
296 <td><p>Marking device in RAID Array as faulty.</p></td>
297 </tr>
298 <tr>
299 <td><p><span class="term">md-raid-remove-device</span></p></td>
300 <td><p>Removing device from RAID Array.</p></td>
301 </tr>
302 <tr>
303 <td><p><span class="term">md-raid-create</span></p></td>
304 <td><p>Create a RAID Array.</p></td>
305 </tr>
306 <tr>
307 <td><p><span class="term">nvme-selftest</span></p></td>
308 <td><p>NVMe device self-test operation.</p></td>
309 </tr>
310 <tr>
311 <td><p><span class="term">nvme-sanitize</span></p></td>
312 <td><p>NVMe sanitize operation.</p></td>
313 </tr>
314 <tr>
315 <td><p><span class="term">nvme-format-ns</span></p></td>
316 <td><p>NVMe format namespace operation.</p></td>
317 </tr>
318 </tbody>
319 </table></div>
320 <p>
321 The
322 <a class="link" href="UDisksClient.html#udisks-client-get-job-description" title="udisks_client_get_job_description ()">udisks_client_get_job_description()</a>
323 function can be used to get a localized human readable description.
324 </p>
325 </div>
326 <hr>
327 <div class="refsect2">
328 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Progress"></a><h3>The "Progress" property</h3>
329 <pre class="programlisting">
330 Progress readable d
331 </pre>
332 <p>
333 </p>
334 <p>
335 How much progress has been made. Values are in the range 0 to 1.
336 </p>
337 <p>
338 Do not use unless <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.ProgressValid" title='The "ProgressValid" property'>"ProgressValid"</a> is <code class="constant">TRUE</code>.
339 </p>
340 </div>
341 <hr>
342 <div class="refsect2">
343 <a name="gdbus-property-org-freedesktop-UDisks2-Job.ProgressValid"></a><h3>The "ProgressValid" property</h3>
344 <pre class="programlisting">
345 ProgressValid readable b
346 </pre>
347 <p>
348 Set to <code class="constant">TRUE</code> if the <a class="link" href="gdbus-org.freedesktop.UDisks2.Job.html#gdbus-property-org-freedesktop-UDisks2-Job.Progress" title='The "Progress" property'>"Progress"</a> is valid.
349 </p>
350 </div>
351 <hr>
352 <div class="refsect2">
353 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Bytes"></a><h3>The "Bytes" property</h3>
354 <pre class="programlisting">
355 Bytes readable t
356 </pre>
357 <p>
358 </p>
359 <p>
360 <em class="parameter"><code>since</code></em>: 2.0.0
361 If the job involves processing a known number of bytes (for
362 example, erasing a disk), this property contains the total
363 number of bytes to process. If not, the value of this
364 property is zero.
365 </p>
366 <p>
367 The intent of this property is for user interfaces to convey
368 information such as <span class="quote">“<span class="quote">123 GB of 1.0 TB completed</span>”</span>.
369 </p>
370 </div>
371 <hr>
372 <div class="refsect2">
373 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Rate"></a><h3>The "Rate" property</h3>
374 <pre class="programlisting">
375 Rate readable t
376 </pre>
377 <p>
378 </p>
379 <p>
380 <em class="parameter"><code>since</code></em>: 2.0.0
381 If the job involves processing a number of bytes (for
382 example, erasing) and the rate at which the processing takes
383 place is known, this property contains the rate (measured in
384 bytes per second). Otherwise the value of this property is
385 zero.
386 </p>
387 <p>
388 The intent of this property is for user interfaces to convey
389 information such as <span class="quote">“<span class="quote">110 MB/sec</span>”</span>.
390 </p>
391 </div>
392 <hr>
393 <div class="refsect2">
394 <a name="gdbus-property-org-freedesktop-UDisks2-Job.StartTime"></a><h3>The "StartTime" property</h3>
395 <pre class="programlisting">
396 StartTime readable t
397 </pre>
398 <p>
399 The point in time (micro-seconds since the <a class="ulink" href="http://en.wikipedia.org/wiki/Unix_epoch" target="_top">Unix
400 Epoch</a>) that the job was started.
401 </p>
402 </div>
403 <hr>
404 <div class="refsect2">
405 <a name="gdbus-property-org-freedesktop-UDisks2-Job.ExpectedEndTime"></a><h3>The "ExpectedEndTime" property</h3>
406 <pre class="programlisting">
407 ExpectedEndTime readable t
408 </pre>
409 <p>
410 The expected point in time (micro-seconds since the <a class="ulink" href="http://en.wikipedia.org/wiki/Unix_epoch" target="_top">Unix
411 Epoch</a>) that the job will complete or 0 if unknown.
412 </p>
413 </div>
414 <hr>
415 <div class="refsect2">
416 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Objects"></a><h3>The "Objects" property</h3>
417 <pre class="programlisting">
418 Objects readable ao
419 </pre>
420 <p>
421 The objects that the job is related to, if any.
422 </p>
423 </div>
424 <hr>
425 <div class="refsect2">
426 <a name="gdbus-property-org-freedesktop-UDisks2-Job.StartedByUID"></a><h3>The "StartedByUID" property</h3>
427 <pre class="programlisting">
428 StartedByUID readable u
429 </pre>
430 <p>
431 </p>
432 <p>
433 The id of the user who started the job or 0 if started
434 by root or not through udisks.
435 </p>
436 </div>
437 <hr>
438 <div class="refsect2">
439 <a name="gdbus-property-org-freedesktop-UDisks2-Job.Cancelable"></a><h3>The "Cancelable" property</h3>
440 <pre class="programlisting">
441 Cancelable readable b
442 </pre>
443 <p>
444 Whether the job can be canceled.
445 </p>
446 </div>
447 </div>
448 </div>
449 <div class="footer">
450 <hr>Generated by GTK-Doc V1.35.1</div>
451 </body>
452 </html>