Class: VirtualBox::SharedFolder
- Inherits:
-
AbstractModel
- Object
- AbstractModel
- VirtualBox::SharedFolder
- 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.("~/Desktop/images") vm. << 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..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..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
- + (Array<SharedFolder>) populate_relationship(caller, doc) Populates the shared folder relationship for anything which is related to it.
- + (Object) save_relationship(caller, data) Saves the relationship.
Instance Method Summary
- - (Object) added_to_relationship(parent) Relationship callback when added to a collection.
- - (Boolean) destroy(raise_errors = false) Destroys the shared folder.
- - (SharedFolder) initialize(*args) constructor A new instance of SharedFolder.
- - (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.
- - (Object) initialize_for_relationship(index, caller, data) Initializes the record for use in a relationship.
- - (Boolean) save(raise_errors = false) Saves or creates a shared folder.
- - (Object) validate Validates a shared folder.
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
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.
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.
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, | data[[: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.
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 |