velir_virtualbox 0.8.4

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

@@ -0,0 +1,160 @@
+module VirtualBox
+  # Represents a single storage controller which can be attached to a
+  # virtual machine.
+  #
+  # **Currently, storage controllers can not be created from scratch.
+  # Therefore, the only way to use this model is through a relationship
+  # of a {VM} object.**
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the storage controller 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 => true
+  #     attribute :name
+  #     attribute :type
+  #     attribute :max_ports, :populate_key => :maxportcount
+  #     attribute :ports, :populate_key => :portcount
+  #
+  # ## Relationships
+  #
+  # In addition to the basic attributes, a virtual machine is related
+  # to other things. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :devices, AttachedDevice, :dependent => :destroy
+  #
+  class StorageController < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :name, :readonly => true
+    attribute :port_count
+    attribute :bus, :readonly => true
+    attribute :controller_type
+
+    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::Util.versioned_interface(:Machine))
+          populate_array_relationship(caller, data)
+        elsif data.is_a?(MediumAttachment)
+          populate_attachment_relationship(caller, data)
+        end
+      end
+
+      # Populates a has many relationship for a {VM}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<StorageController>]
+      def populate_array_relationship(caller, imachine)
+        relation = Proxies::Collection.new(caller)
+
+        imachine.storage_controllers.each do |icontroller|
+          relation << new(caller, icontroller)
+        end
+
+        relation
+      end
+
+      # Populates a single relationship for a {MediumAttachment}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<StorageController>]
+      def populate_attachment_relationship(caller, attachment)
+        # Find the storage controller with the matching name
+        attachment.parent.storage_controllers.find do |sc|
+          sc.name == attachment.controller_name
+        end
+      end
+
+      # Destroys a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      def destroy_relationship(caller, data, *args)
+        data.each { |v| v.destroy(*args) }
+      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, controllers)
+        controllers.each do |sc|
+          sc.save
+        end
+      end
+    end
+
+    # Since storage controllers still can't be created from scratch,
+    # this method shouldn't be called. Instead, storage controllers
+    # can be retrieved through relationships of other models such
+    # as {VM}.
+    def initialize(caller, icontroller)
+      super()
+
+      populate_attributes({
+        :parent => caller,
+        :interface => icontroller
+      }, :ignore_relationships => true)
+      load_interface_attributes(icontroller)
+      clear_dirty!
+    end
+
+    # Retrieves the array of medium attachments related to this storage controller.
+    # This is not implemented as a relationship simply because it would have been
+    # difficult to do so (circular) and its not really necessary.
+    def medium_attachments
+      parent.medium_attachments.find_all do |ma|
+        ma.storage_controller == self
+      end
+    end
+
+    # Saves the storage controller. This method shouldn't be called directly.
+    # Instead, {VM#save} should be called, which will save all attached storage
+    # controllers as well. This will setup the proper parameter for `interface`
+    # here.
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+        save_changed_interface_attributes(machine.get_storage_controller_by_name(name))
+      end
+    end
+
+    # Destroys the storage controller. This first detaches all attachments on this
+    # storage controller. Note that this does *not* delete the media on the attachments,
+    # unless specified by the options.
+    def destroy(*args)
+      # First remove all attachments
+      medium_attachments.each do |ma|
+        ma.destroy(*args)
+      end
+
+      # Finally, remove ourselves
+      parent.with_open_session do |session|
+        machine = session.machine
+        machine.remove_storage_controller(name)
+      end
+    end
+  end
+end

data/lib/virtualbox/system_properties.rb

@@ -0,0 +1,73 @@
+module VirtualBox
+  # Represents the system properties associated with this VirtualBox
+  # installation. Many of these properties are readonly and represent
+  # limits on the system (max RAM available, max CPU, etc.). There are
+  # also configurable options which can be saved such as the default
+  # hard disk folder, or default machine folder.
+  class SystemProperties < AbstractModel
+    attribute :interface, :readonly => true, :property => false
+    attribute :min_guest_ram, :readonly => true
+    attribute :max_guest_ram, :readonly => true
+    attribute :min_guest_vram, :readonly => true
+    attribute :max_guest_vram, :readonly => true
+    attribute :min_guest_cpu_count, :readonly => true
+    attribute :max_guest_cpu_count, :readonly => true
+    attribute :info_vd_size, :readonly => true
+    attribute :network_adapter_count, :readonly => true
+    attribute :serial_port_count, :readonly => true
+    attribute :parallel_port_count, :readonly => true
+    attribute :max_boot_position, :readonly => true
+    attribute :default_machine_folder
+    attribute :medium_formats, :readonly => true
+    attribute :default_hard_disk_format
+    attribute :vrde_auth_library
+    attribute :web_service_auth_library
+    attribute :log_history_count
+    attribute :default_audio_driver, :readonly => true
+
+    class << self
+      # Populates the system properties relationship for anything
+      # which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [SystemProperties]
+      def populate_relationship(caller, data)
+        new(data)
+      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
+
+    # Initializes the system properties object. This shouldn't be called
+    # directly. Instead `Global#system_properties` should be used to
+    # retrieve this object.
+    def initialize(isysprop)
+      initialize_attributes(isysprop)
+    end
+
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(isysprop)
+      # Save the interface to an attribute
+      write_attribute(:interface, isysprop)
+
+      # Load the attributes from the interface
+      load_interface_attributes(interface)
+
+      # Clear dirty and mark as existing
+      clear_dirty!
+      existing_record!
+    end
+
+    # Saves the system properties.
+    def save
+      save_changed_interface_attributes(interface)
+    end
+  end
+end

data/lib/virtualbox/usb_controller.rb

@@ -0,0 +1,59 @@
+module VirtualBox
+  # Represents a USB controller within VirtualBox. This class is a relationship
+  # to {VM} objects.
+  class USBController < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :enabled, :boolean => true
+    attribute :enabled_ehci, :boolean => true
+    attribute :usb_standard, :readonly => true
+    relationship :device_filters, :USBDeviceFilter
+
+    class << self
+      # Populates the USB controller relationship for anything
+      # which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [USBController]
+      def populate_relationship(caller, machine)
+        new(caller, machine.usb_controller)
+      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(parent, iusb)
+      initialize_attributes(parent, iusb)
+    end
+
+    def initialize_attributes(parent, iusb)
+      # Write the parent and interface attributes
+      write_attribute(:parent, parent)
+      write_attribute(:interface, iusb)
+
+      # Load the interface attributes
+      load_interface_attributes(interface)
+
+      # Setup the relationships
+      populate_relationships(interface)
+
+      # Clear dirty and mark as existing
+      clear_dirty!
+      existing_record!
+    end
+
+    # Saves the USB controller.
+    def save
+      parent.with_open_session do |session|
+        save_changed_interface_attributes(session.machine.usb_controller)
+      end
+    end
+  end
+end