virtualbox 0.5.4 → 0.6.0

data/lib/virtualbox/global.rb

@@ -5,22 +5,6 @@ module VirtualBox
   # allow the user to retrieve a list of all VMs, media, global extra data,
   # etc. Indeed, even methods like {VM.all} are implemented using this class.
   #
-  # # Setting the Path to VirtualBox.xml
-  #
-  # **This is extremely important.**
-  #
-  # Much of the virtualbox gem requires a proper path to the global XML configuration
-  # file for VirtualBox. This path is system and installation dependent. {Global}
-  # does its best to guess the path by trying the default paths based on the
-  # platform ruby is running on, but this is hardly foolproof. If you receive an
-  # {Exceptions::ConfigurationException} at some point while running virtualbox,
-  # you should use {Global.vboxconfig=} to set the path. An example is below:
-  #
-  #     # Most installations won't need to do this, since the gem "guesses"
-  #     # the path based on OS, but if you need to set vboxconfig path
-  #     # explicitly:
-  #     VirtualBox::Global.vboxconfig = "~/.MyCustom/VirtualBox.xml"
-  #
   # # Getting Global Data
   #
   # To retrieve the global data, use `Global.global`. This value is _cached_
@@ -46,19 +30,18 @@ module VirtualBox
   # relationships. The relationships are listed below. If you don't
   # understand this, read {Relatable}.
   #
-  #     relationship :vms, VM, :lazy => true
+  #     relationship :vms, VM
   #     relationship :media, Media
   #     relationship :extra_data, ExtraData
+  #     relationship :system_properties, :SystemProperties, :lazy => true
   #
   class Global < AbstractModel
-    # The path to the global VirtualBox XML configuration file. This is
-    # entirely system dependent and can be set with {vboxconfig=}. The default
-    # is guessed based on the platform.
-    @@vboxconfig = nil
+    attribute :lib, :readonly => true
 
-    relationship :vms, VM, :lazy => true
-    relationship :media, Media
-    relationship :extra_data, ExtraData
+    relationship :vms, :VM, :lazy => true
+    relationship :media, :Media, :lazy => true
+    relationship :extra_data, :ExtraData, :lazy => true
+    relationship :system_properties, :SystemProperties, :lazy => true
 
     @@global_data = nil
 
@@ -71,73 +54,32 @@ module VirtualBox
       #
       # @param [Boolean] reload True if you want to force a reload of the data.
       # @return [Global]
-      def global(reload = false)
-        if !@@global_data || reload || reload?
-          @@global_data = new(config)
-          reloaded!
+      def global(reload=false)
+        if !@@global_data || reload
+          @@global_data = new(Lib.lib)
         end
 
         @@global_data
       end
 
-      # Sets the path to the VirtualBox.xml file. This file should already
-      # exist. VirtualBox itself manages this file, not this library.
-      #
-      # @param [String] Full path to the VirtualBox.xml file
-      def vboxconfig=(value)
-        @@vboxconfig = value
-      end
-
-      # Returns the path to the virtual box configuration file. If the path
-      # has not yet been set, it attempts to infer it based on the
-      # platform ruby is running on.
-      def vboxconfig
-        if @@vboxconfig.nil?
-          if Platform.mac?
-            @@vboxconfig = "~/Library/VirtualBox/VirtualBox.xml"
-          elsif Platform.linux? || Platform.windows?
-            @@vboxconfig = "~/.VirtualBox/VirtualBox.xml"
-          else
-            @@vboxconfig = "Unknown"
-          end
-        end
-        
-        File.expand_path(@@vboxconfig)
-      end
-      
-      # Returns a boolean denoting whether or not the vboxconfig value is
-      # valid or not.
-      #
-      # @return [Boolean]
-      def vboxconfig?
-        File.file?(vboxconfig)
-      end
-
-      # Returns the XML document of the configuration. This will raise an
-      # {Exceptions::ConfigurationException} if the vboxconfig file doesn't
-      # exist.
-      #
-      # @return [Nokogiri::XML::Document]
-      def config
-        raise Exceptions::ConfigurationException.new("The path to the global VirtualBox config must be set. See Global.vboxconfig=") unless vboxconfig?
-        Command.parse_xml(vboxconfig)
-      end
-
-      # Expands path relative to the configuration file.
-      #
-      # @return [String]
-      def expand_path(path)
-        File.expand_path(path, File.dirname(vboxconfig))
+      # Resets the global data singleton. This is used for testing purposes.
+      def reset!
+        @@global_data = nil
       end
     end
 
-    def initialize(document)
-      @document = document
-      populate_attributes(@document)
+    def initialize(lib)
+      write_attribute(:lib, lib)
+
+      # Required to load lazy relationships
+      existing_record!
     end
 
     def load_relationship(name)
