Struct VirtualBox

Source

pub struct VirtualBox { /* private fields */ }

Expand description

The VirtualBox interface represents the main interface exposed by the product that provides virtual machine management.

Reference to the official documentation:

https://www.virtualbox.org/sdkref/interface_i_virtual_box.html

Implementations§

Source §

impl VirtualBox

Source

pub fn get_version(&self) -> Result<&'static str, VboxError>

A string representing the version number of the product.

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let version = vbox.get_version().unwrap();

println!("{}", version);

Source

pub fn get_version_normalized(&self) -> Result<&'static str, VboxError>

A string representing the version number of the product, without the publisher information (but still with other tags).

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let version_normalized = vbox.get_version_normalized().unwrap();

println!("{}", version_normalized);

Source

pub fn get_revision(&self) -> Result<u32, VboxError>

The internal build revision number of the product.

§Returns

Returns u32 success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let revision = vbox.get_revision().unwrap();

println!("{:?}", revision);

Source

pub fn get_package_type(&self) -> Result<&'static str, VboxError>

A string representing the package type of this product.

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let package_type = vbox.get_package_type().unwrap();

println!("{}", package_type);

Source

pub fn get_api_version(&self) -> Result<&'static str, VboxError>

A string representing the VirtualBox API version number.

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let api_version = vbox.get_api_version().unwrap();

println!("{}", api_version);

Source

pub fn get_api_revision(&self) -> Result<i64, VboxError>

The internal build revision number of the product.

§Returns

Returns i64 success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let api_revision = vbox.get_api_revision().unwrap();

println!("{:?}", api_revision);

Source

pub fn get_home_folder(&self) -> Result<&'static str, VboxError>

Full path to the directory where the global settings file, VirtualBox.xml, is stored.

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let home_folder = vbox.get_home_folder().unwrap();

println!("{}", home_folder);

Source

pub fn get_settings_file_path(&self) -> Result<&'static str, VboxError>

Full name of the global settings file.

§Returns

Returns a &str success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let settings_file_path = vbox.get_settings_file_path().unwrap();

println!("{}", settings_file_path);

Source

pub fn get_host(&self) -> Result<Host, VboxError>

Associated host object.

§Returns

Returns Host on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();

let host = vbox.get_host();

Source

pub fn get_system_properties(&self) -> Result<SystemProperties, VboxError>

Associated system information object.

§Returns

Returns SystemProperties on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let system_properties = vbox.get_system_properties();

Source

pub fn get_machines(&self) -> Result<Vec<Machine>, VboxError>

Vector of machine objects registered within this VirtualBox instance.

§Returns

Returns Vec<Machine> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let machines = vbox.get_machines();

Source

pub fn get_machine_groups(&self) -> Result<Vec<&'static str>, VboxError>

Array of all machine group names which are used by the machines which are accessible.

§Returns

Returns Vec<&str> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let machines = vbox.get_machine_groups().unwrap();

Source

pub fn get_hard_disks(&self) -> Result<Vec<Medium>, VboxError>

Array of medium objects known to this VirtualBox installation.

§Returns

Returns Vec<Medium> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let hard_disks = vbox.get_hard_disks().unwrap();

Source

pub fn get_dvd_images(&self) -> Result<Vec<Medium>, VboxError>

Array of CD/DVD image objects currently in use by this VirtualBox instance.

§Returns

Returns Vec<Medium> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let images = vbox.get_dvd_images().unwrap();

Source

pub fn get_floppy_images(&self) -> Result<Vec<Medium>, VboxError>

Array of floppy image objects currently in use by this VirtualBox instance.

§Returns

Returns Vec<Medium> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let images = vbox.get_dvd_images().unwrap();

Source

pub fn get_progress_operations(&self) -> Result<Vec<Progress>, VboxError>

Array of ProgressOperations objects currently in use by this VirtualBox instance.

§Returns

Returns Vec<Progress> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let progress = vbox.get_progress_operations().unwrap();

Source

pub fn get_guest_os_types(&self) -> Result<Vec<GuestOSType>, VboxError>

Array of GuestOSTypes objects currently in use by this VirtualBox instance.

§Returns

Returns Vec<GuestOSType> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let guest_os_types = vbox.get_guest_os_types().unwrap();

Source

pub fn get_shared_folders(&self) -> Result<Vec<SharedFolder>, VboxError>

Collection of global shared folders.

Global shared folders are available to all virtual machines.

