Add progress bar.

[guestfs-browser.git] / slave.mli

diff --git a/slave.mli b/slave.mli
index d36ef04..940de14 100644 (file)
--- a/slave.mli
+++ b/slave.mli
@@ -54,9 +54,10 @@ type 'a callback = 'a -> unit
       list callback], and a command that returns nothing would have
       callback type [unit callback].
 
       list callback], and a command that returns nothing would have
       callback type [unit callback].
 

-      Note that errors are not returned this way.  Errors result
-      in the command queue being discarded and the failure_hook
-      function being called. *)
+      Note that errors are not returned this way.  Each function can
+      optionally supply an extra callback to handle errors, or if
+      not supplied then it defaults to the failure hook set by
+      {!set_failure_hook}. *)

 
 val no_callback : 'a callback
   (** The main thread uses this as a callback if it doesn't care about
 
 val no_callback : 'a callback
   (** The main thread uses this as a callback if it doesn't care about


@@ -69,7 +70,7 @@ type domain = {
 }
     (** List of domains as returned in the {!connect} callback. *)
 
 }
     (** List of domains as returned in the {!connect} callback. *)
 

-val connect : string option -> domain list callback -> unit
+val connect : ?fail:exn callback -> string option -> domain list callback -> unit

   (** [connect uri cb] causes the slave thread to disconnect from
       libvirt and connect to the libvirt [uri].  If this succeeds,
       then the list of all domains fetched from libvirt and [cb] is
   (** [connect uri cb] causes the slave thread to disconnect from
       libvirt and connect to the libvirt [uri].  If this succeeds,
       then the list of all domains fetched from libvirt and [cb] is


@@ -77,7 +78,10 @@ val connect : string option -> domain list callback -> unit
 
       Although you can connect to remote hosts, libguestfs won't
       usually be able to see the drives on those hosts, so it normally
 
       Although you can connect to remote hosts, libguestfs won't
       usually be able to see the drives on those hosts, so it normally

-      doesn't make sense to use remote URIs. *)
+      doesn't make sense to use remote URIs.
+
+      If [fail] is passed, then failures cause this callback to
+      be called.  If not, the global failure hook is called. *)

 
 type inspection_data = {
   insp_all_filesystems : (string * string) list;
 
 type inspection_data = {
   insp_all_filesystems : (string * string) list;


@@ -103,7 +107,7 @@ and inspection_os = {
   insp_windows_systemroot : string option;
 }
 
   insp_windows_systemroot : string option;
 }
 

-val open_domain : string -> inspection_data callback -> unit
+val open_domain : ?fail:exn callback -> string -> inspection_data callback -> unit

   (** [open_domain name cb] retrieves the list of block devices for
       the libvirt domain [name], creates a libguestfs handle, adds
       those block devices, launches the handle, and performs
   (** [open_domain name cb] retrieves the list of block devices for
       the libvirt domain [name], creates a libguestfs handle, adds
       those block devices, launches the handle, and performs


@@ -113,11 +117,18 @@ val open_domain : string -> inspection_data callback -> unit
       with the list of filesystems and the results of inspection.
 
       The slave thread must be connected to libvirt (see {!connect})
       with the list of filesystems and the results of inspection.
 
       The slave thread must be connected to libvirt (see {!connect})

-      else this command will fail. *)
+      else this command will fail.
+
+      If [fail] is passed, then failures cause this callback to
+      be called.  If not, the global failure hook is called. *)

 
 

-val open_images : string list -> inspection_data callback -> unit
-  (** [open_images images cb] is like {!open_domain} except
-      that it opens local disk image(s) directly. *)
+val open_images : ?fail:exn callback -> (string * string option) list -> inspection_data callback -> unit
+  (** [open_images images cb] is like {!open_domain} except that it
+      opens local disk image(s) directly.  [images] is a list of
+      [(filename, format)] pairs.
+
+      If [fail] is passed, then failures cause this callback to
+      be called.  If not, the global failure hook is called. *)

 
 type source = OS of inspection_os | Volume of string
   (** Source type used by {!read_directory}. *)
 
 type source = OS of inspection_os | Volume of string
   (** Source type used by {!read_directory}. *)


@@ -129,7 +140,7 @@ type direntry = {
 }
     (** Directory entry returned by {!read_directory}. *)
 
 }
     (** Directory entry returned by {!read_directory}. *)
 

-val read_directory : source -> string -> direntry list callback -> unit
+val read_directory : ?fail:exn callback -> source -> string -> direntry list callback -> unit

   (** [read_directory src dir cb] reads the contents of the directory
       [dir] from source [src], and calls the callback function [cb]
       with the resulting list of directory entries, if successful.
   (** [read_directory src dir cb] reads the contents of the directory
       [dir] from source [src], and calls the callback function [cb]
       with the resulting list of directory entries, if successful.


@@ -138,7 +149,10 @@ val read_directory : source -> string -> direntry list callback -> unit
       dev]), or a fully mounted up operating system (if [src] is [OS ...]).
       In the second case all the mountpoints of the operating system
       are mounted up so that the path may span mountpoints in the
       dev]), or a fully mounted up operating system (if [src] is [OS ...]).
       In the second case all the mountpoints of the operating system
       are mounted up so that the path may span mountpoints in the

-      natural way. *)
+      natural way.
+
+      If [fail] is passed, then failures cause this callback to
+      be called.  If not, the global failure hook is called. *)

 
 val discard_command_queue : unit -> unit
   (** [discard_command_queue ()] discards any commands on the command
 
 val discard_command_queue : unit -> unit
   (** [discard_command_queue ()] discards any commands on the command


@@ -166,7 +180,9 @@ val exit_thread : unit -> unit
     and display those in the main thread.
 
     {!set_busy_hook} and {!set_idle_hook} are used to implement a
     and display those in the main thread.
 
     {!set_busy_hook} and {!set_idle_hook} are used to implement a

-    "throbber". *)
+    "throbber".
+
+    {!set_progress_hook} is used to implement a progress bar. *)

 
 val set_failure_hook : exn callback -> unit
   (** Set the function in the main thread which is called if there is
 
 val set_failure_hook : exn callback -> unit
   (** Set the function in the main thread which is called if there is


@@ -181,3 +197,8 @@ val set_idle_hook : unit callback -> unit
   (** Set the function in the main thread which is called whenever
       the slave thread stops working on a command {i and} has no
       more commands left in the queue to work on. *)
   (** Set the function in the main thread which is called whenever
       the slave thread stops working on a command {i and} has no
       more commands left in the queue to work on. *)

+
+val set_progress_hook : (int64 * int64) callback -> unit
+  (** Set the function in the main thread which is called whenever
+      the slave thread receives a progress notification message
+      from libguestfs. *)