]>
Commit | Line | Data |
---|---|---|
2fe60ff1 ZJS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
2fe60ff1 ZJS |
5 | |
6 | <refentry id="org.freedesktop.import1" conditional='ENABLE_IMPORTD' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | <refentryinfo> | |
9 | <title>org.freedesktop.import1</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>org.freedesktop.import1</refentrytitle> | |
15 | <manvolnum>5</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>org.freedesktop.import1</refname> | |
20 | <refpurpose>The D-Bus interface of systemd-importd</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsect1> | |
24 | <title>Introduction</title> | |
25 | ||
26 | <para> | |
27 | <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
fd571c9d LP |
28 | is a system service which may be used to import, export and download disk images. These images can be |
29 | used by tools such as | |
30 | <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> to run | |
31 | local containers. The service is used as the backend for <command>importctl pull-raw</command>, | |
32 | <command>importctl pull-tar</command> and related commands. This page describes the D-Bus interface. | |
b441a1d4 | 33 | </para> |
2fe60ff1 ZJS |
34 | |
35 | <para>Note that | |
36 | <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
37 | is mostly a small companion service for | |
38 | <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. | |
b441a1d4 | 39 | Many operations to manipulate local container and VM images are hence available via the <command>systemd-machined</command> D-Bus API, c.f. |
55cf7779 | 40 | <citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry>. |
2fe60ff1 ZJS |
41 | </para> |
42 | </refsect1> | |
43 | ||
44 | <refsect1> | |
45 | <title>The Manager Object</title> | |
46 | ||
47 | <para>The service exposes the following interfaces on the Manager object on the bus:</para> | |
48 | ||
48f99d7c | 49 | <programlisting executable="systemd-importd" node="/org/freedesktop/import1" interface="org.freedesktop.import1.Manager"> |
2fe60ff1 ZJS |
50 | node /org/freedesktop/import1 { |
51 | interface org.freedesktop.import1.Manager { | |
52 | methods: | |
53 | ImportTar(in h fd, | |
54 | in s local_name, | |
55 | in b force, | |
56 | in b read_only, | |
57 | out u transfer_id, | |
58 | out o transfer_path); | |
fd571c9d LP |
59 | ImportTarEx(in h fd, |
60 | in s local_name, | |
61 | in s class, | |
62 | in t flags, | |
63 | out u transfer_id, | |
64 | out o transfer_path); | |
2fe60ff1 ZJS |
65 | ImportRaw(in h fd, |
66 | in s local_name, | |
67 | in b force, | |
68 | in b read_only, | |
69 | out u transfer_id, | |
70 | out o transfer_path); | |
fd571c9d LP |
71 | ImportRawEx(in h fd, |
72 | in s local_name, | |
73 | in s class, | |
74 | in t flags, | |
75 | out u transfer_id, | |
76 | out o transfer_path); | |
4fb222c4 ZJS |
77 | ImportFileSystem(in h fd, |
78 | in s local_name, | |
79 | in b force, | |
80 | in b read_only, | |
81 | out u transfer_id, | |
82 | out o transfer_path); | |
fd571c9d LP |
83 | ImportFileSystemEx(in h fd, |
84 | in s local_name, | |
85 | in s class, | |
86 | in t flags, | |
87 | out u transfer_id, | |
88 | out o transfer_path); | |
2fe60ff1 ZJS |
89 | ExportTar(in s local_name, |
90 | in h fd, | |
91 | in s format, | |
92 | out u transfer_id, | |
93 | out o transfer_path); | |
fd571c9d LP |
94 | ExportTarEx(in s local_name, |
95 | in s class, | |
96 | in h fd, | |
97 | in s format, | |
98 | in t flags, | |
99 | out u transfer_id, | |
100 | out o transfer_path); | |
2fe60ff1 ZJS |
101 | ExportRaw(in s local_name, |
102 | in h fd, | |
103 | in s format, | |
104 | out u transfer_id, | |
105 | out o transfer_path); | |
fd571c9d LP |
106 | ExportRawEx(in s local_name, |
107 | in s class, | |
108 | in h fd, | |
109 | in s format, | |
110 | in t flags, | |
111 | out u transfer_id, | |
112 | out o transfer_path); | |
2fe60ff1 ZJS |
113 | PullTar(in s url, |
114 | in s local_name, | |
115 | in s verify_mode, | |
116 | in b force, | |
117 | out u transfer_id, | |
118 | out o transfer_path); | |
fd571c9d LP |
119 | PullTarEx(in s url, |
120 | in s local_name, | |
121 | in s class, | |
122 | in s verify_mode, | |
123 | in t flags, | |
124 | out u transfer_id, | |
125 | out o transfer_path); | |
2fe60ff1 ZJS |
126 | PullRaw(in s url, |
127 | in s local_name, | |
128 | in s verify_mode, | |
129 | in b force, | |
130 | out u transfer_id, | |
131 | out o transfer_path); | |
fd571c9d LP |
132 | PullRawEx(in s url, |
133 | in s local_name, | |
134 | in s class, | |
135 | in s verify_mode, | |
136 | in t flags, | |
137 | out u transfer_id, | |
138 | out o transfer_path); | |
4fb222c4 | 139 | ListTransfers(out a(usssdo) transfers); |
fd571c9d LP |
140 | ListTransfersEx(in s class, |
141 | in t flags, | |
142 | out a(ussssdo) transfers); | |
2fe60ff1 | 143 | CancelTransfer(in u transfer_id); |
fd571c9d LP |
144 | ListImages(in s class, |
145 | in t flags, | |
146 | out a(ssssbtttttt) images); | |
2fe60ff1 ZJS |
147 | signals: |
148 | TransferNew(u transfer_id, | |
149 | o transfer_path); | |
150 | TransferRemoved(u transfer_id, | |
151 | o transfer_path, | |
152 | s result); | |
153 | }; | |
4fb222c4 ZJS |
154 | interface org.freedesktop.DBus.Peer { ... }; |
155 | interface org.freedesktop.DBus.Introspectable { ... }; | |
156 | interface org.freedesktop.DBus.Properties { ... }; | |
2fe60ff1 | 157 | }; |
4fb222c4 ZJS |
158 | </programlisting> |
159 | ||
00bb75d7 ZJS |
160 | <!--Autogenerated cross-references for systemd.directives, do not edit--> |
161 | ||
162 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/> | |
163 | ||
164 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Manager"/> | |
165 | ||
166 | <variablelist class="dbus-method" generated="True" extra-ref="ImportTar()"/> | |
167 | ||
fd571c9d LP |
168 | <variablelist class="dbus-method" generated="True" extra-ref="ImportTarEx()"/> |
169 | ||
00bb75d7 ZJS |
170 | <variablelist class="dbus-method" generated="True" extra-ref="ImportRaw()"/> |
171 | ||
fd571c9d LP |
172 | <variablelist class="dbus-method" generated="True" extra-ref="ImportRawEx()"/> |
173 | ||
00bb75d7 ZJS |
174 | <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystem()"/> |
175 | ||
fd571c9d LP |
176 | <variablelist class="dbus-method" generated="True" extra-ref="ImportFileSystemEx()"/> |
177 | ||
00bb75d7 ZJS |
178 | <variablelist class="dbus-method" generated="True" extra-ref="ExportTar()"/> |
179 | ||
fd571c9d LP |
180 | <variablelist class="dbus-method" generated="True" extra-ref="ExportTarEx()"/> |
181 | ||
00bb75d7 ZJS |
182 | <variablelist class="dbus-method" generated="True" extra-ref="ExportRaw()"/> |
183 | ||
fd571c9d LP |
184 | <variablelist class="dbus-method" generated="True" extra-ref="ExportRawEx()"/> |
185 | ||
00bb75d7 ZJS |
186 | <variablelist class="dbus-method" generated="True" extra-ref="PullTar()"/> |
187 | ||
fd571c9d LP |
188 | <variablelist class="dbus-method" generated="True" extra-ref="PullTarEx()"/> |
189 | ||
00bb75d7 ZJS |
190 | <variablelist class="dbus-method" generated="True" extra-ref="PullRaw()"/> |
191 | ||
fd571c9d LP |
192 | <variablelist class="dbus-method" generated="True" extra-ref="PullRawEx()"/> |
193 | ||
00bb75d7 ZJS |
194 | <variablelist class="dbus-method" generated="True" extra-ref="ListTransfers()"/> |
195 | ||
fd571c9d LP |
196 | <variablelist class="dbus-method" generated="True" extra-ref="ListTransfersEx()"/> |
197 | ||
00bb75d7 ZJS |
198 | <variablelist class="dbus-method" generated="True" extra-ref="CancelTransfer()"/> |
199 | ||
fd571c9d LP |
200 | <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/> |
201 | ||
43b238f1 | 202 | <variablelist class="dbus-signal" generated="True" extra-ref="TransferNew()"/> |
00bb75d7 | 203 | |
43b238f1 | 204 | <variablelist class="dbus-signal" generated="True" extra-ref="TransferRemoved()"/> |
00bb75d7 ZJS |
205 | |
206 | <!--End of Autogenerated section--> | |
207 | ||
2fe60ff1 ZJS |
208 | <refsect2> |
209 | <title>Methods</title> | |
210 | ||
fd571c9d LP |
211 | <para><function>ImportTar()</function>/<function>ImportTarEx()</function> and |
212 | <function>ImportRaw()</function>/<function>ImportRawEx()</function> import a disk image and place it | |
213 | into the image directory. The first argument should be a file descriptor (opened for reading) referring | |
214 | to the tar or raw file to import. It should reference a file on disk, a pipe or a socket. When | |
215 | <function>ImportTar()</function>/<function>ImportTarEx()</function> is used the file descriptor should | |
216 | refer to a tar file, optionally compressed with <citerefentry project="die-net"><refentrytitle>gzip</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
217 | <citerefentry project="die-net"><refentrytitle>bzip2</refentrytitle><manvolnum>1</manvolnum></citerefentry>, or | |
2fe60ff1 ZJS |
218 | <citerefentry project="die-net"><refentrytitle>xz</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
219 | <command>systemd-importd</command> will detect the used compression scheme (if any) automatically. When | |
fd571c9d LP |
220 | <function>ImportRaw()</function>/<function>ImportRawEx()</function> is used the file descriptor should |
221 | refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with | |
222 | gzip, bzip2 or xz. In either case, if the file is specified as a file descriptor on disk, progress | |
223 | information is generated for the import operation (as in that case we know the total size on disk). If | |
224 | a socket or pipe is specified, progress information is not available. The file descriptor argument is | |
225 | followed by a local name for the image. This should be a name suitable as a hostname and will be used | |
226 | to name the imported image below <filename>/var/lib/machines/</filename>. A tar import is placed as a | |
227 | directory tree or a <citerefentry project="url"><refentrytitle url="https://btrfs.readthedocs.io/en/latest/btrfs.html">btrfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
228 | subvolume below the image directory under the specified name with no suffix appended. A raw import is | |
229 | placed as a file in the image directory with the <filename>.raw</filename> suffix appended. In case of | |
230 | <function>ImportTar()</function>/<function>ImportRaw()</function>, if the <option>force</option> | |
231 | argument is true, any pre-existing image with the same name is removed before starting the | |
232 | operation. Otherwise, the operation fails if an image with the same name already exists. The | |
233 | <option>read_only</option> argument controls whether to create a writable or read-only image. In case | |
234 | of <function>ImportTarEx()</function>/<function>ImportRawEx()</function> these boolean flags are | |
235 | provided via a 64bit flags parameter instead, with bit 0 mapping to the <option>force</option> | |
236 | parameter, and bit 1 mapping to <option>read_only</option>. The <option>class</option> parameter | |
237 | specifies the image class, and takes one of <literal>machine</literal>, <literal>portable</literal>, | |
238 | <literal>sysext</literal>, <literal>confext</literal>. All four methods return immediately after | |
239 | starting the import, with the import transfer ongoing. They return a pair of transfer identifier and | |
240 | object path, which may be used to retrieve progress information about the transfer or to cancel it. The | |
241 | transfer identifier is a simple numeric identifier, the object path references an | |
2fe60ff1 | 242 | <interfacename>org.freedesktop.import1.Transfer</interfacename> object, see below. Listen for a |
43b238f1 | 243 | <function>TransferRemoved()</function> signal for the transfer ID in order to detect when a transfer is |
2fe60ff1 ZJS |
244 | complete. The returned transfer object is useful to determine the current progress or log output of the |
245 | ongoing import operation.</para> | |
246 | ||
fd571c9d LP |
247 | <para><function>ExportTar()</function>/<function>ExportTarEx()</function> and |
248 | <function>ExportRaw()</function>/<function>ExportRaw()</function> implement the reverse operation, and | |
249 | may be used to export a system image in order to place it in a tar or raw image. They take the machine | |
250 | name to export as their first parameter, followed by a file descriptor (opened for writing) where the | |
251 | tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third | |
252 | argument specifies in which compression format to write the image. It takes one of | |
2fe60ff1 ZJS |
253 | <literal>uncompressed</literal>, <literal>xz</literal>, <literal>bzip2</literal> or |
254 | <literal>gzip</literal>, depending on which compression scheme is required. The image written to the | |
fd571c9d LP |
255 | specified file descriptor will be a tar file in case of |
256 | <function>ExportTar()</function>/<function>ExportTarEx()</function> or a raw disk image in case of | |
257 | <function>ExportRaw()</function>/<function>ExportRawEx()</function>. Note that currently raw disk | |
258 | images may not be exported as tar files, and vice versa. This restriction might be lifted | |
259 | eventually. The method returns a transfer identifier and object path for cancelling or tracking the | |
260 | export operation, similarly to <function>ImportTar()</function>/<function>ImportTarEx()</function> or | |
261 | <function>ImportRaw()</function>/<function>ImportRawEx()</function> as described | |
262 | above. <function>ExportTarEx()</function>/<function>ExportRawEx()</function> expect the image class as | |
263 | additional parameter, as well as a 64bit flags parameter that currently must be specified as | |
264 | zero.</para> | |
265 | ||
266 | <para><function>PullTar()</function>/<function>PullTarEx()</function> and | |
267 | <function>PullRaw()</function>/<function>PullRawEx()</function> may be used to download, verify and | |
268 | import a system image from a URL. They take a URL argument which should point to a tar or raw file on | |
269 | the <literal>http://</literal> or <literal>https://</literal> protocols, possibly compressed with xz, | |
270 | bzip2 or gzip. The second argument is a local name for the image. It should be suitable as a hostname, | |
271 | similarly to the matching argument of the | |
272 | <function>ImportTar()</function>/<function>ImportTarEx()</function> and | |
273 | <function>ImportRaw()</function>/<function>ImportRawEx()</function> methods above. The third argument | |
274 | indicates the verification mode for the image. It may be one of <literal>no</literal>, | |
275 | <literal>checksum</literal>, <literal>signature</literal>. <literal>no</literal> turns off any kind of | |
276 | verification of the image; <literal>checksum</literal> looks for a <filename>SHA256SUM</filename> file | |
277 | next to the downloaded image and verifies any SHA256 hash value in that file against the image; | |
278 | <literal>signature</literal> does the same but also tries to authenticate the | |
279 | <filename>SHA256SUM</filename> file via <citerefentry project="man-pages"><refentrytitle>gpg</refentrytitle><manvolnum>8</manvolnum></citerefentry> first. In | |
280 | case of <function>PullTar()</function>/<function>PullRaw()</function> the last argument indicates | |
281 | whether to replace a possibly pre-existing image with the same local name (if <literal>true</literal>), | |
282 | or whether to fail (if <literal>false</literal>). In case of | |
283 | <function>PullTarEx()</function>/<function>PullRawEx()</function> the last argument is a 64bit flags | |
284 | parameter, where bit 0 controls the <literal>force</literal> flag, bit 1 is a | |
285 | <literal>read_only</literal> flag that controls whether the created image shall be marked read-only, | |
286 | and bit 2 is a <literal>keep_download</literal> flag that indicates whether a pristine, read-only copy | |
287 | of the downloaded image shell be kept, in addition for the local copy of the image. The | |
288 | <function>…_Ex()</function> variants also expect an image class string (as above). Like the import and | |
289 | export calls above, these calls return a pair of transfer identifier and object path for the ongoing | |
2fe60ff1 ZJS |
290 | download.</para> |
291 | ||
fd571c9d LP |
292 | <para><function>ImportFileSystem()</function>/<function>ImportFileSystemEx()</function> are similar to |
293 | <function>ImportTar()</function>/<function>ImportTarEx()</function> but import a directory tree. The | |
294 | first argument must refer to a directory file descriptor for the source hierarchy to import.</para> | |
295 | ||
296 | <para><function>ListTransfers()</function>/<function>ListTransfersEx()</function> return a list of | |
297 | ongoing import, export or download operations as created with the six calls described above. They | |
298 | return an array of structures which consist of the numeric transfer identifier, a string indicating the | |
299 | operation (one of <literal>import-tar</literal>, <literal>import-raw</literal>, | |
300 | <literal>export-tar</literal>, <literal>export-raw</literal>, <literal>pull-tar</literal> or | |
301 | <literal>pull-raw</literal>), a string describing the remote file (in case of download operations this | |
302 | is the source URL, in case of import/export operations this is a short string describing the file | |
303 | descriptor passed in), a string with the local machine image name, the image class (only in case of | |
304 | <function>ListTransfersEx()</function>; one of <literal>machine</literal>, <literal>portable</literal>, | |
305 | <literal>sysext</literal>, <literal>confext</literal>), a progress value between 0.0 (for 0%) and 1.0 | |
306 | (for 100%), as well as the transfer object path.</para> | |
2fe60ff1 ZJS |
307 | |
308 | <para><function>CancelTransfer()</function> may be used to cancel an ongoing import, export or download | |
b441a1d4 | 309 | operation. Simply specify the transfer identifier to cancel the ongoing operation.</para> |
fd571c9d LP |
310 | |
311 | <para><function>ListImages()</function> returns a list of currently installed images. It takes a image | |
312 | class string and a flags parameter. The image class is either the empty string or specifies one of the | |
313 | four image classes, by which it will then filter. The flags parameter must be zero at this time. It | |
314 | returns an array of items, each describing one image. The item fields are in order: the image class, | |
315 | the local image name, the image type, the image path, the read-only flag, the creation and modification | |
316 | times (in microseconds since the UNIX epoch), as well as the current disk usage in bytes (both overall, | |
317 | and exclusive), as well as any size limit in bytes set on the image (both overall and | |
318 | exclusive).</para> | |
2fe60ff1 ZJS |
319 | </refsect2> |
320 | ||
321 | <refsect2> | |
322 | <title>Signals</title> | |
323 | ||
43b238f1 | 324 | <para>The <function>TransferNew()</function> signal is generated each time a new transfer is started with |
b441a1d4 DDM |
325 | the import, export or download calls described above. It carries the transfer ID and object path that |
326 | have just been created.</para> | |
2fe60ff1 | 327 | |
43b238f1 | 328 | <para>The <function>TransferRemoved()</function> signal is sent each time a transfer finishes, |
b441a1d4 | 329 | is canceled or fails. It also carries the transfer ID and object path, followed by a string indicating |
2fe60ff1 ZJS |
330 | the result of the operation, which is one of <literal>done</literal> (on success), |
331 | <literal>canceled</literal> or <literal>failed</literal>.</para> | |
332 | </refsect2> | |
333 | </refsect1> | |
334 | ||
335 | <refsect1> | |
336 | <title>The Transfer Object</title> | |
337 | ||
48f99d7c | 338 | <programlisting executable="systemd-importd" node="/org/freedesktop/import1/transfer/_1" interface="org.freedesktop.import1.Transfer"> |
2fe60ff1 ZJS |
339 | node /org/freedesktop/import1/transfer/_1 { |
340 | interface org.freedesktop.import1.Transfer { | |
341 | methods: | |
342 | Cancel(); | |
343 | signals: | |
344 | LogMessage(u priority, | |
345 | s line); | |
fd571c9d | 346 | ProgressUpdate(d progress); |
2fe60ff1 | 347 | properties: |
4fb222c4 ZJS |
348 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
349 | readonly u Id = ...; | |
350 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
351 | readonly s Local = '...'; | |
352 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
353 | readonly s Remote = '...'; | |
354 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
355 | readonly s Type = '...'; | |
356 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
357 | readonly s Verify = '...'; | |
358 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
359 | readonly d Progress = ...; | |
2fe60ff1 | 360 | }; |
4fb222c4 ZJS |
361 | interface org.freedesktop.DBus.Peer { ... }; |
362 | interface org.freedesktop.DBus.Introspectable { ... }; | |
363 | interface org.freedesktop.DBus.Properties { ... }; | |
2fe60ff1 | 364 | }; |
4fb222c4 ZJS |
365 | </programlisting> |
366 | ||
00bb75d7 ZJS |
367 | <!--Autogenerated cross-references for systemd.directives, do not edit--> |
368 | ||
369 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/> | |
370 | ||
371 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.import1.Transfer"/> | |
372 | ||
373 | <variablelist class="dbus-method" generated="True" extra-ref="Cancel()"/> | |
374 | ||
43b238f1 | 375 | <variablelist class="dbus-signal" generated="True" extra-ref="LogMessage()"/> |
00bb75d7 | 376 | |
fd571c9d LP |
377 | <variablelist class="dbus-signal" generated="True" extra-ref="ProgressUpdate()"/> |
378 | ||
00bb75d7 ZJS |
379 | <variablelist class="dbus-property" generated="True" extra-ref="Id"/> |
380 | ||
381 | <variablelist class="dbus-property" generated="True" extra-ref="Local"/> | |
382 | ||
383 | <variablelist class="dbus-property" generated="True" extra-ref="Remote"/> | |
384 | ||
385 | <variablelist class="dbus-property" generated="True" extra-ref="Type"/> | |
386 | ||
387 | <variablelist class="dbus-property" generated="True" extra-ref="Verify"/> | |
388 | ||
389 | <variablelist class="dbus-property" generated="True" extra-ref="Progress"/> | |
390 | ||
391 | <!--End of Autogenerated section--> | |
392 | ||
2fe60ff1 ZJS |
393 | <refsect2> |
394 | <title>Methods</title> | |
395 | ||
396 | <para>The <function>Cancel()</function> method may be used to cancel the transfer. It takes no | |
89fc6fd3 DDM |
397 | parameters. This method is pretty much equivalent to the <function>CancelTransfer()</function> method |
398 | on the <structname>Manager</structname> interface (see above), but is exposed on the | |
2fe60ff1 ZJS |
399 | <structname>Transfer</structname> object itself instead of taking a transfer ID.</para> |
400 | </refsect2> | |
401 | ||
402 | <refsect2> | |
403 | <title>Properties</title> | |
404 | ||
405 | <para>The <varname>Id</varname> property exposes the numeric transfer ID of the transfer object.</para> | |
406 | ||
b441a1d4 | 407 | <para>The <varname>Local</varname>, <varname>Remote</varname> and <varname>Type</varname> properties |
2fe60ff1 | 408 | expose the local container name of this transfer, the remote source (in case of download: the URL, in |
b441a1d4 DDM |
409 | case of import/export: a string describing the file descriptor passed in), and the type of operation |
410 | (see the Manager's <function>ListTransfer()</function> method above for an explanation of the possible | |
2fe60ff1 ZJS |
411 | values).</para> |
412 | ||
b441a1d4 | 413 | <para>The <varname>Verify</varname> property exposes the selected verification setting and is only |
2fe60ff1 ZJS |
414 | defined for download operations (see above).</para> |
415 | ||
b441a1d4 DDM |
416 | <para>The <varname>Progress</varname> property exposes the current progress of the transfer as a value |
417 | between 0.0 and 1.0. To show a progress bar on screen we recommend to query this value in regular | |
2fe60ff1 ZJS |
418 | intervals, for example every 500 ms or so.</para> |
419 | </refsect2> | |
fd571c9d LP |
420 | |
421 | <refsect2> | |
422 | <title>Signals</title> | |
423 | ||
424 | <para>The <function>LogMessage()</function> signal is emitted for log messages generated by a transfer. It | |
425 | carries a pair of syslog log level integer and log string.</para> | |
426 | ||
427 | <para>The <function>ProgressUpdate()</function> signal is emitted in regular intervals when new | |
428 | download progress information is available for a transfer. It carries a double precision floating | |
429 | pointer number between 0.0 and 1.0 indicating the transfer progress.</para> | |
430 | </refsect2> | |
2fe60ff1 ZJS |
431 | </refsect1> |
432 | ||
48f99d7c ZJS |
433 | <refsect1> |
434 | <title>Examples</title> | |
435 | ||
436 | <example> | |
437 | <title>Introspect <interfacename>org.freedesktop.import1.Manager</interfacename> on the bus</title> | |
438 | ||
439 | <programlisting>$ gdbus introspect --system \ | |
440 | --dest org.freedesktop.import1 \ | |
441 | --object-path /org/freedesktop/import1 | |
442 | </programlisting> | |
443 | </example> | |
444 | ||
445 | <example> | |
446 | <title>Introspect <interfacename>org.freedesktop.import1.Transfer</interfacename> on the bus</title> | |
447 | ||
448 | <programlisting>$ gdbus introspect --system \ | |
449 | --dest org.freedesktop.import1 \ | |
450 | --object-path /org/freedesktop/import1/transfer/_1 | |
451 | </programlisting> | |
452 | </example> | |
453 | </refsect1> | |
454 | ||
e4239a34 | 455 | <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> |
fd571c9d LP |
456 | <refsect1> |
457 | <title>History</title> | |
458 | <refsect2> | |
459 | <title>The Manager Object</title> | |
460 | <para><function>ImportTarEx()</function>, <function>ImportRawEx()</function>, | |
461 | <function>ImportFileSystemEx()</function>, <function>ExportTarEx()</function>, | |
462 | <function>ExportRawEx()</function>, <function>PullTarEx()</function>, <function>PullRawEx()</function>, | |
463 | <function>ListTransfersEx()</function>, <function>ListImages()</function> were added in version | |
464 | 256.</para> | |
465 | </refsect2> | |
466 | <refsect2> | |
467 | <title>Transfer Objects</title> | |
468 | <para><function>ProgressUpdate()</function> was added in version 256.</para> | |
469 | </refsect2> | |
470 | </refsect1> | |
471 | ||
2fe60ff1 | 472 | </refentry> |