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 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)
 137       stopped. *)
 138
 139 val exit_thread : unit -> unit
 140   (** [exit_thread ()] causes the slave thread to exit, and returns
 141       once it has exited. *)
 142
 143 (** {2 Hooks}
 144
 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.
 148
 149     The other difference is that hooks are global variables.  You can
 150     only set one hook of each type.
 151
 152     {!set_failure_hook} is used to catch errors in slave commands
 153     and display those in the main thread.
 154
 155     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 156     "throbber". *)
 157
 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. *)
 162
 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. *)
 166
 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. *)