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     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.
  27
  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.
  32
  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
  39     sequence.
  40
  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
  45     documentation below).
  46 *)
  47
  48 type 'a callback = 'a -> unit
  49   (** A callback function in the main thread which is called when the
  50       command finishes successfully.
  51
  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].
  56
  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}. *)
  61
  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. *)
  65
  66 type domain = {
  67   dom_id : int;
  68   dom_name : string;
  69   dom_state : Libvirt.Domain.state;
  70 }
  71     (** List of domains as returned in the {!connect} callback. *)
  72
  73 val connect : ?fail:exn callback -> string option -> domain list callback -> unit
  74   (** [connect uri cb] causes the slave thread to disconnect from
  75       libvirt and connect to the libvirt [uri].  If this succeeds,
  76       then the list of all domains fetched from libvirt and [cb] is
  77       called in the main thread.
  78
  79       Although you can connect to remote hosts, libguestfs won't
  80       usually be able to see the drives on those hosts, so it normally
  81       doesn't make sense to use remote URIs.
  82
  83       If [fail] is passed, then failures cause this callback to
  84       be called.  If not, the global failure hook is called. *)
  85
  86 type inspection_data = {
  87   insp_all_filesystems : (string * string) list;
  88   (** see {!Guestfs.list_filesystems} *)
  89   insp_oses : inspection_os list;
  90   (** one entry per root (operating system), see {!Guestfs.inspect_os} *)
  91 }
  92     (** The inspection data returned in the callback from
  93         {!open_domain} and {!open_images}. *)
  94 and inspection_os = {
  95   insp_root : string;                 (** see {!Guestfs.inspect_os} *)
  96   insp_arch : string;
  97   insp_distro : string;
  98   insp_filesystems : string array;
  99   insp_hostname : string;
 100   insp_major_version : int;
 101   insp_minor_version : int;
 102   insp_mountpoints : (string * string) list;
 103   insp_package_format : string;
 104   insp_package_management : string;
 105   insp_product_name : string;
 106   insp_type : string;
 107   insp_windows_systemroot : string option;
 108   insp_winreg_DEFAULT : string option;   (* registry files *)
 109   insp_winreg_SAM : string option;
 110   insp_winreg_SECURITY : string option;
 111   insp_winreg_SOFTWARE : string option;
 112   insp_winreg_SYSTEM : string option;
 113 }
 114
 115 val open_domain : ?fail:exn callback -> string -> inspection_data callback -> unit
 116   (** [open_domain name cb] retrieves the list of block devices for
 117       the libvirt domain [name], creates a libguestfs handle, adds
 118       those block devices, launches the handle, and performs
 119       inspection.
 120
 121       If this is successful, then [cb] is called in the main thread
 122       with the list of filesystems and the results of inspection.
 123
 124       The slave thread must be connected to libvirt (see {!connect})
 125       else this command will fail.
 126
 127       If [fail] is passed, then failures cause this callback to
 128       be called.  If not, the global failure hook is called. *)
 129
 130 val open_images : ?fail:exn callback -> (string * string option) list -> inspection_data callback -> unit
 131   (** [open_images images cb] is like {!open_domain} except that it
 132       opens local disk image(s) directly.  [images] is a list of
 133       [(filename, format)] pairs.
 134
 135       If [fail] is passed, then failures cause this callback to
 136       be called.  If not, the global failure hook is called. *)
 137
 138 type source = OS of inspection_os | Volume of string
 139   (** Source type used by {!read_directory}. *)
 140
 141 type direntry = {
 142   dent_name : string;          (** Basename in directory. *)
 143   dent_stat : Guestfs.stat;    (** stat(2) for this entry. *)
 144   dent_link : string;          (** (for symlinks only) readlink(2). *)
 145 }
 146     (** Directory entry returned by {!read_directory}. *)
 147
 148 val read_directory : ?fail:exn callback -> source -> string -> direntry list callback -> unit
 149   (** [read_directory src dir cb] reads the contents of the directory
 150       [dir] from source [src], and calls the callback function [cb]
 151       with the resulting list of directory entries, if successful.
 152
 153       The source may be either a filesystem (if [src] is [Volume
 154       dev]), or a fully mounted up operating system (if [src] is [OS ...]).
 155       In the second case all the mountpoints of the operating system
 156       are mounted up so that the path may span mountpoints in the
 157       natural way.
 158
 159       If [fail] is passed, then failures cause this callback to
 160       be called.  If not, the global failure hook is called. *)
 161
 162 val download_file : ?fail:exn callback -> source -> string -> string -> unit callback -> unit
 163   (** [download_file src pathname localfile cb] downloads [pathname]
 164       to the named local file, and then calls the callback function. *)
 165
 166 type download_dir_tarball_format = Tar | TGZ | TXZ
 167
 168 val download_dir_tarball : ?fail:exn callback -> source -> string -> download_dir_tarball_format -> string -> unit callback -> unit
 169   (** [download_dir_tarball_format src pathname format localfile cb]
 170       downloads directory [pathname] to the named local file (a
 171       tarball), and then calls the callback function.
 172
 173       [format] controls the download format, which is one of
 174       uncompressed tar, gzip-compressed tar, or xz-compressed tar. *)
 175
 176 val download_dir_find0 : ?fail:exn callback -> source -> string -> string -> unit callback -> unit
 177   (** [download_dir_find0 src pathname localfile cb] downloads the
 178       list of filenames of directory [pathname] to the named local
 179       file (a ASCII NUL-separated text file), and then calls the
 180       callback function. *)
 181
 182 val disk_usage : ?fail:exn callback -> source -> string -> int64 callback -> unit
 183   (** [disk_usage src pathname cb] calculates the disk usage of
 184       directory [pathname] and calls the callback with the answer
 185       (size of {b kilobytes}). *)
 186
 187 val discard_command_queue : unit -> unit
 188   (** [discard_command_queue ()] discards any commands on the command
 189       queue.
 190
 191       The currently running command cannot be discarded (because of
 192       the design of libguestfs).  Instead the callback is discarded,
 193       so from the point of view of the main thread, the effect is
 194       similar. *)
 195
 196 val exit_thread : unit -> unit
 197   (** [exit_thread ()] causes the slave thread to exit, and returns
 198       once it has exited. *)
 199
 200 (** {2 Hooks}
 201
 202     Hooks are like callbacks, except they hook into special events
 203     that happen in the slave thread, rather than just being a response
 204     to commands.
 205
 206     The other difference is that hooks are global variables.  You can
 207     only set one hook of each type.
 208
 209     {!set_failure_hook} is used to catch errors in slave commands
 210     and display those in the main thread.
 211
 212     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 213     "throbber".
 214
 215     {!set_progress_hook} is used to implement a progress bar. *)
 216
 217 val set_failure_hook : exn callback -> unit
 218   (** Set the function in the main thread which is called if there is
 219       an error in the slave thread.  If this is not set then errors
 220       are discarded.  [exn] is the exception. *)
 221
 222 val set_busy_hook : unit callback -> unit
 223   (** Set the function in the main thread which is called whenever
 224       the slave thread starts working on a command. *)
 225
 226 val set_idle_hook : unit callback -> unit
 227   (** Set the function in the main thread which is called whenever
 228       the slave thread stops working on a command {i and} has no
 229       more commands left in the queue to work on. *)
 230
 231 val set_status_hook : string callback -> unit
 232   (** Set the function in the main thread which is called to
 233       update the status bar.  The slave thread updates the
 234       status bar when an operation starts or stops, keeping the
 235       user informed of what is happening. *)
 236
 237 val set_progress_hook : (int64 * int64) callback -> unit
 238   (** Set the function in the main thread which is called whenever
 239       the slave thread receives a progress notification message
 240       from libguestfs. *)