-      populate_relationship(:vms, @document)
+      populate_relationship(:vms, lib.virtualbox.machines)
+      populate_relationship(:media, lib)
+      populate_relationship(:extra_data, lib.virtualbox)
+      populate_relationship(:system_properties, lib.virtualbox.system_properties)
     end
   end
 end

data/lib/virtualbox/hard_drive.rb

@@ -70,15 +70,16 @@ module VirtualBox
   # listed below. If you aren't sure what this means or you can't understand
   # why the below is listed, please read {Attributable}.
   #
-  #     attribute :uuid, :readonly => true
-  #     attribute :location
-  #     attribute :accessible, :readonly => true
-  #     attribute :format, :default => "VDI"
-  #     attribute :size
-  #
-  class HardDrive < Image
-    attribute :format, :default => "VDI"
-    attribute :size, :lazy => true
+  #     attribute :format, :default => "VDI", :property => :format
+  #     attribute :logical_size, :property => :logical_size
+  #     attribute :physical_size, :readonly => true, :property => :size
+  #
+  # There are more attributes on the {Medium} model, which {HardDrive} inherits
+  # from.
+  class HardDrive < Medium
+    attribute :format, :default => "VDI", :property => :format
+    attribute :logical_size, :property => :logical_size
+    attribute :physical_size, :readonly => true, :property => :size
 
     class <<self
       # Returns an array of all available hard drives as HardDrive
@@ -92,45 +93,15 @@ module VirtualBox
       # Finds one specific hard drive by UUID or file name. If the
       # hard drive can not be found, will return `nil`.
       #
-      # @param [String] id The UUID or name of the hard drive
-      # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
-      #   will be raised if the command failed.
+      # @param [String] id The UUID of the hard drive
       # @return [HardDrive]
       def find(id, raise_errors=false)
-        raw = Command.vboxmanage("showhdinfo", id)
-
-        data = raw.split(/\n\n/).collect { |v| parse_block(v) }.find { |v| !v.nil? }
-
-        # Set equivalent fields
-        data[:format] = data[:"storage format"]
-        data[:size] = data[:"logical size"].split(/\s+/)[0] if data.has_key?(:"logical size")
-
-        # Return new object
-        new(data)
-      rescue Exceptions::CommandFailedException
-        raise if raise_errors
-        nil
+        all.find { |hd| hd.uuid == id }
       end
 
-      def populate_relationship(caller, doc)
-        result = Proxies::Collection.new(caller)
-
-        doc.css("MediaRegistry HardDisks HardDisk").each do |hd_node|
-          data = {}
-          hd_node.attributes.each do |key, value|
-            data[key.downcase.to_sym] = value.to_s
-          end
-
-          # Strip the brackets off of UUID
-          data[:uuid] = data[:uuid][1..-2]
-
-          # Expand location relative to config location
-          data[:location] = Global.expand_path(data[:location]) if data[:location]
-
-          result << new(data)
-        end
-
-        result
+      # Override of {Medium.device_type}.
+      def device_type
+        :hard_disk
       end
     end
 
@@ -139,34 +110,27 @@ module VirtualBox
     # here. If no format is specified, the format of the source drive
     # will be used.
     #
-    # @param [String] outputfile The output file. This should be just a
-    #   single filename, since VirtualBox will place it in the hard
-    #   drives folder.
+    # @param [String] outputfile The output file. This can be a full path
+    #   or just a filename. If its just a filename, it will be placed in
+    #   the default hard drives directory.
     # @param [String] format The format to convert to.
     # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
     #   will be raised if the command failed.
     # @return [HardDrive] The new, cloned hard drive, or nil on failure.
-    def clone(outputfile, format="VDI", raise_errors=false)
-      raw = Command.vboxmanage("clonehd", uuid, outputfile, "--format", format, "--remember")
-      return nil unless raw =~ /UUID: (.+?)$/
+    def clone(outputfile, format="VDI")
+      # Get main VirtualBox object
+      virtualbox = Lib.lib.virtualbox
 
-      self.class.find($1.to_s)
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      nil
-    end
+      # Expand path relative to the default hard disk folder. This allows
+      # filenames to exist in the default folder while full paths will use
+      # the paths specified.
+      outputfile = File.expand_path(outputfile, virtualbox.system_properties.default_hard_disk_folder)
 
-    # Override of {Image#image_type}.
-    def image_type
-      "hdd"
-    end
-
-    # Validates a hard drive.
-    def validate
-      super
+      # Create the new medium. This simply creates a new IMedium structure
+      new_medium = virtualbox.create_hard_disk(format, outputfile)
 