New shared folders are added to the collection using createSharedFolder. Existing shared folders can be removed using removeSharedFolder.

§Returns

Returns Vec<GuestOSType> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let shared_folders = vbox.get_shared_folders().unwrap();

Source

pub fn get_performance_collector( &self, ) -> Result<PerformanceCollector, VboxError>

Associated performance collector object.

§Returns

Returns PerformanceCollector on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let performance_collector = vbox.get_performance_collector().unwrap();

Source

pub fn get_dhcp_servers(&self) -> Result<Vec<DHCPServer>, VboxError>

DHCP servers.

§Returns

Returns Vec<DHCPServer> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let dhcp_servers = vbox.get_dhcp_servers().unwrap();

Source

pub fn get_nat_networks(&self) -> Result<Vec<NATNetwork>, VboxError>

NAT Network.

§Returns

Returns Vec<NATNetwork> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let nat_networks = vbox.get_nat_networks().unwrap();

Source

pub fn get_event_source(&self) -> Result<EventSource, VboxError>

Event source for VirtualBox events.

§Returns

Returns EventSource on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let event_source = vbox.get_event_source();

Source

pub fn get_extension_pack_manager(&self) -> Result<ExtPackManager, VboxError>

The extension pack manager.

§Returns

Returns ExtPackManager on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let extension_pack_manager = vbox.get_extension_pack_manager().unwrap();

Source

pub fn get_internal_networks(&self) -> Result<Vec<&'static str>, VboxError>

Names of all internal networks.

§Returns

Returns Vec<&str> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let internal_networks = vbox.get_internal_networks().unwrap();

Source

pub fn get_generic_network_drivers( &self, ) -> Result<Vec<&'static str>, VboxError>

Names of all generic network drivers.

§Returns

Returns Vec<&str> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let generic_network_drivers = vbox.get_generic_network_drivers().unwrap();

Source

pub fn compose_machine_filename( &self, name: &str, group: &str, create_flags: &str, base_folder: &str, ) -> Result<&'static str, VboxError>

Returns a recommended full path of the settings file name for a new virtual machine.

This API serves two purposes:

It gets called by createMachine if empty string (which is recommended) is specified for the settingsFile argument there, which means that API should use a recommended default file name.

It can be called manually by a client software before creating a machine, e.g. if that client wants to pre-create the machine directory to create virtual hard disks in that directory together with the new machine settings file. In that case, the file name should be stripped from the full settings file path returned by this function to obtain the machine directory.

See Machine::get_name and VirtualBox::create_machine for more details about the machine name.

groupName defines which additional subdirectory levels should be included. It must be either a valid group name or null or empty string which designates that the machine will not be related to a machine group.

If baseFolder is a null or empty string (which is recommended), the default machine settings folder (see ISystemProperties::defaultMachineFolder) will be used as a base folder for the created machine, resulting in a file name like “/home/user/VirtualBox VMs/name/name.vbox”. Otherwise the given base folder will be used.

This method does not access the host disks. In particular, it does not check for whether a machine with this name already exists.

§Arguments

name - &str. Suggested machine name.
group - &str. Machine group name for the new machine or machine group. It is used to determine the right subdirectory.
create_flags - &str. Machine creation flags, see VirtualBox::create_machine (optional).
base_folder - &str. Base machine folder (optional).

§Returns

Returns fully qualified path where the machine would be created (&str) on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let machine_filename = vbox.compose_machine_filename(
    "machine1",
    "",
    "",
    ""
).unwrap();

Source

pub fn create_machine( &self, settings_file: &str, name: &str, platform: PlatformArchitecture, groups: Vec<&str>, os_type_id: &str, flags: &str, cipher: &str, password_id: &str, password: &str, ) -> Result<Machine, VboxError>

Creates a new virtual machine by creating a machine settings file at the given location.

VirtualBox machine settings files use a custom XML dialect. Starting with VirtualBox 4.0, a “.vbox” extension is recommended, but not enforced, and machine files can be created at arbitrary locations.

However, it is recommended that machines are created in the default machine folder (e.g. “/home/user/VirtualBox VMs/name/name.vbox”; see SystemProperties::get_default_machine_folder). If you specify null or empty string (which is recommended) for the settingsFile argument, VirtualBox::compose_machine_filename is called automatically to have such a recommended name composed based on the machine name given in the name argument and the primary group.

If the resulting settings file already exists, this method will fail, unless the forceOverwrite flag is set.

