slave.mli

   1 (* Guestfs Browser.
   2  * Copyright (C) 2010 Red Hat Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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.
  17  *)
  18
  19 (** The public interface to the slave thread.
  20     Please see HACKING file. *)
  21
  22 (** {2 Commands and callbacks} *)
  23
  24 type 'a callback = 'a -> unit
  25   (** A callback function in the main thread which is called when the
  26       command finishes (successfully).
  27
  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].
  32
  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. *)
  36
  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. *)
  40
  41 val connect : string option -> unit callback -> unit
  42   (** [connect uri cb] sends the [Connect] message to the slave
  43       thread.
  44
  45       This causes the slave thread to disconnect from libvirt and
  46       connect to the libvirt [uri].  If this succeeds, [cb] is called
  47       in the main thread.
  48
  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. *)
  52
  53 type domain = {
  54   dom_id : int;
  55   dom_name : string;
  56   dom_state : Libvirt.Domain.state;
  57 }
  58     (** List of domains as returned in the [Get_domains] message callback.
  59
  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]). *)
  63
  64 val get_domains : domain list callback -> unit
  65   (** [get_domains cb] sends the [Get_domains] message to the
  66       slave thread.
  67
  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. *)
  72
  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]). *)
  76
  77 val open_domain : string -> rw_flag callback -> unit
  78   (** [open_domain name cb] sends the [Open_domain] message to the
  79       slave thread.
  80
  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
  85       in the main thread.
  86
  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.
  90
  91       The slave thread must be connected to libvirt (see {!connect})
  92       else this command will fail. *)
  93
  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. *)
  97
  98 type volume = {
  99   vol_device : string;
 100   vol_type : string;
 101   vol_label : string;
 102   vol_uuid : string;
 103   vol_statvfs : Guestfs.statvfs;
 104 }
 105     (** The volume structure which is passed to the {!get_volumes} callback. *)
 106
 107 val get_volumes : volume callback -> unit
 108   (** [get_volumes cb] sends the [Get_volumes] message to the
 109       slave thread.
 110
 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). *)
 115
 116 type direntry = {
 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). *)
 120 }
 121
 122 val read_directory : string -> string -> direntry list callback -> unit
 123   (** [read_directory dev dir cb] sends the [Read_directory] message
 124       to the slave thread.
 125
 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
 129       is an error.
 130
 131       Note that [.] and [..] entries are not included in the result,
 132       and the list is sorted on the [filename] field. *)
 133
 134 val disk_usage : string -> string -> int64 callback -> unit
 135   (** [disk_usage dev dir cb] sends the [Disk_usage] message to the
 136       slave thread.
 137
 138       This causes the slave thread to estimate the disk usage of the
 139       directory (or file) [dir] from volume [dev], and call [cb] with
 140       the result (size in {b kilobytes}). *)
 141
 142 type export_t =
 143   | Export_tar                      (** uncompressed tar archive *)
 144   | Export_tgz                      (** gzip compressed tar archive *)
 145   | Export_checksums of string      (** checksums using algorithm *)
 146   | Export_list                     (** list of file names, \0-separated *)
 147       (** Export format used by {!export_dir_to}. *)
 148
 149 val export_dir_to : export_t -> string -> string -> string -> unit callback -> unit
 150   (** [export_dir_to t dev dir file cb] sends the [Export_dir_to] message
 151       to the slave thread.
 152
 153       This causes the slave thread to export the directory [dir] on
 154       device [dev] to the host file called [file].  The precise
 155       operation (ie. what is exported) is controlled by the type
 156       [export_t].  When the export has been completed, the callback
 157       [cb] is called in the main thread.
 158
 159       Libguestfs doesn't offer any way to view progress of this
 160       operation, which could potentially take a long time. *)
 161
 162 val discard_command_queue : unit -> unit
 163   (** [discard_command_queue ()] discards any commands on the command
 164       queue.  The currently running command is not (and can not be)
 165       stopped. *)
 166
 167 val exit_thread : unit -> unit
 168   (** [exit_thread ()] causes the slave thread to exit, and returns
 169       once it has exited. *)
 170
 171 (** {2 Hooks}
 172
 173     Hooks are like callbacks, except they hook into special events
 174     that happen in the slave threads, rather than just being a
 175     response to commands.
 176
 177     The other difference is that hooks are global variables.  You can
 178     only set one hook of each type.
 179
 180     {!set_failure_hook} is used to catch errors in slave commands
 181     and display those in the main thread.
 182
 183     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 184     "throbber". *)
 185
 186 val set_failure_hook : exn callback -> unit
 187   (** Set the function in the main thread which is called if there is
 188       an error in the slave thread.  If this is not set then errors
 189       are discarded.  [exn] is the exception. *)
 190
 191 val set_busy_hook : unit callback -> unit
 192   (** Set the function in the main thread which is called whenever
 193       the slave thread starts working on a command. *)
 194
 195 val set_idle_hook : unit callback -> unit
 196   (** Set the function in the main thread which is called whenever
 197       the slave thread stops working on a command {i and} has no
 198       more commands left in the queue to work on. *)