filetree.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 (** Tree model for displaying files in the guest filesystem.
  20
  21     The model reads files and directories on demand so that we don't
  22     have to read the whole thing in at the beginning.
  23
  24     Originally this was written as a custom tree model, but we
  25     couldn't get that to work.  Instead we use something similar
  26     to this trick:
  27     http://mail.gnome.org/archives/gtk-app-devel-list/2003-May/msg00241.html *)
  28
  29 type registry_t
  30 val source_of_registry_t : registry_t -> Slave_types.source
  31 val root_key_of_registry_t : registry_t -> string
  32
  33 (** The filetree widget. *)
  34 class tree : ?packing:(GObj.widget -> unit) -> unit ->
  35 object ('a)
  36   inherit GTree.view
  37
  38   method clear : unit -> unit
  39     (** Clear out all rows in existing widget. *)
  40
  41   method add_os : string -> Slave_types.inspection_data -> unit
  42     (** [add_os name data] clears out the widget and adds the operating
  43         system and/or filesystems described by the [data] struct.
  44
  45         The [name] parameter should be some host-side (verifiable) name,
  46         not any untrusted string from the guest; usually we pass the
  47         name of the guest from libvirt here. *)
  48
  49   method get_pathname : Gtk.tree_iter -> Slave_types.source * string
  50     (** Use [get_pathname row] on a [row] representing a file or
  51         directory.  It searches back up the tree to get the source
  52         OS and the full pathname of the file.
  53
  54         Don't use this on registry entries.  Use {!get_registry_path}
  55         instead. *)
  56
  57   method get_registry_path : Gtk.tree_iter -> registry_t * string list
  58     (** Use [get_registry_path row] on a [row] representing a registry
  59         entry.  It searches back up the tree and returns a tuple
  60         containing:
  61
  62         - an opaque registry handle
  63
  64         - list of registry path elements (in reverse order)
  65
  66         Don't use this on files and directories.  Use {!get_pathname}
  67         instead. *)
  68
  69   method get_registry_value : Gtk.tree_iter -> Hivex.hive_type * string
  70     (** [get_registry_value row] returns the type and value of the
  71         registry value at [row]. *)
  72
  73   method get_registry_file : ?fail:exn Slave.callback ->
  74     Gtk.tree_path -> registry_t -> string Slave.callback -> unit
  75     (** [get_registry_file ?fail path registry_t cb] forces the
  76         registry to be downloaded (if not already).
  77
  78         [cb cachefile] is called when it is downloaded, where
  79         [cachefile] is the local hive containing the registry.
  80
  81         Optional argument [?fail] is called if the download fails. *)
  82
  83   method set_visited : Gtk.tree_iter -> unit
  84     (** Mark row has visited. *)
  85
  86   method has_child_info_node : Gtk.tree_path -> string -> bool
  87     (** [has_child_info_node path info_text] returns [true] iff there is
  88         an info node under path which exactly matches [info_text].
  89
  90         Info nodes are used for "Calculating ..." messages, and for
  91         the final result of those calculations. *)
  92
  93   method set_child_info_node : Gtk.tree_path -> string -> string -> unit
  94     (** [set_child_info_node path info_text text] replaces the
  95         displayed [text] in the info node [info_text] under [path].
  96         If the info node doesn't exist, then one is created. *)
  97
  98     (** Signals emitted by the filetree widget.
  99
 100         The main point of using signals is to decouple the filetree
 101         widget from associated dialogs and operations that can be
 102         performed by actions in the context menu.  So instead of
 103         having a giant filetree object that does everything, we have
 104         the code split into small modules, with the filetree widget
 105         just emitting signals when some action needs to take place.
 106
 107         All the components are wired together in the {!Window}
 108         module. *)
 109
 110   method after : 'a
 111   method disconnect : GtkSignal.id -> unit
 112
 113   method clear_tree : callback:(unit -> unit) -> GtkSignal.id
 114     (** Register a signal handler which is called when the tree is
 115         cleared (ie. when either {!clear} or {!add_os} is called. *)
 116
 117     (** The following methods register signals that are emitted
 118         on user events in the context menu. *)
 119   method op_checksum_file :
 120     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 121   method op_copy_regvalue :
 122     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 123   method op_disk_usage :
 124     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 125   method op_download_as_reg :
 126     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 127   method op_download_dir_find0 :
 128     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 129   method op_download_dir_tarball :
 130     callback:(Slave_types.download_dir_tarball_format * Gtk.tree_path -> unit) ->
 131     GtkSignal.id
 132   method op_download_file :
 133     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 134   method op_file_information :
 135     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 136   method op_inspection_dialog :
 137     callback:(Slave_types.inspection_os -> unit) -> GtkSignal.id
 138   method op_view_file :
 139     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 140 end