Struct libvirt_rpc::async::DomainOperations

pub struct DomainOperations<'a> { /* fields omitted */ }

Operations on libvirt domains

Methods

impl<'a> DomainOperations<'a>

fn info(&self, dom: &Domain) -> LibvirtFuture<DomainInfo>

fn list(&self, flags: ListAllDomainsFlags) -> LibvirtFuture<Vec<Domain>>

Collect a possibly-filtered list of all domains, and return an allocated array of information for each.

fn lookup_by_uuid(&self, uuid: &Uuid) -> LibvirtFuture<Domain>

Lookup a domain on the given hypervisor based on its UUID.

fn register_lifecycle_event(
    &self,
    dom: Option<&Domain>
) -> LibvirtFuture<EventStream<DomainLifecycleEvent>>

fn register_reboot_event(
    &self,
    dom: Option<&Domain>
) -> LibvirtFuture<EventStream<DomainRebootEvent>>

fn start(&self, dom: Domain, flags: DomainCreateFlags) -> LibvirtFuture<Domain>

Launch a defined domain. If the call succeeds the domain moves from the defined to the running domains pools.

fn destroy(&self, dom: &Domain, flags: DomainDestroyFlags) -> LibvirtFuture<()>

Destroy the domain object. The running instance is shutdown if not down already and all resources used by it are given back to the hypervisor.

fn define(&self, xml: &str) -> LibvirtFuture<Domain>

Defines a domain, but does not start it. This definition is persistent, until explicitly undefined with virDomainUndefine(). A previous definition for this domain would be overridden if it already exists.

fn undefine(&self, dom: Domain) -> LibvirtFuture<()>

Undefine a domain. If the domain is running, it's converted to transient domain, without stopping it. If the domain is inactive, the domain configuration is removed.

fn shutdown(&self, dom: &Domain) -> LibvirtFuture<()>

Shutdown a domain, the domain object is still usable thereafter, but the domain OS is being stopped. Note that the guest OS may ignore the request.

Additionally, the hypervisor may check and support the domain 'on_poweroff' XML setting resulting in a domain that reboots instead of shutting down. For guests that react to a shutdown request, the differences from virDomainDestroy() are that the guests disk storage will be in a stable state rather than having the (virtual) power cord pulled, and this command returns as soon as the shutdown request is issued rather than blocking until the guest is no longer running.

fn reboot(&self, dom: &Domain) -> LibvirtFuture<()>

Reboot a domain, the domain object is still usable thereafter, but the domain OS is being stopped for a restart. Note that the guest OS may ignore the request.

Additionally, the hypervisor may check and support the domain 'on_reboot' XML setting resulting in a domain that shuts down instead of rebooting.

fn reset(&self, dom: &Domain) -> LibvirtFuture<()>

Reset a domain immediately without any guest OS shutdown. Reset emulates the power reset button on a machine, where all hardware sees the RST line set and reinitializes internal state.

Note that there is a risk of data loss caused by reset without any guest OS shutdown.

fn screenshot(
    &self,
    dom: &Domain,
    screen: u32
) -> LibvirtFuture<(Option<String>, LibvirtStream)>

Take a screenshot of current domain console as a stream. The image format is hypervisor specific. Moreover, some hypervisors supports multiple displays per domain. These can be distinguished by @screen argument.

This call sets up a stream; subsequent use of stream API is necessary to transfer actual data, determine how much data is successfully transferred, and detect any errors.

The screen ID is the sequential number of screen. In case of multiple graphics cards, heads are enumerated before devices, e.g. having two graphics cards, both with four heads, screen ID 5 addresses the second head on the second card.

fn attach_device(
    &self,
    dom: &Domain,
    xml: &str,
    flags: DomainModificationImpact
) -> LibvirtFuture<()>

Attach a virtual device to a domain, using the flags parameter to control how the device is attached. VIR_DOMAIN_AFFECT_CURRENT specifies that the device allocation is made based on current domain state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be allocated to the active domain instance only and is not added to the persisted domain configuration.

VIR_DOMAIN_AFFECT_CONFIG specifies that the device shall be allocated to the persisted domain configuration only. Note that the target hypervisor must return an error if unable to satisfy flags. E.g. the hypervisor driver will return failure if LIVE is specified but it only supports modifying the persisted device allocation. For compatibility, this method can also be used to change the media in an existing CDROM/Floppy device, however, applications are recommended to use the virDomainUpdateDeviceFlag method instead.

