(* 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} *)

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.  Errors result
      in the command queue being discarded and the failure_hook
      function being called. *)

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 connect : string option -> unit callback -> unit
  (** [connect uri cb] sends the [Connect] message to the slave
      thread.

      This causes the slave thread to disconnect from libvirt and
      connect to the libvirt [uri].  If this succeeds, [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. *)

type domain = {
  dom_id : int;
  dom_name : string;
  dom_state : Libvirt.Domain.state;
}
    (** List of domains as returned in the [Get_domains] message callback.

        Note that [dom_state] is the state of the domain and should
        control whether we are allowed to write to the domain's
        filesystem (disallowed if [dom_state] is not [InfoShutoff]). *)

val get_domains : domain list callback -> unit
  (** [get_domains cb] sends the [Get_domains] message to the
      slave thread.

      This causes the slave thread to retrieve the list of domains
      from libvirt (active and inactive ones).  If this succeeds,
      [cb] is called in the main thread with the list of
      domains.  See also the {!domain} type. *)

type rw_flag = RO | RW
    (** This flag is passed to open callbacks to indicate whether
        we could open the disks read-only ([RO]) or read-write ([RW]). *)

val open_domain : string -> rw_flag callback -> unit
  (** [open_domain name cb] sends the [Open_domain] message to the
      slave thread.

      This causes the slave thread to retrieve the list of
      block devices for the libvirt domain [name], create a
      libguestfs handle, add those block devices, and launch
      the handle.  If this is successful, then [cb] is called
      in the main thread.

      If the domain is live then the disks are opened read only,
      else they are opened read write if write_flag is true.
      The [rw_flag] is passed into the callback accordingly.

      The slave thread must be connected to libvirt (see {!connect})
      else this command will fail. *)

val open_images : string list -> rw_flag callback -> unit
  (** [open_images images cb] is like {!open_domain} except
      that it opens local disk image(s) directly. *)

type volume = {
  vol_device : string;
  vol_type : string;
  vol_label : string;
  vol_uuid : string;
  vol_statvfs : Guestfs.statvfs;
}
    (** The volume structure which is passed to the {!get_volumes} callback. *)

val get_volumes : volume callback -> unit
  (** [get_volumes cb] sends the [Get_volumes] message to the
      slave thread.

      This causes the slave thread to examine all partitions, LVs
      etc within the current disk image, and for each that contains
      a mountable filesystem, [cb] is called.  (Note [cb] can be
      called multiple times). *)

type direntry = {
  dent_name : string;          (** Basename in directory. *)
  dent_stat : Guestfs.stat;    (** stat(2) for this entry. *)
  dent_link : string;          (** (for symlinks only) readlink(2). *)
}

val read_directory : string -> string -> direntry list callback -> unit
  (** [read_directory dev dir cb] sends the [Read_directory] message
      to the slave thread.

      This causes the slave thread to read the contents of the
      directory [dir] from volume [dev], and call [cb] with the
      complete result.  If [dir] is not a directory then this
      is an error.

      Note that [.] and [..] entries are not included in the result,
      and the list is sorted on the [filename] field. *)

val disk_usage : string -> string -> int64 callback -> unit
  (** [disk_usage dev dir cb] sends the [Disk_usage] message to the
      slave thread.

      This causes the slave thread to estimate the disk usage of the
      directory (or file) [dir] from volume [dev], and call [cb] with
      the result (size in {b kilobytes}). *)

type export_t =
  | Export_tar                      (** uncompressed tar archive *)
  | Export_tgz                      (** gzip compressed tar archive *)
  | Export_checksums of string      (** checksums using algorithm *)
  | Export_list                     (** list of file names, \0-separated *)
      (** Export format used by {!export_dir_to}. *)

val export_dir_to : export_t -> string -> string -> string -> unit callback -> unit
  (** [export_dir_to t dev dir file cb] sends the [Export_dir_to] message
      to the slave thread.

      This causes the slave thread to export the directory [dir] on
      device [dev] to the host file called [file].  The precise
      operation (ie. what is exported) is controlled by the type
      [export_t].  When the export has been completed, the callback
      [cb] is called in the main thread.

      Libguestfs doesn't offer any way to view progress of this
      operation, which could potentially take a long time. *)

val discard_command_queue : unit -> unit
  (** [discard_command_queue ()] discards any commands on the command
      queue.  The currently running command is not (and can not be)
      stopped. *)

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 threads, 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". *)

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