Class: VirtualBox::SharedFolder

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

Overview

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 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 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 SharedFolder

Overloads:

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

    Creates a new SharedFolder which is a new record. This should be attached to a VM and saved.

    Parameters:

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

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

    Parameters:

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


134
135
136
137
138
139
140
141
142
143
144
145
146
# File 'lib/virtualbox/shared_folder.rb', line 134

def initialize(*args)
  super()

  if args.length == 3
    initialize_for_relationship(*args)
  elsif args.length == 1
    initialize_for_data(*args)
  elsif args.length == 0
    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

+ (Array<SharedFolder>) populate_relationship(caller, doc)

Populates the shared folder relationship for anything which is related to it.

This method typically won't be used except internally.

Returns:



98
99
100
101
102
103
104
105
106
107
108
# File 'lib/virtualbox/shared_folder.rb', line 98

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

  counter = 1
  doc.css("Hardware SharedFolders SharedFolder").each do |folder|
    relation << new(counter, caller, folder)
    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.



114
115
116
117
118
119
# File 'lib/virtualbox/shared_folder.rb', line 114

def save_relationship(caller, data)
  # Just call save on each folder with the VM
  data.each do |sf|
    sf.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.



214
215
216
# File 'lib/virtualbox/shared_folder.rb', line 214

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

- (Boolean) destroy(raise_errors = false)

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.

Parameters:

Returns:

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


226
227
228
229
230
231
232
233
234
235
236
# File 'lib/virtualbox/shared_folder.rb', line 226

def destroy(raise_errors=false)
  # If the name changed, we have to be sure to use the previous
  # one.
  name_value = name_changed? ? name_was : name

  Command.vboxmanage("sharedfolder", "remove", parent.name, "--name", name_value)
  true
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end

- (Object) initialize_for_data(data)

Initializes a record with initial data but keeping it a "new record." This is called automatically if #initialize is given only a single parameter. View #initialize for documentation.



168
169
170
171
172
173
174
175
# File 'lib/virtualbox/shared_folder.rb', line 168

def initialize_for_data(data)
  self.class.attributes.each do |name, options|
    data[options[:populate_key]] = data[name]
  end

  populate_attributes(data)
  new_record!
end

- (Object) initialize_for_relationship(index, caller, data)

Initializes the record for use in a relationship. This is automatically called by #initialize if it has three parameters.

This method typically won't be used except internally.



153
154
155
156
157
158
159
160
161
162
163
# File 'lib/virtualbox/shared_folder.rb', line 153

def initialize_for_relationship(index, caller, data)
  # Setup the index specific attributes
  populate_data = {}
  data.attributes.each do |key, value|
    populate_data[key.downcase.to_sym] = value.to_s
  end

  populate_attributes(populate_data.merge({
    :parent => caller
  }))
end

- (Boolean) save(raise_errors = false)

Saves or creates a shared folder.

Parameters:

Returns:

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


191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
# File 'lib/virtualbox/shared_folder.rb', line 191

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

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

  # If this isn't a new record, we destroy it first
  destroy(raise_errors) if !new_record?

  Command.vboxmanage("sharedfolder", "add", parent.name, "--name", name, "--hostpath", hostpath)
  existing_record!
  clear_dirty!

  true
rescue Exceptions::CommandFailedException
  raise if raise_errors
  false
end

- (Object) validate

Validates a shared folder.



178
179
180
181
182
183
184
# File 'lib/virtualbox/shared_folder.rb', line 178

def validate
  super

  validates_presence_of :parent
  validates_presence_of :name
  validates_presence_of :hostpath
end