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 AbstractModel::Attributable.

attribute :parent, :readonly => :readonly
attribute :name
attribute :hostpath

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from AbstractModel

#errors, errors_for_relationship, #existing_record!, #inspect, #lazy_attribute?, #lazy_relationship?, #new_record!, #new_record?, #parent_machine, #populate_attributes, #populate_relationship, #populate_relationships, reload!, #reload!, reload?, reloaded!, #save!, #save_attribute, #save_changed_interface_attributes, #save_interface_attribute, #set_relationship, #write_attribute

Methods included from AbstractModel::Validatable

#__validates_extract_options, #add_error, #clear_errors, #errors, #errors_on, #full_error_messages, #valid?, #validates_format_of, #validates_inclusion_of, #validates_numericality_of, #validates_presence_of

Methods included from AbstractModel::Relatable

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

Methods included from AbstractModel::VersionMatcher

#assert_version_match, #split_version, #version_match?

Methods included from AbstractModel::Dirty

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

Methods included from AbstractModel::InterfaceAttributes

#load_interface_attribute, #load_interface_attributes, #save_interface_attribute, #save_interface_attributes, #spec_to_proc

Methods included from AbstractModel::Attributable

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

Methods included from Logger

included, #logger, #logger_output=

Constructor Details

#initialize(data = {}) ⇒ SharedFolder #initialize(interface) ⇒ SharedFolder

Returns a new instance of SharedFolder.

Overloads:

  • #initialize(data = {}) ⇒ SharedFolder

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

    Parameters:

    • data (Hash) (defaults to: {}) —

      (optional) A hash which contains initial attribute values for the SharedFolder.

  • #initialize(interface) ⇒ SharedFolder

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

    Parameters:

    • caller (Object) —

      The parent

    • data (Hash) —

      A hash of data which must be used to extract the relationship data.



133
134
135
136
137
138
139
 
# File 'lib/virtualbox/shared_folder.rb', line 133

def initialize(data=nil)
  super()

  if data
    initialize_attributes(data)
  end
end

Dynamic Method Handling

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

Class Method Details

.populate_relationship(caller, imachine) ⇒ Array<SharedFolder>

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

**This method typically won’t be used except internally.**

Returns:



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

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

  imachine.shared_folders.each do |ishared|
    relation << new(ishared)
  end

  relation
end

.save_relationship(caller, items) ⇒ Object

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

**This method typically won’t be used except internally.**



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

def save_relationship(caller, items)
  items.dup.each do |item|
    item.save
  end
end

Instance Method Details

#added_to_relationship(proxy) ⇒ Object

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



193
194
195
196
197
198
199
200
201
 
# File 'lib/virtualbox/shared_folder.rb', line 193

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

#create ⇒ Object

Creates a new shared folder. This method should not be called directly. Instead, #save should always be called, which will do the right thing.



179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/virtualbox/shared_folder.rb', line 179

def create
  return unless new_record?

  parent_machine.with_open_session do |session|
    machine = session.machine
    machine.create_shared_folder(name, host_path, writable)
  end

  existing_record!
  clear_dirty!
end

#destroy(update_collection = true) ⇒ Object

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.



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

def destroy(update_collection=true)
   parent.with_open_session do |session|
     machine = session.machine
     machine.remove_shared_folder(name)
   end

   # Remove it from it's parent collection
   parent_collection.delete(self, true) if parent_collection && update_collection

   # Mark as a new record so if it is saved again, it will create it
   new_record!
end

#initialize_attributes(ishared) ⇒ Object

Initializes the attributes of an existing shared folder.



142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/virtualbox/shared_folder.rb', line 142

def initialize_attributes(ishared)
  # Load the interface attributes
  load_interface_attributes(ishared)

  # 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

#save ⇒ Object

Saves or creates a shared folder.

Raises:



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

def save
  return true if !new_record? && !changed?
  raise Exceptions::ValidationFailedException.new(errors) if !valid?

  if !new_record?
    # If its not a new record, any changes will require a new shared
    # folder to be created, so we first destroy it then recreate it.
    destroy(false)
  end

  create
end

#validate ⇒ Object

Validates a shared folder.



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

def validate
  super

  validates_presence_of :parent
  validates_presence_of :name
  validates_presence_of :host_path
end