virtualbox 0.6.1 → 0.7.0

data/lib/virtualbox/medium.rb

@@ -5,13 +5,15 @@ module VirtualBox
   class Medium < AbstractModel
     include SubclassListing
 
-    attribute :uuid, :readonly => :true, :property => :id
+    attribute :uuid, :readonly => true, :property => :id
+    attribute :type, :readonly => true
     attribute :description, :readonly => true
     attribute :location, :readonly => true
     attribute :state, :readonly => true, :property => :refresh_state
     attribute :interface, :readonly => true, :property => false
+    relationship :children, :Medium, :lazy => true
 
-    class <<self
+    class << self
       # Populates a relationship with another model. Depending on the data sent
       # through as the `media` parameter, this can either return a single value
       # or an array of values. {Global}, for example, has a relationship of media,
@@ -106,6 +108,11 @@ module VirtualBox
       existing_record!
     end
 
+    def load_relationship(name)
+      # Populate children
+      populate_relationship(name, interface.children)
+    end
+
     # Returns the basename of the images location (the file name +extension)
     #
     # @return [String]
@@ -135,4 +142,4 @@ module VirtualBox
       interface.delete_storage.wait_for_completion(-1)
     end
   end
-end
+end

data/lib/virtualbox/medium_attachment.rb

@@ -11,7 +11,7 @@ module VirtualBox
     relationship :medium, :Medium
     relationship :storage_controller, :StorageController
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -58,4 +58,4 @@ module VirtualBox
       medium.destroy(opts[:destroy_medium] == :delete) if opts[:destroy_medium] && medium
     end
   end
-end
+end

data/lib/virtualbox/network_adapter.rb

@@ -35,17 +35,17 @@ module VirtualBox
   class NetworkAdapter < AbstractModel
     attribute :parent, :readonly => true, :property => false
     attribute :slot, :readonly => true
-    attribute :enabled
+    attribute :enabled, :boolean => true
     attribute :attachment_type
     attribute :adapter_type
     attribute :mac_address
-    attribute :cable_connected
+    attribute :cable_connected, :boolean => true
     attribute :nat_network
     attribute :internal_network
     attribute :host_interface
     attribute :interface, :readonly => true, :property => false
 
-    class <<self
+    class << self
       # Populates the nic relationship for anything which is related to it.
       #
       # **This method typically won't be used except internally.**
@@ -98,6 +98,14 @@ module VirtualBox
       existing_record!
     end
 
+    # Gets the host interface object associated with the class if it
+    # exists.
+    def host_interface_object
+      VirtualBox::Global.global.host.network_interfaces.find do |ni|
+        ni.name == host_interface
+      end
+    end
+
     # Save a network adapter.
     def save
       modify_adapter do |adapter|
@@ -131,4 +139,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/proxies/collection.rb

@@ -3,14 +3,34 @@ module VirtualBox
     # A relationship which can be described as a collection, which
     # is a set of items.
     class Collection < Array
-      def initialize(parent)
+      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
 
       def <<(item)
-        item.added_to_relationship(@parent) if item.respond_to?(:added_to_relationship)
+        item.added_to_relationship(self) if item.respond_to?(:added_to_relationship)
         push(item)
       end
 
@@ -20,10 +40,10 @@ module VirtualBox
         end
       end
 
-      def delete(item)
-        return unless super
-        item.removed_from_relationship(@parent) if item.respond_to?(:removed_from_relationship)
+      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
+end

data/lib/virtualbox/shared_folder.rb

@@ -86,12 +86,13 @@ module VirtualBox
   #
   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
-    attribute :accessible, :readonly => true
+    attribute :writable, :default => true, :boolean => true
+    attribute :accessible, :readonly => true, :boolean => true
 
-    class <<self
+    class << self
       # Populates the shared folder relationship for anything which is related to it.
       #
       # **This method typically won't be used except internally.**
@@ -101,7 +102,7 @@ module VirtualBox
         relation = Proxies::Collection.new(caller)
 
         imachine.shared_folders.each do |ishared|
-          relation << new(caller, ishared)
+          relation << new(ishared)
         end
 
         relation
@@ -123,25 +124,22 @@ module VirtualBox
     #   should be attached to a VM and saved.
     #   @param [Hash] data (optional) A hash which contains initial attribute
     #     values for the SharedFolder.
-    # @overload initialize(index, caller, data)
+    # @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(*args)
+    def initialize(data=nil)
       super()
 
-      if args.length == 2
-        initialize_attributes(*args)
+      if data
+        initialize_attributes(data)
       end
     end
 
     # Initializes the attributes of an existing shared folder.
-    def initialize_attributes(parent, ishared)
-      # Set the parent
-      write_attribute(:parent, parent)
-
+    def initialize_attributes(ishared)
       # Load the interface attributes
       load_interface_attributes(ishared)
 
@@ -192,8 +190,14 @@ module VirtualBox
 
     # Relationship callback when added to a collection. This is automatically
     # called by any relationship collection when this object is added.
-    def added_to_relationship(parent)
-      write_attribute(:parent, parent)
+    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
@@ -206,8 +210,11 @@ module VirtualBox
         machine.remove_shared_folder(name)
       end
 
+      # Remove it from it's parent collection
+      parent_collection.delete(self, true) if parent_collection
+
       # Mark as a new record so if it is saved again, it will create it
       new_record!
    end
   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