-      validates_presence_of :format
-      validates_presence_of :size
+      # Clone the current drive
+      interface.clone_to(new_medium, :standard, nil).wait_for_completion(-1)
     end
 
     # Creates a new hard drive.
@@ -182,14 +146,8 @@ module VirtualBox
         return false
       end
 
-      raw = Command.vboxmanage("createhd", "--filename", location, "--size", size, "--format", read_attribute(:format), "--remember")
-      return nil unless raw =~ /UUID: (.+?)$/
-
-      # Just replace our attributes with the newly created ones. This also
-      # will set new_record to false.
-      populate_attributes(self.class.find($1.to_s).attributes)
+      # TODO
 
-      # Return the success of the command
       true
     rescue Exceptions::CommandFailedException
       raise if raise_errors
@@ -214,30 +172,5 @@ module VirtualBox
         super
       end
     end
-
-    # Destroys the hard drive. This deletes the hard drive off
-    # of disk.
-    #
-    # **This operation is not reversable.**
-    #
-    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
-    #   will be raised if the command failed.
-    # @return [Boolean] True if command was successful, false otherwise.
-    def destroy(raise_errors=false)
-      Command.vboxmanage("closemedium", "disk", uuid, "--delete")
-      true
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
-    end
-
-    # Lazy load the lazy attributes for this model.
-    def load_attribute(name)
-      # Since the lazy attributes are related, we just load them all at once
-      loaded_hd = self.class.find(uuid, true)
-
-      write_attribute(:size, loaded_hd.size)
-      write_attribute(:accessible, loaded_hd.accessible)
-    end
   end
 end

data/lib/virtualbox/lib.rb

@@ -0,0 +1,82 @@
+module VirtualBox
+  # Used by the rest of the VirtualBox library to interface with
+  # the VirtualBox XPCOM library (VBoxXPCOMC). Most users will never need
+  # to interface with this class directly, except other to set the path to
+  # the `VBoxXPCOMC` lib.
+  #
+  # # Setting the Path to the VBoxXPCOMC Library
+  #
+  # This won't be necessary for 95% of users, and won't be necessary at all
+  # for windows users. But for unix users, the VirtualBox gem uses a dynamic
+  # library named `VBoxXPCOMC` to interface with VirtualBox. The gem does its
+  # best to guess the path to this gem based on the operating system ruby is
+  # running on, but in the case you get an error about it missing, you can
+  # easily set it:
+  #
+  #     VirtualBox::Lib.lib_path = "/path/to/VBoxXPCOMC.so"
+  #
+  # **Windows users will never need to do this.**
+  #
+  class Lib
+    @@lib_path = nil
+    @@lib = nil
+
+    attr_reader :interface
+    attr_reader :virtualbox
+    attr_reader :session
+
+    class <<self
+      # Resets the initialized library (if there is any). This is primarily only
+      # used for testing.
+      def reset!
+        @@lib = nil
+      end
+
+      # The singleton instance of Lib.
+      #
+      # @return [Lib]
+      def lib
+        @@lib ||= new(lib_path)
+      end
+
+      # Sets the path to the VBoxXPCOMC library which is created with any
+      # VirtualBox install. 90% of the time, this won't have to be set manually,
+      # and instead the gem will try to find it for you.
+      #
+      # @param [String] Full path to the VBoxXPCOMC library
+      def lib_path=(value)
+        @@lib_path = value.nil? ? value : File.expand_path(value)
+      end
+
+      # Returns the path to the virtual box library. If the path
+      # has not yet been set, it attempts to infer it based on the
+      # platform ruby is running on.
+      def lib_path
+        if @@lib_path.nil?
+          if Platform.mac?
+            @@lib_path = ["/Applications/VirtualBox.app/Contents/MacOS/VBoxXPCOMC.dylib"]
+          elsif Platform.linux?
+            @@lib_path = ["/opt/VirtualBox/VBoxXPCOMC.so", "/usr/lib/virtualbox/VBoxXPCOMC.so"]
+          elsif Platform.windows?
+            @@lib_path = "Unknown"
+          else
+            @@lib_path = "Unknown"
+          end
+        end
+
+        @@lib_path
+      end
+    end
+
+    def initialize(lib_path)
+      if Platform.windows?
+        @interface = COM::MSCOMInterface.new
+      else
+        @interface = COM::FFIInterface.create(lib_path)
+      end
+
+      @virtualbox = @interface.virtualbox
+      @session = @interface.session
+    end
+  end
+end

data/lib/virtualbox/media.rb