The new machine is created unregistered, with the initial configuration set according to the specified guest OS type. A typical sequence of actions to create a new virtual machine is as follows:

Call this method to have a new machine created. The returned machine object will be “mutable” allowing to change any machine property.

Configure the machine using the appropriate attributes and methods.

Call Machine::save_settings to write the settings to the machine’s XML settings file. The configuration of the newly created machine will not be saved to disk until this method is called.

Call VirtualBox::register_machine to add the machine to the list of machines known to VirtualBox.

The specified guest OS type identifier must match an ID of one of known guest OS types listed in the IVirtualBox::guestOSTypes array.

§Arguments

settings_file - &str. Fully qualified path where the settings file should be created, empty string for a default folder and file based on the name argument and the primary group. (see VirtualBox::compose_machine_filename).
name - &str. Machine name.
groups - Vec<&str>. Array of group names. null or an empty array have the same meaning as an array with just the empty string or “/”, i.e. create a machine without group association.
os_type_id - &str. Guest OS Type ID.
flags - &str. Additional property parameters, passed as a comma-separated list of “name=value” type entries. The following ones are recognized: forceOverwrite=1 to overwrite an existing machine settings file, UUID=uuid to specify a machine UUID and directoryIncludesUUID=1 to switch to a special VM directory naming scheme which should not be used unless necessary.
cipher - &str. The cipher. It should be empty if encryption is not required.
password_id - &str. The password id. It should be empty if encryption is not required.
password - &str. The password. It should be empty if encryption is not required.

§Returns

Returns Machine on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};use virtualbox_rs::enums::PlatformArchitecture;

let vbox = VirtualBox::init().unwrap();

let machine = vbox.create_machine(
    "",
    "machine1",
    PlatformArchitecture::X86,
    vec![],
    "Ubuntu (64-bit)",
    "",
    "",
    "",
    ""
).unwrap();
machine.save_settings().unwrap();

Source

pub fn register_machine(&self, machine: &Machine) -> Result<(), VboxError>

Registers the machine previously created using createMachine or opened using openMachine within this VirtualBox installation.

After successful method invocation, the MachineRegisteredEvent event is fired.

This method implicitly calls Machine::save_settings to save all current machine settings before registering it.

§Arguments

machine - Machine.

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let machine = vbox.open_machine(
    "/home/host_user/VirtualBox VMs/machine1/machine1.vbox",
    ""
).unwrap();
vbox.register_machine(&machine).unwrap()

Source

pub fn find_machines(&self, name_or_id: &str) -> Result<Machine, VboxError>

Attempts to find a virtual machine given its name or UUID.

§Arguments

name_or_id - What to search for. This can either be the UUID or the name of a virtual machine.

§Returns

Returns Machine on success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let machine = vbox.
        find_machines("Freebsd_14").unwrap();

Source

pub fn get_machines_by_groups( &self, groups: Vec<&str>, ) -> Result<Vec<Machine>, VboxError>

Gets all machine references which are in one of the specified groups.

§Arguments

groups - Vec<&str>. What groups to match. The usual group list rules apply, i.e. passing an empty list will match VMs in the toplevel group, likewise the empty string.

§Returns

Returns Vec<Machine> on success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let machines = vbox.
        get_machines_by_groups(vec!["/"]).unwrap();

Source

pub fn get_machine_states( &self, machines: Vec<&Machine>, ) -> Result<Vec<MachineState>, VboxError>

Gets the state of several machines in a single operation.

§Arguments

machines - Vec<Machine>. Vector with the machine references.

§Returns

Returns Vec<Machine> on success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let machines = vbox.
        get_machines_by_groups(vec!["/"]).unwrap();
let states = vbox.get_machine_states(machines.iter().collect()).unwrap();

Source

pub fn create_appliance(&self) -> Result<Appliance, VboxError>

Creates a new appliance object, which represents an appliance in the Open Virtual Machine Format (OVF).

This can then be used to import an OVF appliance into VirtualBox or to export machines as an OVF appliance; see the documentation for Appliance for details.

§Returns

Returns Appliance on success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let appliance = vbox.create_appliance().unwrap();

Source

pub fn create_unattended_installer(&self) -> Result<Unattended, VboxError>

Creates a new Unattended guest installation object.

This can be used to analyze an installation ISO to create and configure a new machine for it to be installed on. It can also be used to (re)install an existing machine.

§Returns

Returns Unattended on success, or a VboxError on failure.

§Example


