2 * Copyright (C) 2010 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 (** The public interface to the slave thread.
20 Please see HACKING file. *)
22 (** {2 Commands and callbacks}
24 Commands for libvirt and libguestfs are executed in a separate slave
25 thread. This file describes the interface with that thread that the
26 rest of the program sees.
28 Commands are intentionally as high level as possible. Often a
29 single command may perform many libvirt and libguestfs operations
30 before returing a result. This is to make use of the slave thread
31 as simple as possible.
33 Commands are executed in a "continuation-passing style" (CPS),
34 which means that you call a function to issue the command, passing
35 in a callback ("continuation"). The function returns immediately.
36 The callback may be called some time later once the issued command
37 completes successfully. Several commands can be queued up for
38 execution. Commands are executed and callbacks are performed in
41 The callback returns the result of the command. The callback does
42 not get invoked if there was an error, or if the command was
43 cancelled before it runs (see {!discard_command_queue}). For some
44 commands the callback can be called multiple times (see
48 type 'a callback = 'a -> unit
49 (** A callback function in the main thread which is called when the
50 command finishes successfully.
52 This can also return some data (the ['a] parameter). A command
53 that returns a list of strings might have callback type [string
54 list callback], and a command that returns nothing would have
55 callback type [unit callback].
57 Note that errors are not returned this way. Each function can
58 optionally supply an extra callback to handle errors, or if
59 not supplied then it defaults to the failure hook set by
60 {!set_failure_hook}. *)
62 val no_callback : 'a callback
63 (** The main thread uses this as a callback if it doesn't care about
64 the return value from a command. *)
66 val checksum_file : ?fail:exn callback -> Slave_types.source -> string -> string -> string callback -> unit
67 (** [checksum_file src pathname csumtype cb] calculates the checksum
68 of the file [pathname]. [csumtype] is one of the types
69 supported by libguestfs. *)
71 val connect : ?fail:exn callback -> string option -> Slave_types.domain list callback -> unit
72 (** [connect uri cb] causes the slave thread to disconnect from
73 libvirt and connect to the libvirt [uri]. If this succeeds,
74 then the list of all domains fetched from libvirt and [cb] is
75 called in the main thread.
77 Although you can connect to remote hosts, libguestfs won't
78 usually be able to see the drives on those hosts, so it normally
79 doesn't make sense to use remote URIs.
81 If [fail] is passed, then failures cause this callback to
82 be called. If not, the global failure hook is called. *)
84 val disk_usage : ?fail:exn callback -> Slave_types.source -> string -> int64 callback -> unit
85 (** [disk_usage src pathname cb] calculates the disk usage of
86 directory [pathname] and calls the callback with the answer
87 (size of {b kilobytes}). *)
89 val download_dir_tarball : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.download_dir_tarball_format -> string -> unit callback -> unit
90 (** [download_dir_tarball_format src pathname format localfile cb]
91 downloads directory [pathname] to the named local file (a
92 tarball), and then calls the callback function.
94 [format] controls the download format, which is one of
95 uncompressed tar, gzip-compressed tar, or xz-compressed tar. *)
97 val download_dir_find0 : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
98 (** [download_dir_find0 src pathname localfile cb] downloads the
99 list of filenames of directory [pathname] to the named local
100 file (a ASCII NUL-separated text file), and then calls the
101 callback function. *)
103 val download_file : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
104 (** [download_file src pathname localfile cb] downloads [pathname]
105 to the named local file, and then calls the callback function. *)
107 val download_file_if_not_exist : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
108 (** Like {!download_file} except that if [localfile] already exists
109 then the download is skipped. You can use this to implement
110 caching of remote files. *)
112 val file_information : ?fail:exn callback -> Slave_types.source -> string -> string callback -> unit
113 (** [file_information src pathname cb] calculates the file
114 information of the file [pathname]. *)
116 val file_xattrs : ?fail:exn callback -> Slave_types.source -> string -> Guestfs.xattr array callback -> unit
117 (** [file_xattrs src pathname cb] returns the extended
118 attributes of the file [pathname]. *)
120 val list_applications : ?fail:exn callback -> Slave_types.inspection_os -> Guestfs.application array callback -> unit
121 (** [list_applications os cb] lists the applications in the
122 guest using libguestfs inspection. *)
124 val open_domain : ?fail:exn callback -> string -> Slave_types.inspection_data callback -> unit
125 (** [open_domain name cb] retrieves the list of block devices for
126 the libvirt domain [name], creates a libguestfs handle, adds
127 those block devices, launches the handle, and performs
130 If this is successful, then [cb] is called in the main thread
131 with the list of filesystems and the results of inspection.
133 The slave thread must be connected to libvirt (see {!connect})
134 else this command will fail.
136 If [fail] is passed, then failures cause this callback to
137 be called. If not, the global failure hook is called. *)
139 val open_images : ?fail:exn callback -> (string * string option) list -> Slave_types.inspection_data callback -> unit
140 (** [open_images images cb] is like {!open_domain} except that it
141 opens local disk image(s) directly. [images] is a list of
142 [(filename, format)] pairs.
144 If [fail] is passed, then failures cause this callback to
145 be called. If not, the global failure hook is called. *)
147 val read_directory : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.direntry list callback -> unit
148 (** [read_directory src dir cb] reads the contents of the directory
149 [dir] from source [src], and calls the callback function [cb]
150 with the resulting list of directory entries, if successful.
152 The source may be either a filesystem (if [src] is [Volume
153 dev]), or a fully mounted up operating system (if [src] is [OS ...]).
154 In the second case all the mountpoints of the operating system
155 are mounted up so that the path may span mountpoints in the
158 If [fail] is passed, then failures cause this callback to
159 be called. If not, the global failure hook is called. *)
161 val reopen : ?fail:exn callback -> Slave_types.inspection_data callback -> unit
162 (** [reopen cb] reruns the last {!open_domain} or {!open_images}
163 command, if there was one. *)
165 val run_command : ?fail:exn callback -> string -> unit callback -> unit
166 (** [run_command cmd] runs an external command [cmd]. This is
167 useful for possibly long-running commands as it keeps the
168 display interactive. Be careful to quote arguments in the
169 command properly (see {!Filename.quote}). The external command
170 must eventually terminate and must not wait for user input. *)
172 val discard_command_queue : unit -> unit
173 (** [discard_command_queue ()] discards any commands on the command
176 The currently running command cannot be discarded (because of
177 the design of libguestfs). Instead the callback is discarded,
178 so from the point of view of the main thread, the effect is
181 val exit_thread : unit -> unit
182 (** [exit_thread ()] causes the slave thread to exit, and returns
183 once it has exited. *)
187 Hooks are like callbacks, except they hook into special events
188 that happen in the slave thread, rather than just being a response
191 The other difference is that hooks are global variables. You can
192 only set one hook of each type.
194 {!set_failure_hook} is used to catch errors in slave commands
195 and display those in the main thread.
197 {!set_busy_hook} and {!set_idle_hook} are used to implement a
200 {!set_progress_hook} is used to implement a progress bar. *)
202 val set_failure_hook : exn callback -> unit
203 (** Set the function in the main thread which is called if there is
204 an error in the slave thread. If this is not set then errors
205 are discarded. [exn] is the exception. *)
207 val set_busy_hook : unit callback -> unit
208 (** Set the function in the main thread which is called whenever
209 the slave thread starts working on a command. *)
211 val set_idle_hook : unit callback -> unit
212 (** Set the function in the main thread which is called whenever
213 the slave thread stops working on a command {i and} has no
214 more commands left in the queue to work on. *)
216 val set_status_hook : string callback -> unit
217 (** Set the function in the main thread which is called to
218 update the status bar. The slave thread updates the
219 status bar when an operation starts or stops, keeping the
220 user informed of what is happening. *)
222 val set_progress_hook : (int64 * int64) callback -> unit
223 (** Set the function in the main thread which is called whenever
224 the slave thread receives a progress notification message