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 oses : Slave_types.inspection_os list
  50     (** If operating system root(s) are currently loaded into the
  51         filetree widget, this returns a list of them.  If none are
  52         loaded (empty, or could be just a pile of filesystems), then this
  53         returns an empty list. *)
  54
  55   method get_pathname : Gtk.tree_iter -> Slave_types.source * string
  56     (** Use [get_pathname row] on a [row] representing a file or
  57         directory.  It searches back up the tree to get the source
  58         OS and the full pathname of the file.
  59
  60         Don't use this on registry entries.  Use {!get_registry_path}
  61         instead. *)
  62
  63   method get_direntry : Gtk.tree_iter -> Slave_types.direntry
  64     (** [get_direntry row] returns the file and stat information for a
  65         file or directory. *)
  66
  67   method get_registry_path : Gtk.tree_iter -> registry_t * string list
  68     (** Use [get_registry_path row] on a [row] representing a registry
  69         entry.  It searches back up the tree and returns a tuple
  70         containing:
  71
  72         - an opaque registry handle
  73
  74         - list of registry path elements (in reverse order)
  75
  76         Don't use this on files and directories.  Use {!get_pathname}
  77         instead. *)
  78
  79   method get_registry_value : Gtk.tree_iter -> Hivex.hive_type * string
  80     (** [get_registry_value row] returns the type and value of the
  81         registry value at [row]. *)
  82
  83   method get_registry_file : ?fail:exn Slave.callback ->
  84     Gtk.tree_path -> registry_t -> string Slave.callback -> unit
  85     (** [get_registry_file ?fail path registry_t cb] forces the
  86         registry to be downloaded (if not already).
  87
  88         [cb cachefile] is called when it is downloaded, where
  89         [cachefile] is the local hive containing the registry.
  90
  91         Optional argument [?fail] is called if the download fails. *)
  92
  93   method set_visited : Gtk.tree_iter -> unit
  94     (** Mark row has visited. *)
  95
  96   method has_child_info_node : Gtk.tree_path -> string -> bool
  97     (** [has_child_info_node path info_text] returns [true] iff there is
  98         an info node under path which exactly matches [info_text].
  99
 100         Info nodes are used for "Calculating ..." messages, and for
 101         the final result of those calculations. *)
 102
 103   method set_child_info_node : Gtk.tree_path -> string -> string -> unit
 104     (** [set_child_info_node path info_text text] replaces the
 105         displayed [text] in the info node [info_text] under [path].
 106         If the info node doesn't exist, then one is created. *)
 107
 108     (** Signals emitted by the filetree widget.
 109
 110         The main point of using signals is to decouple the filetree
 111         widget from associated dialogs and operations that can be
 112         performed by actions in the context menu.  So instead of
 113         having a giant filetree object that does everything, we have
 114         the code split into small modules, with the filetree widget
 115         just emitting signals when some action needs to take place.
 116
 117         All the components are wired together in the {!Main}
 118         module. *)
 119
 120   method after : 'a
 121   method disconnect : GtkSignal.id -> unit
 122
 123   method clear_tree : callback:(unit -> unit) -> GtkSignal.id
 124     (** Register a signal handler which is called when the tree is
 125         cleared (ie. when either {!clear} or {!add_os} is called. *)
 126
 127     (** The following methods register signals that are emitted
 128         on user events in the context menu. *)
 129   method op_checksum_file :
 130     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 131   method op_copy_regvalue :
 132     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 133   method op_disk_usage :
 134     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 135   method op_download_as_reg :
 136     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 137   method op_download_dir_find0 :
 138     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 139   method op_download_dir_tarball :
 140     callback:(Slave_types.download_dir_tarball_format * Gtk.tree_path -> unit) ->
 141     GtkSignal.id
 142   method op_download_file :
 143     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 144   method op_file_information :
 145     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 146   method op_file_properties :
 147     callback:(Gtk.tree_path -> unit) -> GtkSignal.id
 148   method op_inspection_dialog :
 149     callback:(Slave_types.inspection_os -> unit) -> GtkSignal.id
 150   method op_view_file :
 151     callback:(Gtk.tree_path * string -> unit) -> GtkSignal.id
 152 end