use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();
let unattended_installer = vbox.create_unattended_installer().unwrap();

Source

pub fn create_medium( &self, format: &str, location: &str, access_mode: AccessMode, a_device_type_type: DeviceType, ) -> Result<Medium, VboxError>

Creates a new base medium object that will use the given storage format and location for medium data.

§Arguments

format - &str. Identifier of the storage format to use for the new medium.
location - &str. Location of the storage unit for the new medium.
access_mode - AccessMode. Whether to open the image in read/write or read-only mode. For a “DVD” device type, this is ignored and read-only mode is always assumed.
a_device_type_type - DeviceType. Must be one of “HardDisk”, “DVD” or “Floppy”.

§Returns

Returns Medium on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};
use virtualbox_rs::enums::{AccessMode, DeviceType};

let vbox = VirtualBox::init().unwrap();
let medium = vbox.create_medium(
    "",
    "/",
    AccessMode::ReadWrite,
    DeviceType::HardDisk
).unwrap();

Source

pub fn open_medium( &self, location: &str, a_device_type_type: DeviceType, access_mode: AccessMode, force_new_uuid: bool, ) -> Result<Medium, VboxError>

Finds existing media or opens a medium from an existing storage location.

§Arguments

location - &str. Location of the storage unit for the new medium.
a_device_type_type - DeviceType. Must be one of “HardDisk”, “DVD” or “Floppy”.
access_mode - AccessMode. Whether to open the image in read/write or read-only mode. For a “DVD” device type, this is ignored and read-only mode is always assumed.
force_new_uuid - bool. Allows the caller to request a completely new medium UUID for the image which is to be opened. Useful if one intends to open an exact copy of a previously opened image, as this would normally fail due to the duplicate UUID.

§Returns

Returns Medium on success, or a VboxError on failure.

§Example


use virtualbox_rs::{ VirtualBox};
use virtualbox_rs::enums::{AccessMode, DeviceType};

let vbox = VirtualBox::init().unwrap();
let medium = vbox.open_medium(
    "",
    DeviceType::HardDisk,
    AccessMode::ReadWrite,
    false
).unwrap();

Source

pub fn get_guest_os_type(&self, id: &str) -> Result<GuestOSType, VboxError>

Returns an object describing the specified guest OS type.

The requested guest OS type is specified using a string which is a mnemonic identifier of the guest operating system, such as “win31” or “ubuntu”. The guest OS type ID of a particular virtual machine can be read or set using the Machine::get_os_type_id attribute.

The VirtualBox::get_guest_os_types collection contains all available guest OS type objects. Each object has an IGuestOSType::id attribute which contains an identifier of the guest OS this object describes.

While this function returns an error for unknown guest OS types, they can be still used without serious problems (if one accepts the fact that there is no default VM config information).

§Arguments

id - &str. Guest OS type ID string.

§Returns

Returns GuestOSType on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let medium = vbox.get_guest_os_type(
    "FreeBSD"
).unwrap();

Source

pub fn create_shared_folder( &self, name: &str, host_path: &str, writable: bool, automount: bool, auto_mount_point: &str, ) -> Result<(), VboxError>

Creates a new global shared folder by associating the given logical name with the given host path, adds it to the collection of shared folders and starts sharing it.

Refer to the description of SharedFolder to read more about logical names.

§Arguments

name - &str. Unique logical name of the shared folder.
host_path - &str. Full path to the shared folder in the host file system.
writable - bool. Whether the share is writable or readonly
automount - bool. Whether the share gets automatically mounted by the guest or not.
auto_mount_point - &str. Where the guest should automatically mount the folder, if possible. For Windows and OS/2 guests this should be a drive letter, while other guests it should be bsolute directory.

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
vbox.create_shared_folder(
    "shared1",
    "/mnt",
    false,
    false,
    ""
).unwrap();

Source

pub fn remove_shared_folder(&self, name: &str) -> Result<(), VboxError>

Removes the global shared folder with the given name previously created by VirtualBox::create_shared_folder from the collection of shared folders and stops sharing it.

§Arguments

name - &str. Logical name of the shared folder to remove.

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
vbox.remove_shared_folder(
    "shared1"
).unwrap();

Source

pub fn get_extra_data_keys(&self) -> Result<Vec<&'static str>, VboxError>

Returns an array representing the global extra data keys which currently have values defined.

§Returns

Returns Vec<&str> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let extra_data_keys = vbox.get_extra_data_keys().unwrap();

Source

