bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/proxies/collection.rb

@@ -0,0 +1,57 @@
+module VirtualBox
+  module Proxies
+    # A relationship which can be described as a collection, which
+    # is a set of items.
+    class Collection < Array
+      attr_reader :parent
+
+      def initialize(parent, item_klass=nil, *args)
+        super()
+
+        @parent = parent
+        @item_klass = item_klass
+        @other = args
+      end
+
+      # Creates a new item for this collection and returns the
+      # instance. The item is automatically put into this
+      # collection. `create` happens immediately, meaning that even
+      # without a `save`, the item will already exist.
+      def create(*args)
+        item =  nil
+
+        if @item_klass.respond_to?(:create)
+          args = @other + args
+          item = @item_klass.create(self, *args)
+          self << item
+        end
+
+        item
+      end
+
+      # Returns the errors associated with all the items in this
+      # collection
+      def errors
+        collect do |item|
+          item.respond_to?(:errors) ? item.errors : {}
+        end
+      end
+
+      def <<(item)
+        item.added_to_relationship(self) if item.respond_to?(:added_to_relationship)
+        push(item)
+      end
+
+      def clear
+        each do |item|
+          delete(item)
+        end
+      end
+
+      def delete(item, no_callback=false)
+        return unless super(item)
+        item.removed_from_relationship(self) if !no_callback && item.respond_to?(:removed_from_relationship)
+      end
+    end
+  end
+end

data/lib/virtualbox/shared_folder.rb

@@ -0,0 +1,220 @@
+module VirtualBox
+  # Represents a shared folder in VirtualBox. In VirtualBox, shared folders are a
+  # method for basically "symlinking" a folder on the guest system to a folder which
+  # exists on the host system. This allows for sharing of files across the virtual
+  # machine.
+  #
+  # **Note:** Whenever modifying shared folders on a VM, the changes won't take
+  # effect until a _cold reboot_ occurs. This means actually closing the virtual
+  # machine _completely_, then restarting it. You can't just hit "Start > Restart"
+  # or do a `sudo reboot`. It doesn't work that way!
+  #
+  # # Getting Shared Folders
+  #
+  # All shared folders are attached to a {VM} object, by definition. Therefore, to
+  # get a list of the shared folders, first {VM.find find} the VM you need, then
+  # use the `shared_folders` relationship to access an array of the shared folders.
+  # With this array, you can create, modify, update, and delete the shared folders
+  # for that virtual machine.
+  #
+  # # Creating a Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  # With a VM found, creating a shared folder is just a few lines of code:
+  #
+  #     folder = VirtualBox::SharedFolder.new
+  #     folder.name = "desktop-images"
+  #     folder.hostpath = File.expand_path("~/Desktop/images")
+  #     vm.shared_folders << folder
+  #     folder.save # Or you can call vm.save, which works too!
+  #
+  # # Modifying an Existing Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  # Nothing tricky here: You treat existing shared folder objects just as if they
+  # were new ones. Assign a new name and/or a new path, then save.
+  #
+  #     folder = vm.shared_folders.first
+  #     folder.name = "rufus"
+  #     folder.save # Or vm.save
+  #
+  # **Note**: The VirtualBox-saavy will know that VirtualBox doesn't actually
+  # expose a way to edit shared folders. Under the hood, the virtualbox ruby
+  # library is actually deleting the old shared folder, then creating a new
+  # one with the new details. This shouldn't affect the way anything works for
+  # the VM itself.
+  #
+  # # Deleting a Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  #     folder = vm.shared_folder.first
+  #     folder.destroy
+  #
+  # Poof! It'll be gone. This is usually the place where I warn you about this
+  # being non-reversable, but since no _data_ was actually destroyed, this is
+  # not too risky. You could always just recreate the shared folder with the
+  # same name and path and it'll be like nothing happened.
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the model are exposed using standard ruby instance
+  # methods which are generated on the fly. Because of this, they are not listed
+  # below as available instance methods.
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below.
+  #
+  # Relationships are also accessed like attributes but can't be set. Instead,
+  # they are typically references to other objects such as an {AttachedDevice} which
+  # in turn have their own attributes which can be modified.
+  #
+  # ## Attributes
+  #
+  # This is copied directly from the class header, but lists all available
+  # attributes. If you don't understand what this means, read {Attributable}.
+  #
+  #     attribute :parent, :readonly => :readonly
+  #     attribute :name
+  #     attribute :hostpath
+  #
+  class SharedFolder < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :name
+    attribute :host_path
+    attribute :writable, :default => true, :boolean => true
+    attribute :accessible, :readonly => true, :boolean => true
+
+    class << self
+      # Populates the shared folder relationship for anything which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<SharedFolder>]
+      def populate_relationship(caller, imachine)
+        relation = Proxies::Collection.new(caller)
+
+        imachine.shared_folders.each do |ishared|
+          relation << new(ishared)
+        end
+
+        relation
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, items)
+        items.dup.each do |item|
+          item.save
+        end
+      end
+    end
+
+    # @overload initialize(data={})
+    #   Creates a new SharedFolder which is a new record. This
+    #   should be attached to a VM and saved.
+    #   @param [Hash] data (optional) A hash which contains initial attribute
+    #     values for the SharedFolder.
+    # @overload initialize(interface)
+    #   Creates an SharedFolder for a relationship. **This should
+    #   never be called except internally.**
+    #   @param [Object] caller The parent
+    #   @param [Hash] data A hash of data which must be used
+    #     to extract the relationship data.
+    def initialize(data=nil)
+      super()
+
+      if data
+        initialize_attributes(data)
+      end
+    end
+
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(ishared)
+      # Load the interface attributes
+      load_interface_attributes(ishared)
+
+      # Clear dirtiness, since this should only be called initially and
+      # therefore shouldn't affect dirtiness
+      clear_dirty!
+
+      # But this is an existing record
+      existing_record!
+    end
+
+    # Validates a shared folder.
+    def validate
+      super
+
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :host_path
+    end
+
+    # Saves or creates a shared folder.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      if !new_record?
+        # If its not a new record, any changes will require a new shared
+        # folder to be created, so we first destroy it then recreate it.
+        destroy(false)
+      end
+
+      create
+    end
+
+    # Creates a new shared folder. This method should not be called directly.
+    # Instead, {save} should always be called, which will do the right thing.
+    def create
+      return unless new_record?
+
+      parent_machine.with_open_session do |session|
+        machine = session.machine
+        machine.create_shared_folder(name, host_path, writable)
+      end
+
+      existing_record!
+      clear_dirty!
+    end
+
+    # Relationship callback when added to a collection. This is automatically
+    # called by any relationship collection when this object is added.
+    def added_to_relationship(proxy)
+      was_clean = parent.nil? && !changed?
+
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+
+      # This keeps existing records not dirty when added to collection
+      clear_dirty! if !new_record? && was_clean
+    end
+
+    # Destroys the shared folder. This doesn't actually delete the folder
+    # from the host system. Instead, it simply removes the mapping to the
+    # virtual machine, meaning it will no longer be possible to mount it
+    # from within the virtual machine.
+    def destroy(update_collection=true)
+      parent.with_open_session do |session|
+        machine = session.machine
+        machine.remove_shared_folder(name)
+      end
+
+      # Remove it from it's parent collection
+      parent_collection.delete(self, true) if parent_collection && update_collection
+
+      # Mark as a new record so if it is saved again, it will create it
+      new_record!
+   end
+  end
+end