Be aware that hotplug changes might not persist across a domain going into S4 state (also known as hibernation) unless you also modify the persistent domain definition.

fn detach_device(
    &self,
    dom: &Domain,
    xml: &str,
    flags: DomainModificationImpact
) -> LibvirtFuture<()>

Detach a virtual device from a domain, using the flags parameter to control how the device is detached. VIR_DOMAIN_AFFECT_CURRENT specifies that the device allocation is removed based on current domain state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be deallocated from the active domain instance only and is not from the persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG specifies that the device shall be deallocated from the persisted domain configuration only. Note that the target hypervisor must return an error if unable to satisfy flags. E.g. the hypervisor driver will return failure if LIVE is specified but it only supports removing the persisted device allocation. Some hypervisors may prevent this operation if there is a current block copy operation on the device being detached; in that case, use virDomainBlockJobAbort() to stop the block copy first. Beware that depending on the hypervisor and device type, detaching a device from a running domain may be asynchronous. That is, calling virDomainDetachDeviceFlags may just request device removal while the device is actually removed later (in cooperation with a guest OS). Previously, this fact was ignored and the device could have been removed from domain configuration before it was actually removed by the hypervisor causing various failures on subsequent operations. To check whether the device was successfully removed, either recheck domain configuration using virDomainGetXMLDesc() or add a handler for the VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED event. In case the device is already gone when virDomainDetachDeviceFlags returns, the event is delivered before this API call ends. To help existing clients work better in most cases, this API will try to transform an asynchronous device removal that finishes shortly after the request into a synchronous removal. In other words, this API may wait a bit for the removal to complete in case it was not synchronous.

Be aware that hotplug changes might not persist across a domain going into S4 state (also known as hibernation) unless you also modify the persistent domain definition.

The supplied XML description of the device should be as specific as its definition in the domain XML. The set of attributes used to match the device are internal to the drivers. Using a partial definition, or attempting to detach a device that is not present in the domain XML, but shares some specific attributes with one that is present, may lead to unexpected results.

fn update_device(
    &self,
    dom: &Domain,
    xml: &str,
    flags: DomainModificationImpact
) -> LibvirtFuture<()>

Change a virtual device on a domain, using the flags parameter to control how the device is changed. VIR_DOMAIN_AFFECT_CURRENT specifies that the device change is made based on current domain state. VIR_DOMAIN_AFFECT_LIVE specifies that the device shall be changed on the active domain instance only and is not added to the persisted domain configuration. VIR_DOMAIN_AFFECT_CONFIG specifies that the device shall be changed on the persisted domain configuration only. Note that the target hypervisor must return an error if unable to satisfy flags. E.g. the hypervisor driver will return failure if LIVE is specified but it only supports modifying the persisted device allocation. This method is used for actions such changing CDROM/Floppy device media, altering the graphics configuration such as password, reconfiguring the NIC device backend connectivity, etc.

fn get_xml(&self, dom: &Domain, flags: DomainXmlFlags) -> LibvirtFuture<String>

Provide an XML description of the domain. The description may be reused later to relaunch the domain with virDomainCreateXML(). No security-sensitive data will be included unless @flags contains VIR_DOMAIN_XML_SECURE; this flag is rejected on read-only connections. If @flags includes VIR_DOMAIN_XML_INACTIVE, then the XML represents the configuration that will be used on the next boot of a persistent domain; otherwise, the configuration represents the currently running domain. If @flags contains VIR_DOMAIN_XML_UPDATE_CPU, then the portion of the domain XML describing CPU capabilities is modified to match actual capabilities of the host.

fn set_autostart(&self, dom: &Domain, enable: bool) -> LibvirtFuture<()>

Configure the domain to be automatically started when the host machine boots.

fn get_autostart(&self, dom: &Domain) -> LibvirtFuture<bool>

Provides a boolean value indicating whether the domain configured to be automatically started when the host machine boots.

fn send_key(
    &self,
    dom: &Domain,
    codeset: u32,
    holdtime: u32,
    keycodes: Vec<u32>
) -> LibvirtFuture<()>

Send key(s) to the guest.