pub fn get_extra_data(&self, key: &str) -> Result<&'static str, VboxError>

Returns associated global extra data.

If the requested data key does not exist, this function will succeed and return an empty string in the value argument.

§Arguments

key - &str. Name of the data key to get.

§Returns

Returns &str on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let extra_data = vbox.get_extra_data("GUI/LanguageID").unwrap();

Source

pub fn set_extra_data(&self, key: &str, value: &str) -> Result<(), VboxError>

Sets associated global extra data.

If you pass an empty string as a key value, the given key will be deleted.

§Arguments

key - &str. Name of the data key to set.
value - &str. Value to assign to the key.

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
vbox.set_extra_data("GUI/LanguageID", "en").unwrap();

Source

pub fn set_settings_secret(&self, password: &str) -> Result<(), VboxError>

Unlocks the secret data by passing the unlock password to the server.

The server will cache the password for that machine.

§Arguments

password - &str. The cipher key.

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
vbox.set_settings_secret("123").unwrap();

Source

pub fn create_dhcp_server(&self, name: &str) -> Result<DHCPServer, VboxError>

Creates a DHCP server settings to be used for the given internal network name.

§Arguments

name - &str. server name

§Returns

Returns DHCPServer on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let dhcp_server = vbox.create_dhcp_server("DHCP1").unwrap();

Source

pub fn find_dhcp_server_by_network_name( &self, name: &str, ) -> Result<DHCPServer, VboxError>

Searches a DHCP server settings to be used for the given internal network name.

§Arguments

name - &str. server name

§Returns

Returns DHCPServer on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let dhcp_server = vbox.find_dhcp_server_by_network_name("DHCP1").unwrap();

Source

pub fn remove_dhcp_server(&self, server: &DHCPServer) -> Result<(), VboxError>

Removes the DHCP server settings.

§Arguments

server - &str. DHCP server settings to be removed

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let dhcp_server = vbox.find_dhcp_server_by_network_name("DHCP1").unwrap();
vbox.remove_dhcp_server(&dhcp_server).unwrap()

Source

pub fn create_nat_network( &self, network_name: &str, ) -> Result<NATNetwork, VboxError>

Creates a NATNetwork

§Arguments

network_name - &str. Network name

§Returns

Returns NATNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let dhcp_server = vbox.find_dhcp_server_by_network_name("DHCP1").unwrap();

Source

pub fn find_nat_network_by_name( &self, name: &str, ) -> Result<NATNetwork, VboxError>

Searches a NATNetwork server settings to be used for the given internal network name.

§Arguments

name - &str. network name

§Returns

Returns DHCPServer on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let nat_network = vbox.find_nat_network_by_name("DHCP1").unwrap();

Source

pub fn remove_nat_network(&self, network: &NATNetwork) -> Result<(), VboxError>

Removes the NATNetwork settings.

§Arguments

network - &str. NATNetwork settings to be removed

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let network = vbox.find_nat_network_by_name("DHCP1").unwrap();
vbox.remove_nat_network(&network).unwrap()

Source

pub fn creat_cloud_network( &self, network_name: &str, ) -> Result<CloudNetwork, VboxError>

Creates a CloudNetwork

§Arguments

network_name - &str. Network name

§Returns

Returns CloudNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let cloud_network = vbox.creat_cloud_network("CN1").unwrap();

Source

pub fn find_cloud_network_by_name( &self, name: &str, ) -> Result<CloudNetwork, VboxError>

Searches a CloudNetwork server settings to be used for the given internal network name.

§Arguments

name - &str. network name

§Returns

Returns CloudNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let nat_network = vbox.find_nat_network_by_name("CN1").unwrap();

Source

pub fn remove_cloud_network( &self, network: &CloudNetwork, ) -> Result<(), VboxError>

Removes the CloudNetwork settings.

§Arguments

network - &str. CloudNetwork settings to be removed

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let network = vbox.find_cloud_network_by_name("CN1").unwrap();
vbox.remove_cloud_network(&network).unwrap()

Source

pub fn check_firmware_present( &self, platform_architecture: PlatformArchitecture, firmware_type: FirmwareType, version: &str, ) -> Result<(&str, &str, bool), VboxError>

Check if this VirtualBox installation has a firmware of the given type available, either system-wide or per-user.

Optionally, this may return a hint where this firmware can be downloaded from.

§Arguments

firmware_type - FirmwareType. Type of firmware to check.
version - &str. Expected version number, usually empty string (presently ignored).

