Class: VirtualBox::AttachedDevice

Inherits:
AbstractModel show all
Defined in:
lib/virtualbox/attached_device.rb

Overview

Represents an device which is attached to a storage controller. An example of such a device would be a CD or hard drive attached to an IDE controller.

Creating a New Attached Device

Creating a new attached device is simple. The following is a simple example of creating a DVD with an empty drive:

ad = VirtualBox::AttachedDevice.new
ad.port = 0
ad.image = VirtualBox::DVD.empty_drive
storage_controller.devices << ad
ad.save

The only quirk is that the attached device must be attached to a storage controller. The above assumes that storage_controller exists, which adds the device.

Any Image subclass can be set to the image relationship.

The following is an example using VM.find:

# First creating the new device...
ad = VirtualBox::AttachedDevice.new
ad.port = 0
ad.image = VirtualBox::DVD.empty_drive

# Now attaching to existing VM
vm = VirtualBox::VM.find("FooVM")
vm.storage_controllers[0].devices << ad
vm.save

The interesting thing in this example is that the save method is called on the virtual machine rather than the AttachedDevice. This will actually work as expected! Saving a virtual machine automatically saves all it's relationships as well.

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 => true
attribute :uuid
attribute :medium
attribute :port

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 :image, Image

Class Method Summary

Instance Method Summary

Methods inherited from AbstractModel

#errors, #existing_record!, #inspect, #lazy_attribute?, #lazy_relationship?, #new_record!, #new_record?, #populate_attributes, #populate_relationship, #populate_relationships, reload!, #reload!, reload?, reloaded!, #save_attribute, #set_relationship, #write_attribute

Methods included from AbstractModel::Attributable

#attributes, #has_attribute?, included, #lazy_attribute?, #loaded_attribute?, #populate_attributes, #read_attribute, #readonly_attribute?, #write_attribute

Methods included from AbstractModel::Dirty

#changed?, #changes, #clear_dirty!, #ignore_dirty, #method_missing, #set_dirty!

Methods included from AbstractModel::Relatable

#destroy_relationship, #destroy_relationships, #has_relationship?, included, #lazy_relationship?, #loaded_relationship?, #populate_relationship, #populate_relationships, #read_relationship, #relationship_data, #save_relationship, #save_relationships, #set_relationship

Methods included from AbstractModel::Validatable

#add_error, #clear_errors, #errors, #valid?, #validates_presence_of

Constructor Details

- (Object) initialize(data = {}) - (Object) initialize(index, caller, data)

A new instance of AttachedDevice

Overloads:

  • - (Object) initialize(data = {})

    Creates a new AttachedDevice which is a new record. This should be attached to a storage controller and saved.

    Parameters:

    • (Hash) data — (optional) A hash which contains initial attribute values for the AttachedDevice.
  • - (Object) initialize(index, caller, data)

    Creates an AttachedDevice for a relationship. This should never be called except internally.

    Parameters:

    • (Integer) index — Index of the port
    • (Object) caller — The parent
    • (Hash) data — A hash of data which must be used to extract the relationship data. 


127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/virtualbox/attached_device.rb', line 127

def initialize(*args)
  super()

  if args.length == 3
    populate_from_data(*args)
  elsif args.length == 1
    populate_attributes(*args)
    new_record!
  elsif args.empty?
    return
  else
    raise NoMethodError.new
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class VirtualBox::AbstractModel::Dirty

Class Method Details

+ (Object) destroy_relationship(caller, data, *args)

Destroy attached devices associated with another model.

This method typically won't be used except internally.



99
100
101
 
# File 'lib/virtualbox/attached_device.rb', line 99

def destroy_relationship(caller, data, *args)
  data.each { |v| v.destroy(*args) }
end

+ (Array<AttachedDevice>) populate_relationship(caller, data)

Populate relationship with another model.

This method typically won't be used except internally.

Returns:



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/virtualbox/attached_device.rb', line 84

def populate_relationship(caller, data)
  relation = Proxies::Collection.new(caller)

  counter = 0
  data.css("AttachedDevice").each do |ad|
    relation << new(counter, caller, ad)
    counter += 1
  end

  relation
end

+ (Object) save_relationship(caller, data)

Saves the relationship. This simply calls #save on every member of the relationship.

This method typically won't be used except internally.



107
108
109
110
111
112
 
# File 'lib/virtualbox/attached_device.rb', line 107

def save_relationship(caller, data)
  # Just call save on each nic with the VM
  data.each do |ad|
    ad.save
  end
end

Instance Method Details

- (Object) added_to_relationship(parent)

Relationship callback when added to a collection. This is automatically called by any relationship collection when this object is added.



220
221
222
 
# File 'lib/virtualbox/attached_device.rb', line 220

def added_to_relationship(parent)
  write_attribute(:parent, parent)
end

- (Boolean) destroy(options = {}, raise_errors = false)

Destroys the attached device. By default, this only removes any media inserted within the device, but does not destroy it. This option can be specified, however, through the destroy_image option.

Parameters:

Options Hash (options):

  • (Boolean) :destroy_image — default: false —If true, will also destroy the image associated with device.

Returns:

  • (Boolean) — True if command was successful, false otherwise. 


207
208
209
210
211
212
213
214
215
216
 
# File 'lib/virtualbox/attached_device.rb', line 207

def destroy(options={}, raise_errors=false)
  # parent = storagecontroller
  # parent.parent = vm
  destroy_port = options[:port] || port
  Command.vboxmanage("storageattach", parent.parent.name, "--storagectl", parent.name, "--port", destroy_port, "--device", "0", "--medium", "none")
  image.destroy(raise_errors) if options[:destroy_image] && image
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end

- (String) medium

Medium of the attached image. This attribute will be dependent on the attached image and will return one of the following values:

  • none - There is no attached image
  • emptydrive - An image with an empty drive is attached (see DVD.empty_drive)
  • image uuid - The image's UUID

Returns:

  • (String) 


187
188
189
190
191
192
193
194
195
 
# File 'lib/virtualbox/attached_device.rb', line 187

def medium
  if image.nil?
    "none"
  elsif image.empty_drive?
    "emptydrive"
  else
    image.uuid
  end
end

- (Boolean) save(raise_errors = false)

Saves or creates an attached device.

Parameters:

Returns:

  • (Boolean) — True if command was successful, false otherwise. 


156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/virtualbox/attached_device.rb', line 156

def save(raise_errors=false)
  return true unless changed?

  if !valid?
    raise Exceptions::ValidationFailedException.new(errors) if raise_errors
    return false
  end

  # If the port changed, we have to destroy the old one, then create
  # a new one
  destroy({:port => port_was}, raise_errors) if port_changed? && !port_was.nil?

  Command.vboxmanage("storageattach", parent.parent.name, "--storagectl", parent.name, "--port", port, "--device", "0", "--type", image.image_type, "--medium", medium)
  existing_record!
  clear_dirty!

  true
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end

- (Object) validate

Validates an attached device.



143
144
145
146
147
148
149
 
# File 'lib/virtualbox/attached_device.rb', line 143

def validate
  super

  validates_presence_of :parent
  validates_presence_of :image
  validates_presence_of :port
end