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 type 'a callback = 'a -> unit
25 (** A callback function in the main thread which is called when the
26 command finishes (successfully).
28 This can also return some data (the ['a] parameter). A command
29 that returns a list of strings might have callback type [string
30 list callback], and a command that returns nothing would have
31 callback type [unit callback].
33 Note that errors are not returned this way. Errors result
34 in the command queue being discarded and the failure_hook
35 function being called. *)
37 val no_callback : 'a callback
38 (** The main thread uses this as a callback if it doesn't care about
39 the return value from a command. *)
41 val connect : string option -> unit callback -> unit
42 (** [connect uri cb] sends the [Connect] message to the slave
45 This causes the slave thread to disconnect from libvirt and
46 connect to the libvirt [uri]. If this succeeds, [cb] is called
49 Although you can connect to remote hosts, libguestfs won't
50 usually be able to see the drives on those hosts, so it normally
51 doesn't make sense to use remote URIs. *)
56 dom_state : Libvirt.Domain.state;
58 (** List of domains as returned in the [Get_domains] message callback.
60 Note that [dom_state] is the state of the domain and should
61 control whether we are allowed to write to the domain's
62 filesystem (disallowed if [dom_state] is not [InfoShutoff]). *)
64 val get_domains : domain list callback -> unit
65 (** [get_domains cb] sends the [Get_domains] message to the
68 This causes the slave thread to retrieve the list of domains
69 from libvirt (active and inactive ones). If this succeeds,
70 [cb] is called in the main thread with the list of
71 domains. See also the {!domain} type. *)
73 type rw_flag = RO | RW
74 (** This flag is passed to open callbacks to indicate whether
75 we could open the disks read-only ([RO]) or read-write ([RW]). *)
77 val open_domain : string -> rw_flag callback -> unit
78 (** [open_domain name cb] sends the [Open_domain] message to the
81 This causes the slave thread to retrieve the list of
82 block devices for the libvirt domain [name], create a
83 libguestfs handle, add those block devices, and launch
84 the handle. If this is successful, then [cb] is called
87 If the domain is live then the disks are opened read only,
88 else they are opened read write if write_flag is true.
89 The [rw_flag] is passed into the callback accordingly.
91 The slave thread must be connected to libvirt (see {!connect})
92 else this command will fail. *)
94 val open_images : string list -> rw_flag callback -> unit
95 (** [open_images images cb] is like {!open_domain} except
96 that it opens local disk image(s) directly. *)
103 vol_statvfs : Guestfs.statvfs;
105 (** The volume structure which is passed to the {!get_volumes} callback. *)
107 val get_volumes : volume callback -> unit
108 (** [get_volumes cb] sends the [Get_volumes] message to the
111 This causes the slave thread to examine all partitions, LVs
112 etc within the current disk image, and for each that contains
113 a mountable filesystem, [cb] is called. (Note [cb] can be
114 called multiple times). *)
117 dent_name : string; (** Basename in directory. *)
118 dent_stat : Guestfs.stat; (** stat(2) for this entry. *)
119 dent_link : string; (** (for symlinks only) readlink(2). *)
122 val read_directory : string -> string -> direntry list callback -> unit
123 (** [read_directory dev dir cb] sends the [Read_directory] message
126 This causes the slave thread to read the contents of the
127 directory [dir] from volume [dev], and call [cb] with the
128 complete result. If [dir] is not a directory then this
131 Note that [.] and [..] entries are not included in the result,
132 and the list is sorted on the [filename] field. *)
134 val discard_command_queue : unit -> unit
135 (** [discard_command_queue ()] discards any commands on the command
136 queue. The currently running command is not (and can not be)
139 val exit_thread : unit -> unit
140 (** [exit_thread ()] causes the slave thread to exit, and returns
141 once it has exited. *)
145 Hooks are like callbacks, except they hook into special events
146 that happen in the slave threads, rather than just being a
147 response to commands.
149 The other difference is that hooks are global variables. You can
150 only set one hook of each type.
152 {!set_failure_hook} is used to catch errors in slave commands
153 and display those in the main thread.
155 {!set_busy_hook} and {!set_idle_hook} are used to implement a
158 val set_failure_hook : exn callback -> unit
159 (** Set the function in the main thread which is called if there is
160 an error in the slave thread. If this is not set then errors
161 are discarded. [exn] is the exception. *)
163 val set_busy_hook : unit callback -> unit
164 (** Set the function in the main thread which is called whenever
165 the slave thread starts working on a command. *)
167 val set_idle_hook : unit callback -> unit
168 (** Set the function in the main thread which is called whenever
169 the slave thread stops working on a command {i and} has no
170 more commands left in the queue to work on. *)