data/lib/virtualbox/storage_controller.rb

@@ -47,14 +47,14 @@ module VirtualBox
     attribute :bus, :readonly => true
     attribute :controller_type
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
       #
       # @return [Array<StorageController>]
       def populate_relationship(caller, data)
-        if data.is_a?(COM::Interface::Machine)
+        if data.is_a?(COM::Util.versioned_interface(:Machine))
           populate_array_relationship(caller, data)
         elsif data.is_a?(MediumAttachment)
           populate_attachment_relationship(caller, data)
@@ -157,4 +157,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/system_properties.rb

@@ -26,7 +26,7 @@ module VirtualBox
     attribute :log_history_count
     attribute :default_audio_driver, :readonly => true
 
-    class <<self
+    class << self
       # Populates the system properties relationship for anything
       # which is related to it.
       #

data/lib/virtualbox/usb_controller.rb

@@ -4,11 +4,12 @@ module VirtualBox
   class USBController < AbstractModel
     attribute :parent, :readonly => true, :property => false
     attribute :interface, :readonly => true, :property => false
-    attribute :enabled
-    attribute :enabled_ehci
+    attribute :enabled, :boolean => true
+    attribute :enabled_ehci, :boolean => true
     attribute :usb_standard, :readonly => true
+    relationship :device_filters, :USBDeviceFilter
 
-    class <<self
+    class << self
       # Populates the USB controller relationship for anything
       # which is related to it.
       #
@@ -40,6 +41,9 @@ module VirtualBox
       # Load the interface attributes
       load_interface_attributes(interface)
 
+      # Setup the relationships
+      populate_relationships(interface)
+
       # Clear dirty and mark as existing
       clear_dirty!
       existing_record!
@@ -52,4 +56,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/usb_device_filter.rb

@@ -0,0 +1,74 @@
+module VirtualBox
+  # Represents a USB device filter within VirtualBox. This class
+  # is a relationship to {USBController} objects.
+  class USBDeviceFilter < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :name
+    attribute :active, :boolean => true
+    attribute :vendor_id
+    attribute :product_id
+    attribute :revision
+    attribute :manufacturer
+    attribute :product
+    attribute :serial_number
+    attribute :port
+    attribute :remote
+    attribute :masked_interfaces
+
+    class << self
+      # Populates the USB controller relationship for anything
+      # which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [USBDeviceFilter]
+      def populate_relationship(caller, usbcontroller)
+        result = Proxies::Collection.new(caller)
+
+        usbcontroller.device_filters.each do |filter|
+          result << new(filter)
+        end
+
+        result
+      end
+
+      # Saves the relationship. This simply calls {#save} on the
+      # relationship object.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, item)
+        item.save
+      end
+    end
+
+    def initialize(iusb)
+      initialize_attributes(iusb)
+    end
+
+    def initialize_attributes(iusb)
+      # Write the parent and interface attributes
+      write_attribute(:interface, iusb)
+
+      # Load the interface attributes
+      load_interface_attributes(interface)
+
+      # Clear dirty and mark as existing
+      clear_dirty!
+      existing_record!
+    end
+
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+    end
+
+    # Saves the USB device.
+    def save
+      parent.with_open_session do |session|
+        # TODO: save_changed_interface_attributes(session.machine.usb_controller)
+      end
+    end
+  end
+end

data/lib/virtualbox/version.rb

@@ -1,5 +1,16 @@
 module VirtualBox
   module Version
+    # Returns a boolean denoting whether the current VirtualBox
+    # version is supported or not. This will return `false` if the
+    # version is invalid, the version is not detected, etc. That means
+    # that even if VirtualBox is not installed, this will simply
+    # return `false`.
+    #
+    # @return [Boolean]
+    def supported?
+      !version.nil?
+    end
+
     # Returns the version string of the VirtualBox installed, ex. "3.1.6"
     def version
       Lib.lib.virtualbox.version
@@ -12,4 +23,4 @@ module VirtualBox
       Lib.lib.virtualbox.revision
     end
   end
-end
+end

data/lib/virtualbox/virtual_system_description.rb

@@ -5,7 +5,7 @@ module VirtualBox
     attribute :interface, :readonly => true
     attribute :descriptions, :readonly => true, :default => {}
 
-    class <<self
+    class << self
       def populate_relationship(caller, data)
         result = Proxies::Collection.new(caller)
 
@@ -26,8 +26,8 @@ module VirtualBox
       # Grab all the descriptions, iterate over each, and add to the hash of
       # descriptions. This multiple loop method is used instead of `get_description` since
       # that method doesn't work well with MSCOM.
-      COM::Interface::VirtualSystemDescriptionType.each_with_index do |type, index|
-        COM::Interface::VirtualSystemDescriptionValueType.each_with_index do |value_type, value_index|
+      COM::Util.versioned_interface(:VirtualSystemDescriptionType).each_with_index do |type, index|
+        COM::Util.versioned_interface(:VirtualSystemDescriptionValueType).each_with_index do |value_type, value_index|
           value = ivsd.get_values_by_type(type, value_type)
           if value && value != [] && value != [nil]
             descriptions[type] ||= {}
@@ -44,4 +44,4 @@ module VirtualBox
       existing_record!
     end
   end
-end
+end