data/lib/virtualbox/snapshot.rb

@@ -0,0 +1,185 @@
+module VirtualBox
+  # Represents a virtual machine snapshot. Snapshots allow users of virtual
+  # machines to make a lightweight "snapshot" of a virtual machine at any
+  # moment. This snapshot can be taken while the virtual machine is running
+  # or while its powered off. Snapshotting creates a differencing image for
+  # the hard drive which allows a virtual machine to restore itself to the
+  # exact state of where it was snapshotted.
+  #
+  # # Getting Snapshots
+  #
+  # Snapshots are accessed from the `current_snapshot` relationship on {VM}.
+  # There is no other way to access snapshots. After getting the current
+  # snapshot, you can easily traverse the tree of snapshots by accessing
+  # `parent` or `children` on the snapshot. An example follows:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     p vm.current_snapshot # the current snapshot
+  #     p vm.current_snapshot.children # The children of the current snapshot
+  #     p vm.current_snapshot.parent # The current snapshot's parent
+  #     p vm.current_snapshot.parent.parent.children # You get the idea.
+  #
+  # # Taking a Snapshot
+  #
+  # To take a snapshot, call the {VM#take_snapshot} method. Please view
+  # the documentation on that method for more information.
+  #
+  # # Restoring a Snapshot
+  #
+  # To restore a snapshot, call the {#restore} method. A simple example
+  # is shown below:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     snapshot = vm.current_snapshot.parent
+  #     snapshot.restore
+  #
+  # **Note:** The VM object will not immediately update to reflect any settings
+  # changes or current snapshot changes from the restore. To grab the updates,
+  # either load a new VM object or call {VM#reload}.
+  #
+  # # Deleting a Snapshot
+  #
+  # To delete a snapshot, simply find the snapshot of interest and call
+  # it's {#destroy} method. A quick example is shown below:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     snapshot = vm.current_snapshot # Grab the current snapshot
+  #     snapshot.destroy # Destroy it
+  #
+  # Note that this doesn't actually affect the `current_snapshot`
+  # relationship on the VM. To update all the proper values, you have to call
+  # {VM#reload}.
+  #
+  class Snapshot < AbstractModel
+    attribute :uuid, :readonly => true, :property => :id
+    attribute :name
+    attribute :description
+    attribute :time_stamp, :readonly => true
+    attribute :online, :readonly => true, :boolean => true
+    attribute :interface, :readonly => true, :property => false
+    relationship :parent, :Snapshot, :lazy => true
+    relationship :machine, :VM, :lazy => true
+    relationship :children, :Snapshot, :lazy => true
+
+    class << self
+      # Populates a relationship with another model. Since a snapshot
+      # can be in a relationship with multiple items, this method forwards
+      # to other methods such as {populate_vm_relationship}.
+      #
+      # **This method typically won't be used except internally.**
+      def populate_relationship(caller, data)
+        if data.is_a?(COM::Util.versioned_interface(:Machine))
+          populate_machine_relationship(caller, data)
+        elsif data.is_a?(Array)
+          populate_children_relationship(caller, data)
+        elsif data.is_a?(COM::Util.versioned_interface(:Snapshot)) || data.nil?
+          populate_parent_relationship(caller, data)
+        else
+          raise Exceptions::Exception.new("Invalid relationship data for Snapshot: #{data}")
+        end
+      end
+
+      # Populates the VM relationship as the "current snapshot."
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Snapshot]
+      def populate_machine_relationship(caller, machine)
+        # The current snapshot can and will be nil if there are no snapshots
+        # taken. In that case, we just return nil.
+        snapshot = machine.current_snapshot
+        snapshot ? new(machine.current_snapshot) : nil
+      end
+
+      # Populates the VM relationship as the "current snapshot."
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Snapshot]
+      def populate_parent_relationship(caller, parent)
+        # If the parent is nil then that means the child is the root
+        # snapshot
+        parent ? new(parent) : nil
+      end
+
+      # Populates the snapshot child tree relationship.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Snapshot>]
+      def populate_children_relationship(caller, snapshots)
+        result = Proxies::Collection.new(caller)
+
+        snapshots.each do |snapshot|
+          result << new(snapshot)
+        end
+
+        result
+      end
+    end
+
+    # Initializes a new snapshot. This should never be called on its own.
+    # Snapshots should be accessed beginning with the `current_snapshot` on
+    # a VM, and can be further accessed by traversing the parent/child tree
+    # of the snapshot.
+    def initialize(snapshot)
+      write_attribute(:interface, snapshot)
+      initialize_attributes(snapshot)
+    end
+
+    def initialize_attributes(snapshot)
+      # Load the interface attributes
+      load_interface_attributes(snapshot)
+
+      # Clear dirtiness, since this should only be called initially and
+      # therefore shouldn't affect dirtiness
+      clear_dirty!
+
+      # But this is an existing record
+      existing_record!
+    end
+
+    # Loads the lazy relationships.
+    #
+    # **This method should only be called internally.**
+    def load_relationship(name)
+      populate_relationship(:parent, interface.parent)
+      populate_relationship(:machine, interface.machine)
+      populate_relationship(:children, interface.children)
+    end
+
+    # Timestamp that the snapshot was taken. This method overwrites the
+    # typical attribute so it can return a Time object.
+    def time_stamp
+      # Seconds, microseconds, since the time stamp is in milliseconds
+      value = read_attribute(:time_stamp)
+      Time.at(value / 1000, (value % 1000) * 1000)
+    end
+
+    # Restore a snapshot. This will restore this snapshot's virtual machine
+    # to the state that this snapshot represents. This method will block while
+    # the restore occurs.
+    #
+    # If a block is given to the function, it will be yielded with a progress
+    # object which can be used to track the progress of the operation.
+    def restore(&block)
+      machine.with_open_session do |session|
+        session.console.restore_snapshot(interface).wait(&block)
+      end
+    end
+
+    # Destroy a snapshot. This will physically remove the snapshot. Once this
+    # method is called, there is no undo. If this snapshot is a parent of other
+    # snapshots, the differencing image of this snapshot will be merged with
+    # the child snapshots so no data is lost. This process can sometimes take
+    # some time. This method will block while this process occurs.
+    #
+    # If a block is given to the function, it will be yielded with a progress
+    # object which can be used to track the progress of the operation.
+    def destroy(&block)
+      machine.with_open_session do |session|
+        session.console.delete_snapshot(uuid).wait(&block)
+      end
+    end
+  end
+end