§Returns

The method returns a tuple with the following values:

&str - Suggested URL to download this firmware from.
&str - Filename of firmware, only valid if result == true.
bool - Indicates if firmware of this type and version is available.

§Example


use virtualbox_rs::{VirtualBox};
use virtualbox_rs::enums::{FirmwareType, PlatformArchitecture};

let vbox = VirtualBox::init().unwrap();
let firmware_present = vbox.check_firmware_present(PlatformArchitecture::X86, FirmwareType::BIOS, "1.0.0").unwrap();

Source

pub fn get_host_only_networks(&self) -> Result<Vec<HostOnlyNetwork>, VboxError>

Names of all host-only networks.

§Returns

Returns Vec<HostOnlyNetwork> on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let networks = vbox.get_host_only_networks().unwrap();

Source

pub fn open_machine( &self, settings_file: &str, password: &str, ) -> Result<Machine, VboxError>

Opens a virtual machine from the existing settings file.

The opened machine remains unregistered until you call VirtualBox::register_machine.

The specified settings file name must be fully qualified. The file must exist and be a valid machine XML settings file whose contents will be used to construct the machine object.

§Arguments

settings_file - &str. Name of the machine settings file.
password - &str. The password. If the machine is not encrypted the parameter is ignored.

§Returns

Returns Machine on success, or a VboxError on failure.

§Example


use virtualbox_rs::{SystemProperties, VirtualBox};

let vbox = VirtualBox::init().unwrap();

let machine = vbox.open_machine(
    "/home/host_user/VirtualBox VMs/machine1/machine1.vbox",
    ""
).unwrap();

Source

pub fn create_host_only_network( &self, network_name: &str, ) -> Result<HostOnlyNetwork, VboxError>

Creates a HostOnlyNetwork

§Arguments

network_name - &str. Network name

§Returns

Returns HostOnlyNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let host_only_network = vbox.create_host_only_network("HON").unwrap();

Source

pub fn find_host_only_network_by_name( &self, name: &str, ) -> Result<HostOnlyNetwork, VboxError>

Searches a HostOnlyNetwork server settings to be used for the given internal network name.

§Arguments

name - &str. network name

§Returns

Returns HostOnlyNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let nat_network = vbox.find_nat_network_by_name("HON").unwrap();

Source

pub fn find_host_only_network_by_id( &self, id: &str, ) -> Result<HostOnlyNetwork, VboxError>

Searches a HostOnlyNetwork server settings to be used for the id.

§Arguments

id - &str. network id

§Returns

Returns HostOnlyNetwork on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let nat_network = vbox.find_host_only_network_by_id("HON").unwrap();

Source

pub fn remove_host_only_network( &self, network: &HostOnlyNetwork, ) -> Result<(), VboxError>

Removes the NATNetwork settings.

§Arguments

network - &str. NATNetwork settings to be removed

§Returns

Returns () on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let network = vbox.find_host_only_network_by_name("HON").unwrap();
vbox.remove_host_only_network(&network).unwrap()

Source

pub fn find_progress_by_id(&self, id: &str) -> Result<Progress, VboxError>

Searches through all progress objects known to VBoxSVC for an instance with the given GUID.

§Arguments

id - &str. GUID of the progress object to search for.

§Returns

Returns Progress on success, or a VboxError on failure.

§Example


use virtualbox_rs::{VirtualBox};

let vbox = VirtualBox::init().unwrap();
let progress = vbox.find_progress_by_id("ID").unwrap();

Source §

impl VirtualBox

Source

pub fn init() -> Result<Self, VboxError>

Initializes the VirtualBox.

§Returns

Returns VirtualBoxClient on success, or a VboxError on failure.

§Example

use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init().unwrap();

§Details

This method checks the VirtualBox version before initializing the virtualbox. It ensures compatibility and prevents potential issues due to version mismatches. Use this method if you have not checked the version beforehand.

Source

pub fn init_unchecked() -> Result<Self, VboxError>

Initializes the VirtualBox without checking the version.

§Returns

Returns VirtualBoxClient on success, or a VboxError on failure.

§Example

use virtualbox_rs::VirtualBox;

let vbox = VirtualBox::init_unchecked().unwrap();

§Details

This method skips the version check and directly initializes the virtualbox. Use this method only if you have already checked the version and are confident it is correct. If the version is not checked and does not match, the application may crash with a core dump on random method calls. The speed of calling init_unchecked is minimally different from the regular init.