@@ -2,18 +2,19 @@ module VirtualBox
   # Represents the media registry within the global VirtualBox configuration.
   class Media < AbstractModel
     attribute :parent, :readonly => true
-    relationship :hard_drives, HardDrive
-    relationship :dvds, DVD
+    relationship :hard_drives, :HardDrive
+    relationship :dvds, :DVD
 
     class <<self
-      def populate_relationship(caller, data)
-        new(caller, data)
+      def populate_relationship(caller, lib)
+        new(caller, lib)
       end
     end
 
-    def initialize(parent, document)
+    def initialize(parent, lib)
       populate_attributes({ :parent => parent }, :ignore_relationships => true)
-      populate_relationships(document)
+      populate_relationship(:hard_drives, lib.virtualbox.hard_disks)
+      populate_relationship(:dvds, lib.virtualbox.dvd_images)
     end
   end
 end

data/lib/virtualbox/medium.rb

@@ -0,0 +1,138 @@
+module VirtualBox
+  # Represents a medium object part of VirtualBox. A medium is a
+  # hard drive, DVD, floppy disk, etc. Each of these share common
+  # properties represented here.
+  class Medium < AbstractModel
+    include SubclassListing
+
+    attribute :uuid, :readonly => :true, :property => :id
+    attribute :description, :readonly => true
+    attribute :location, :readonly => true
+    attribute :state, :readonly => true, :property => :refresh_state
+    attribute :interface, :readonly => true, :property => false
+
+    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,
+      # while a {MediumAttachment} has a relationship with a single medium.
+      #
+      # **This method typically won't be used except internally.**
+      def populate_relationship(caller, media)
+        if media.is_a?(Array)
+          # has many relationship
+          populate_array_relationship(caller, media)
+        else
+          # has one relationship
+          populate_single_relationship(caller, media)
+        end
+      end
+
+      # Populates a relationship which has many media.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Medium>]
+      def populate_array_relationship(caller, media)
+        relation = Proxies::Collection.new(caller)
+
+        media.each do |medium|
+          # Skip media this class isn't interested in
+          next if device_type != :all && medium.device_type != device_type
+
+          # Wrap it up and add to the relationship
+          relation << new(medium)
+        end
+
+        relation
+      end
+
+      # Populates a relationship which has one medium. This method goes one step
+      # further and instantiates the proper class for the type of medium given.
+      # For example, given a `device_type` of `:hard_drive`, it would return a
+      # {HardDrive} object.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Medium]
+      def populate_single_relationship(caller, medium)
+        return nil if medium.nil?
+
+        subclasses.each do |subclass|
+          # Skip this class unless the device type matches
+          next unless subclass.device_type == medium.device_type
+
+          # Wrap it up and return it
+          return subclass.new(medium)
+        end
+
+        # If all else fails, just wrap it in a Medium
+        new(medium)
+      end
+
+      # Specifies the device type that a {Medium} class is interested in. This
+      # is `:all` on {Medium}, but is expected to be overridden by child classes.
+      # The value returned should be one of {COM::Interface::DeviceType}.
+      #
+      # @return [Symbol]
+      def device_type
+        :all
+      end
+    end
+
+    # Initializes a medium object, retrieving the attributes and information
+    # from the {COM::Interface::Medium} object given as the parameter. This initialization
+    # is done automatically by virtualbox when populating a relationship. Mediums should
+    # never be initialized manually.
+    #
+    # @param [COM::Interface::Medium] imedium
+    def initialize(imedium)
+      write_attribute(:interface, imedium)
+      initialize_attributes(imedium)
+    end
+
+    def initialize_attributes(imedium)
+      # First refresh the state (required for many attributes)
+      imedium.refresh_state
+
+      # Load interface attributes
+      load_interface_attributes(imedium)
+
+      # 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
+
+    # Returns the basename of the images location (the file name +extension)
+    #
+    # @return [String]
+    def filename
+      File.basename(location.to_s)
+    end
+
+    # Destroys the medium, optionally also phsyically destroying the backing
+    # storage. This removes this medium from the VirtualBox media registry.
+    # In order to remove the medium, it must not be attached to any virtual
+    # machine. If it is, an exception of some sort will be raised.
+    # This action happens *immediately* when the method is called, and is not
+    # deferred to a save.
+    def destroy(destroy_backing=false)
+      if destroy_backing
+        destroy_storage
+      else
+        interface.close
+      end
+    end
+
+    # Destroys the backing store of the medium and the media registry. This is
+    # analagous to calling {#destroy} with the first parameter set to true. This
+    # method requires that the medium not be attached to any virtual machine
+    # (running or not).
+    def destroy_storage
+      interface.delete_storage.wait_for_completion(-1)
+    end
+  end
+end