(* Guestfs Browser.
 * Copyright (C) 2010 Red Hat Inc.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *)

(** The public interface to the slave thread.
    Please see HACKING file. *)

(** {2 Commands and callbacks}

    Commands for libvirt and libguestfs are executed in a separate slave
    thread.  This file describes the interface with that thread that the
    rest of the program sees.

    Commands are intentionally as high level as possible.  Often a
    single command may perform many libvirt and libguestfs operations
    before returing a result.  This is to make use of the slave thread
    as simple as possible.

    Commands are executed in a "continuation-passing style" (CPS),
    which means that you call a function to issue the command, passing
    in a callback ("continuation").  The function returns immediately.
    The callback may be called some time later once the issued command
    completes successfully.  Several commands can be queued up for
    execution.  Commands are executed and callbacks are performed in
    sequence.

    The callback returns the result of the command.  The callback does
    not get invoked if there was an error, or if the command was
    cancelled before it runs (see {!discard_command_queue}).  For some
    commands the callback can be called multiple times (see
    documentation below).
*)

type 'a callback = 'a -> unit
  (** A callback function in the main thread which is called when the
      command finishes successfully.

      This can also return some data (the ['a] parameter).  A command
      that returns a list of strings might have callback type [string
      list callback], and a command that returns nothing would have
      callback type [unit callback].

      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
      the return value from a command. *)

val checksum_file : ?fail:exn callback -> Slave_types.source -> string -> string -> string callback -> unit
  (** [checksum_file src pathname csumtype cb] calculates the checksum
      of the file [pathname].  [csumtype] is one of the types
      supported by libguestfs. *)

val connect : ?fail:exn callback -> string option -> Slave_types.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
      called in the main thread.

      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.

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

val disk_usage : ?fail:exn callback -> Slave_types.source -> string -> int64 callback -> unit
  (** [disk_usage src pathname cb] calculates the disk usage of
      directory [pathname] and calls the callback with the answer
      (size of {b kilobytes}). *)

val download_dir_tarball : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.download_dir_tarball_format -> string -> unit callback -> unit
  (** [download_dir_tarball_format src pathname format localfile cb]
      downloads directory [pathname] to the named local file (a
      tarball), and then calls the callback function.

      [format] controls the download format, which is one of
      uncompressed tar, gzip-compressed tar, or xz-compressed tar. *)

val download_dir_find0 : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
  (** [download_dir_find0 src pathname localfile cb] downloads the
      list of filenames of directory [pathname] to the named local
      file (a ASCII NUL-separated text file), and then calls the
      callback function. *)

val download_file : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
  (** [download_file src pathname localfile cb] downloads [pathname]
      to the named local file, and then calls the callback function. *)

val download_file_if_not_exist : ?fail:exn callback -> Slave_types.source -> string -> string -> unit callback -> unit
  (** Like {!download_file} except that if [localfile] already exists
      then the download is skipped.  You can use this to implement
      caching of remote files. *)

val file_information : ?fail:exn callback -> Slave_types.source -> string -> string callback -> unit
  (** [file_information src pathname cb] calculates the file
      information of the file [pathname]. *)

val file_xattrs : ?fail:exn callback -> Slave_types.source -> string -> Guestfs.xattr array callback -> unit
  (** [file_xattrs src pathname cb] returns the extended
      attributes of the file [pathname]. *)

val list_applications : ?fail:exn callback -> Slave_types.inspection_os -> Guestfs.application array callback -> unit
  (** [list_applications os cb] lists the applications in the
      guest using libguestfs inspection. *)

val open_domain : ?fail:exn callback -> string -> Slave_types.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
      inspection.

      If this is successful, then [cb] is called in the main thread
      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.

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

val open_images : ?fail:exn callback -> (string * string option) list -> Slave_types.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. *)

val read_directory : ?fail:exn callback -> Slave_types.source -> string -> Slave_types.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.

      The source may be either a filesystem (if [src] is [Volume
      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.

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

val reopen : ?fail:exn callback -> Slave_types.inspection_data callback -> unit
  (** [reopen cb] reruns the last {!open_domain} or {!open_images}
      command, if there was one. *)

val run_command : ?fail:exn callback -> string -> unit callback -> unit
  (** [run_command cmd] runs an external command [cmd].  This is
      useful for possibly long-running commands as it keeps the
      display interactive.  Be careful to quote arguments in the
      command properly (see {!Filename.quote}).  The external command
      must eventually terminate and must not wait for user input. *)

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

      The currently running command cannot be discarded (because of
      the design of libguestfs).  Instead the callback is discarded,
      so from the point of view of the main thread, the effect is
      similar. *)

val exit_thread : unit -> unit
  (** [exit_thread ()] causes the slave thread to exit, and returns
      once it has exited. *)

(** {2 Hooks}

    Hooks are like callbacks, except they hook into special events
    that happen in the slave thread, rather than just being a response
    to commands.

    The other difference is that hooks are global variables.  You can
    only set one hook of each type.

    {!set_failure_hook} is used to catch errors in slave commands
    and display those in the main thread.

    {!set_busy_hook} and {!set_idle_hook} are used to implement a
    "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
      an error in the slave thread.  If this is not set then errors
      are discarded.  [exn] is the exception. *)

val set_busy_hook : unit callback -> unit
  (** Set the function in the main thread which is called whenever
      the slave thread starts working on a command. *)

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. *)

val set_status_hook : string callback -> unit
  (** Set the function in the main thread which is called to
      update the status bar.  The slave thread updates the
      status bar when an operation starts or stops, keeping the
      user informed of what is happening. *)

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. *)