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 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. *)
  70
  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.
  76
  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.
  80
  81       If [fail] is passed, then failures cause this callback to
  82       be called.  If not, the global failure hook is called. *)
  83
  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}). *)
  88
  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.
  93
  94       [format] controls the download format, which is one of
  95       uncompressed tar, gzip-compressed tar, or xz-compressed tar. *)
  96
  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. *)
 102
 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. *)
 106
 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. *)
 111
 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]. *)
 115
 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]. *)
 119
 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. *)
 123
 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
 128       inspection.
 129
 130       If this is successful, then [cb] is called in the main thread
 131       with the list of filesystems and the results of inspection.
 132
 133       The slave thread must be connected to libvirt (see {!connect})
 134       else this command will fail.
 135
 136       If [fail] is passed, then failures cause this callback to
 137       be called.  If not, the global failure hook is called. *)
 138
 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.
 143
 144       If [fail] is passed, then failures cause this callback to
 145       be called.  If not, the global failure hook is called. *)
 146
 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.
 151
 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
 156       natural way.
 157
 158       If [fail] is passed, then failures cause this callback to
 159       be called.  If not, the global failure hook is called. *)
 160
 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. *)
 164
 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. *)
 171
 172 val discard_command_queue : unit -> unit
 173   (** [discard_command_queue ()] discards any commands on the command
 174       queue.
 175
 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
 179       similar. *)
 180
 181 val exit_thread : unit -> unit
 182   (** [exit_thread ()] causes the slave thread to exit, and returns
 183       once it has exited. *)
 184
 185 (** {2 Hooks}
 186
 187     Hooks are like callbacks, except they hook into special events
 188     that happen in the slave thread, rather than just being a response
 189     to commands.
 190
 191     The other difference is that hooks are global variables.  You can
 192     only set one hook of each type.
 193
 194     {!set_failure_hook} is used to catch errors in slave commands
 195     and display those in the main thread.
 196
 197     {!set_busy_hook} and {!set_idle_hook} are used to implement a
 198     "throbber".
 199
 200     {!set_progress_hook} is used to implement a progress bar. *)
 201
 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. *)
 206
 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. *)
 210
 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. *)
 215
 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. *)
 221
 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
 225       from libguestfs. *)