Libvirt-gobject Reference Manual: GVirDomain

GVirDomain

Functions

const gchar *	gvir_domain_get_name ()
const gchar *	gvir_domain_get_uuid ()
gint	gvir_domain_get_id ()
gboolean	gvir_domain_start ()
void	gvir_domain_start_async ()
gboolean	gvir_domain_start_finish ()
gboolean	gvir_domain_resume ()
void	gvir_domain_resume_async ()
gboolean	gvir_domain_resume_finish ()
gboolean	gvir_domain_wakeup ()
void	gvir_domain_wakeup_async ()
gboolean	gvir_domain_wakeup_finish ()
gboolean	gvir_domain_stop ()
gboolean	gvir_domain_delete ()
gboolean	gvir_domain_shutdown ()
gboolean	gvir_domain_reboot ()
gboolean	gvir_domain_save_to_file ()
void	gvir_domain_save_to_file_async ()
gboolean	gvir_domain_save_to_file_finish ()
GVirDomainInfo *	gvir_domain_get_info ()
void	gvir_domain_get_info_async ()
GVirDomainInfo *	gvir_domain_get_info_finish ()
GVirConfigDomain *	gvir_domain_get_config ()
gboolean	gvir_domain_set_config ()
gchar *	gvir_domain_screenshot ()
gboolean	gvir_domain_open_console ()
gboolean	gvir_domain_open_graphics ()
gboolean	gvir_domain_suspend ()
gboolean	gvir_domain_save ()
void	gvir_domain_save_async ()
gboolean	gvir_domain_save_finish ()
gboolean	gvir_domain_get_persistent ()
gboolean	gvir_domain_get_saved ()
GList *	gvir_domain_get_devices ()
gboolean	gvir_domain_update_device ()
GVirDomainSnapshot *	gvir_domain_create_snapshot ()
void	gvir_domain_create_snapshot_async ()
GVirDomainSnapshot *	gvir_domain_create_snapshot_finish ()
gboolean	gvir_domain_fetch_snapshots ()
GList *	gvir_domain_get_snapshots ()
void	gvir_domain_fetch_snapshots_async ()
gboolean	gvir_domain_fetch_snapshots_finish ()
gboolean	gvir_domain_get_has_current_snapshot ()

Properties

GVirDomainHandle *	handle	Read / Write / Construct Only
gboolean	persistent	Read

Signals

void	pmsuspended	No Hooks
void	resumed	No Hooks
void	started	No Hooks
void	stopped	No Hooks
void	suspended	No Hooks
void	updated	No Hooks

Types and Values

enum	GVirDomainState
enum	GVirDomainStartFlags
enum	GVirDomainDeleteFlags
enum	GVirDomainXMLFlags
enum	GVirDomainShutdownFlags
enum	GVirDomainSnapshotCreateFlags
enum	GVirDomainUpdateDeviceFlags
enum	GVirDomainRebootFlags
enum	GVirDomainSnapshotListFlags

Object Hierarchy

    GBoxed
    ╰── GVirDomainInfo
    GObject
    ╰── GVirDomain

Description

Functions

gvir_domain_get_name ()

const gchar *
gvir_domain_get_name (GVirDomain *dom);

gvir_domain_get_uuid ()

const gchar *
gvir_domain_get_uuid (GVirDomain *dom);

gvir_domain_get_id ()

gint
gvir_domain_get_id (GVirDomain *dom,
                    GError **err);

gvir_domain_start ()

gboolean
gvir_domain_start (GVirDomain *dom,
                   guint flags,
                   GError **err);

Parameters

dom	the domain
flags	the flags

gvir_domain_start_async ()

void
gvir_domain_start_async (GVirDomain *dom,
                         guint flags,
                         GCancellable *cancellable,
                         GAsyncReadyCallback callback,
                         gpointer user_data);

Asynchronous variant of gvir_domain_start.

Parameters

dom	the domain
flags	the flags
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_start_finish ()

gboolean
gvir_domain_start_finish (GVirDomain *dom,
                          GAsyncResult *result,
                          GError **err);

gvir_domain_resume ()

gboolean
gvir_domain_resume (GVirDomain *dom,
                    GError **err);

Parameters

dom	the domain
err	Place-holder for possible errors

Returns

TRUE on success

gvir_domain_resume_async ()

void
gvir_domain_resume_async (GVirDomain *dom,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronous variant of gvir_domain_resume.

Parameters

dom	the domain to resume
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_resume_finish ()

gboolean
gvir_domain_resume_finish (GVirDomain *dom,
                           GAsyncResult *result,
                           GError **err);

gvir_domain_wakeup ()

gboolean
gvir_domain_wakeup (GVirDomain *dom,
                    guint flags,
                    GError **err);

Parameters

dom	the domain
flags	placeholder for flags, pass 0
err	Place-holder for possible errors

Returns

TRUE on success

gvir_domain_wakeup_async ()

void
gvir_domain_wakeup_async (GVirDomain *dom,
                          guint flags,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Asynchronous variant of gvir_domain_wakeup.

Parameters

dom	the domain to wakeup
flags	placeholder for flags, pass 0
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_wakeup_finish ()

gboolean
gvir_domain_wakeup_finish (GVirDomain *dom,
                           GAsyncResult *result,
                           GError **err);

gvir_domain_stop ()

gboolean
gvir_domain_stop (GVirDomain *dom,
                  guint flags,
                  GError **err);

Parameters

dom	the domain
flags	the flags

gvir_domain_delete ()

gboolean
gvir_domain_delete (GVirDomain *dom,
                    guint flags,
                    GError **err);

Parameters

dom	the domain
flags	the flags

gvir_domain_shutdown ()

gboolean
gvir_domain_shutdown (GVirDomain *dom,
                      guint flags,
                      GError **err);

Parameters

dom	the domain
flags	the `GVirDomainShutdownFlags` flags

gvir_domain_reboot ()

gboolean
gvir_domain_reboot (GVirDomain *dom,
                    guint flags,
                    GError **err);

Parameters

dom	the domain
flags	the `GVirDomainRebootFlags` flags

gvir_domain_save_to_file ()

gboolean
gvir_domain_save_to_file (GVirDomain *dom,
                          gchar *filename,
                          GVirConfigDomain *custom_conf,
                          guint flags,
                          GError **err);

Parameters

dom	the domain
filename	path to the output file
custom_conf	configuration for domain or NULL.	[allow-none]
flags	the flags

Returns

TRUE on success, FALSE otherwise

gvir_domain_save_to_file_async ()

void
gvir_domain_save_to_file_async (GVirDomain *dom,
                                gchar *filename,
                                GVirConfigDomain *custom_conf,
                                guint flags,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Asynchronous variant of gvir_domain_save_to_file

Parameters

dom	the domain
filename	path to output file
custom_conf	configuration for domain or NULL.	[allow-none]
flags	the flags
cancellable	cancallation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_save_to_file_finish ()

gboolean
gvir_domain_save_to_file_finish (GVirDomain *dom,
                                 GAsyncResult *result,
                                 GError **err);

Finishes the operation started by gvir_domain_save_to_file_async.

Parameters

dom	the domain to save
result	async method result.	[transfer none]
err	Place-holder for possible errors

Returns

TRUE if domain was saved successfully, FALSE otherwise.

gvir_domain_get_info ()

GVirDomainInfo *
gvir_domain_get_info (GVirDomain *dom,
                      GError **err);

Parameters

dom

the domain

Returns

the info. The returned structure should be freed using g_boxed_free() with GVIR_TYPE_DOMAIN_INFO as the first argument when no longer needed.

[transfer full]

gvir_domain_get_info_async ()

void
gvir_domain_get_info_async (GVirDomain *dom,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Asynchronous variant of gvir_domain_get_info.

Parameters

dom	the domain
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_get_info_finish ()

GVirDomainInfo *
gvir_domain_get_info_finish (GVirDomain *dom,
                             GAsyncResult *result,
                             GError **err);

Finishes the operation started by gvir_domain_get_info_async.

Parameters

dom	the domain
result	async method result.	[transfer none]
err	Place-holder for possible errors

Returns

the info. The returned object should be unreffed with g_object_unref() when no longer needed.

[transfer full]

gvir_domain_get_config ()

GVirConfigDomain *
gvir_domain_get_config (GVirDomain *dom,
                        guint flags,
                        GError **err);

Parameters

dom	the domain
flags	the `GVirDomainXMLFlags` flags

Returns

the config. The returned object should be unreffed with g_object_unref() when no longer needed.

[transfer full]

gvir_domain_set_config ()

gboolean
gvir_domain_set_config (GVirDomain *domain,
                        GVirConfigDomain *conf,
                        GError **err);

Resets configuration of an existing domain.

Note: If domain is already running, the new configuration will not take affect until domain reboots.

Parameters

domain	the domain
conf	the new configuration for the domain
err	Place-holder for error or NULL.	[allow-none]

Returns

TRUE on success, FALSE if an error occurred.

gvir_domain_screenshot ()

gchar *
gvir_domain_screenshot (GVirDomain *dom,
                        GVirStream *stream,
                        guint monitor_id,
                        guint flags,
                        GError **err);

Parameters

stream	stream to use as output
monitor_id	monitor ID to take screenshot from
flags	extra flags, currently unused

Returns

a newly allocated string containing the mime-type of the image format, or NULL upon error.

[transfer full]

gvir_domain_open_console ()

gboolean
gvir_domain_open_console (GVirDomain *dom,
                          GVirStream *stream,
                          const gchar *devname,
                          guint flags,
                          GError **err);

Open a text console for the domain dom , connecting it to the stream stream . If devname is NULL, the default console will be opened, otherwise devname can be used to specify a non-default console device.

Parameters

dom	the domain.	[transfer none]
devname	the device name.	[transfer none][allow-none]
stream	stream to use as output.	[transfer none]
flags	extra flags, currently unused

Returns

TRUE if the console was opened, FALSE otherwise.

gvir_domain_open_graphics ()

gboolean
gvir_domain_open_graphics (GVirDomain *dom,
                           guint idx,
                           int fd,
                           unsigned int flags,
                           GError **err);

Open a connection to the local graphics display, connecting it to the socket pair file descriptor passed in as fd .

Parameters

dom	the domain
idx	the graphics index
fd	pre-opened socket pair
flags	extra flags, currently unused

Returns

TRUE if the graphics connection was opened, FALSE otherwise.

gvir_domain_suspend ()

gboolean
gvir_domain_suspend (GVirDomain *dom,
                     GError **err);

Suspends an active domain, the process is frozen without further access to CPU resources and I/O but the memory used by the domain at the hypervisor level will stay allocated. Use gvir_domain_resume() to reactivate the domain.

Parameters

dom	the domain to suspend
err	Place-holder for possible errors

Returns

TRUE if domain was suspended successfully, FALSE otherwise.

gvir_domain_save ()

gboolean
gvir_domain_save (GVirDomain *dom,
                  unsigned int flags,
                  GError **err);

Saves the state of the domain on disk and stops it. Use gvir_domain_start to restore the saved state of the domain. A saved domain can be restored even after shutdown/reboot of host machine.

Parameters

dom	the domain to save
flags	extra flags, currently unused
err	Place-holder for possible errors

Returns

TRUE if domain was saved successfully, FALSE otherwise.

gvir_domain_save_async ()

void
gvir_domain_save_async (GVirDomain *dom,
                        unsigned int flags,
                        GCancellable *cancellable,
                        GAsyncReadyCallback callback,
                        gpointer user_data);

Asynchronous variant of gvir_domain_save.

Parameters

dom	the domain to save
flags	extra flags, currently unused
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_save_finish ()

gboolean
gvir_domain_save_finish (GVirDomain *dom,
                         GAsyncResult *result,
                         GError **err);

Finishes the operation started by gvir_domain_save_async.

Parameters

dom	the domain to save
result	async method result.	[transfer none]
err	Place-holder for possible errors

Returns

TRUE if domain was saved successfully, FALSE otherwise.

gvir_domain_get_persistent ()

gboolean
gvir_domain_get_persistent (GVirDomain *dom);

Parameters

dom

the domain

Returns

TRUE if domain is persistent, FALSE otherwise.

gvir_domain_get_saved ()

gboolean
gvir_domain_get_saved (GVirDomain *dom);

Parameters

dom

the domain

Returns

TRUE if a stopped domain has a saved state to which it can be restored to using gvir_domain_start, FALSE otherwise.

gvir_domain_get_devices ()

GList *
gvir_domain_get_devices (GVirDomain *domain,
                         GError **err);

Gets the list of devices attached to domain . The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

Parameters

domain	the domain
err	place-holder for possible errors, or NULL

Returns

a newly allocated GList of GVirDomainDevice.

[element-type LibvirtGObject.DomainDevice][transfer full]

gvir_domain_update_device ()

gboolean
gvir_domain_update_device (GVirDomain *dom,
                           GVirConfigDomainDevice *device,
                           guint flags,
                           GError **err);

Update the configuration of a device.

Parameters

dom	the domain
device	A modified device config
flags	bitwise-OR of GVirDomainUpdateDeviceFlags
err	Place-holder for error or NULL.	[allow-none]

Returns

TRUE if device was updated successfully, FALSE otherwise.

gvir_domain_create_snapshot ()

GVirDomainSnapshot *
gvir_domain_create_snapshot (GVirDomain *dom,
                             GVirConfigDomainSnapshot *custom_conf,
                             guint flags,
                             GError **err);

Parameters

dom	the domain
custom_conf	configuration of snapshot or NULL.	[allow-none]
flags	bitwise-OR of GVirDomainSnapshotCreateFlags
err	Place-holder for error or NULL.	[allow-none]

Returns

snapshot of domain. The returned object should be unreffed when no longer needed.

[transfer full]

gvir_domain_create_snapshot_async ()

void
gvir_domain_create_snapshot_async (GVirDomain *dom,
                                   GVirConfigDomainSnapshot *custom_conf,
                                   guint flags,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Parameters

dom	The GVirDomain
custom_conf	Configuration of snapshot or `NULL`.	[allow-none]
flags	Bitwise-OR of GVirDomainSnapshotCreateFlags
cancellable	cancellation object.	[allow-none][transfer none]
callback	Completion callback.	[scope async]
user_data	Opaque data for callback.	[closure]

gvir_domain_create_snapshot_finish ()

GVirDomainSnapshot *
gvir_domain_create_snapshot_finish (GVirDomain *domain,
                                    GAsyncResult *result,
                                    GError **error);

Parameters

domain	A GVirDomain
result	Async method result.	[transfer none]
error	Error placeholder.	[allow-none]

Returns

The created snapshot.

[transfer full]

gvir_domain_fetch_snapshots ()

gboolean
gvir_domain_fetch_snapshots (GVirDomain *dom,
                             guint list_flags,
                             GCancellable *cancellable,
                             GError **error);

Parameters

dom	The domain
list_flags	bitwise-OR of GVirDomainSnapshotListFlags
cancellable	cancellation object.	[allow-none][transfer none]
error	Place-holder for error or `NULL`.	[allow-none]

Returns

TRUE on success, FALSE otherwise.

gvir_domain_get_snapshots ()

GList *
gvir_domain_get_snapshots (GVirDomain *dom);

Parameters

dom

The domain Returns: (element-type LibvirtGObject.DomainSnapshot) (transfer full): A list of all the snapshots available for the given domain. The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

gvir_domain_fetch_snapshots_async ()

void
gvir_domain_fetch_snapshots_async (GVirDomain *dom,
                                   guint list_flags,
                                   GCancellable *cancellable,
                                   GAsyncReadyCallback callback,
                                   gpointer user_data);

Parameters

dom	The domain
list_flags	bitwise-OR of GVirDomainSnapshotListFlags
cancellable	cancellation object.	[allow-none][transfer none]
callback	completion callback.	[scope async]
user_data	opaque data for callback.	[closure]

gvir_domain_fetch_snapshots_finish ()

gboolean
gvir_domain_fetch_snapshots_finish (GVirDomain *dom,
                                    GAsyncResult *res,
                                    GError **error);

Parameters

dom	a GVirDomain
res	async method result.	[transfer none]

Returns

TRUE on success, FALSE otherwise.

gvir_domain_get_has_current_snapshot ()

gboolean
gvir_domain_get_has_current_snapshot (GVirDomain *dom,
                                      guint flags,
                                      gboolean *has_current_snapshot,
                                      GError **error);

Parameters

dom	a GVirDomain
flags	Unused, pass 0
has_current_snapshot	Will be set to `TRUE` if the given domain has a current snapshot and to `FALSE` otherwise.	[out]
error	Place-holder for error or `NULL`.	[allow-none]

Returns

TRUE on success, FALSE otherwise.

Types and Values

enum GVirDomainState

Members

GVIR_DOMAIN_STATE_NONE
GVIR_DOMAIN_STATE_RUNNING
GVIR_DOMAIN_STATE_BLOCKED
GVIR_DOMAIN_STATE_PAUSED
GVIR_DOMAIN_STATE_SHUTDOWN
GVIR_DOMAIN_STATE_SHUTOFF
GVIR_DOMAIN_STATE_CRASHED
GVIR_DOMAIN_STATE_PMSUSPENDED

enum GVirDomainStartFlags

Members

GVIR_DOMAIN_START_NONE
GVIR_DOMAIN_START_PAUSED
GVIR_DOMAIN_START_AUTODESTROY
GVIR_DOMAIN_START_BYPASS_CACHE
GVIR_DOMAIN_START_FORCE_BOOT

enum GVirDomainDeleteFlags

Members

GVIR_DOMAIN_DELETE_NONE	No flags
GVIR_DOMAIN_DELETE_SAVED_STATE	Also remove associated saved state (if present).
GVIR_DOMAIN_DELETE_SNAPSHOTS_METADATA	If last use of domain, then also remove any snapshot metadata.

enum GVirDomainXMLFlags

Members

GVIR_DOMAIN_XML_NONE	No flags
GVIR_DOMAIN_XML_SECURE	Dump security sensitive information too
GVIR_DOMAIN_XML_INACTIVE	Dump inactive domain information
GVIR_DOMAIN_XML_UPDATE_CPU	Update guest CPU requirements according to host CPU

enum GVirDomainShutdownFlags

Members

GVIR_DOMAIN_SHUTDOWN_NONE	No flags, hypervisor choice
GVIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN	Send ACPI event
GVIR_DOMAIN_SHUTDOWN_GUEST_AGENT	Use guest agent

enum GVirDomainSnapshotCreateFlags

Members

GVIR_DOMAIN_SNAPSHOT_NONE	No flags
GVIR_DOMAIN_SNAPSHOT_REDEFINE	Restore or alter metadata
GVIR_DOMAIN_SNAPSHOT_CURRENT	With redefine, make snapshot current
GVIR_DOMAIN_SNAPSHOT_NO_METADATA	Make snapshot without remembering it
GVIR_DOMAIN_SNAPSHOT_HALT	Stop running guest after snapshot
GVIR_DOMAIN_SNAPSHOT_DISK_ONLY	Disk snapshot, not system checkpoint
GVIR_DOMAIN_SNAPSHOT_REUSE_EXT	Reuse any existing external files
GVIR_DOMAIN_SNAPSHOT_QUIESCE	Use guest agent to quiesce all mounter file systems within the domain
GVIR_DOMAIN_SNAPSHOT_ATOMIC	Atomically avoid partial changes

enum GVirDomainUpdateDeviceFlags

Members

GVIR_DOMAIN_UPDATE_DEVICE_CURRENT	Update current domain state
GVIR_DOMAIN_UPDATE_DEVICE_LIVE	Update state for only active domains
GVIR_DOMAIN_UPDATE_DEVICE_CONFIG	Update state for persistent state only

enum GVirDomainRebootFlags

Members

GVIR_DOMAIN_REBOOT_NONE	No flags, hypervisor choice
GVIR_DOMAIN_REBOOT_ACPI_POWER_BTN	Send ACPI event
GVIR_DOMAIN_REBOOT_GUEST_AGENT	Use guest agent

enum GVirDomainSnapshotListFlags

Members

GVIR_DOMAIN_SNAPSHOT_LIST_ALL	List all snapshots
GVIR_DOMAIN_SNAPSHOT_LIST_DESCENDANTS	List all descendants, not just children, when listing a snapshot. For historical reasons, groups do not use contiguous bits.
GVIR_DOMAIN_SNAPSHOT_LIST_ROOTS	Filter by snapshots with no parents, when listing a domain
GVIR_DOMAIN_SNAPSHOT_LIST_METADATA	Filter by snapshots which have metadata
GVIR_DOMAIN_SNAPSHOT_LIST_LEAVES	Filter by snapshots with no children
GVIR_DOMAIN_SNAPSHOT_LIST_NO_LEAVES	Filter by snapshots that have children
GVIR_DOMAIN_SNAPSHOT_LIST_NO_METADATA	Filter by snapshots with no metadata
GVIR_DOMAIN_SNAPSHOT_LIST_INACTIVE	Filter by snapshots taken while guest was shut off
GVIR_DOMAIN_SNAPSHOT_LIST_ACTIVE	Filter by snapshots taken while guest was active, and with memory state
GVIR_DOMAIN_SNAPSHOT_LIST_DISK_ONLY	Filter by snapshots taken while guest was active, but without memory state
GVIR_DOMAIN_SNAPSHOT_LIST_INTERNAL	Filter by snapshots stored internal to disk images
GVIR_DOMAIN_SNAPSHOT_LIST_EXTERNAL	Filter by snapshots that use files external to disk images

Property Details

The `“handle”` property

  “handle”                   GVirDomainHandle *

The domain handle.

Flags: Read / Write / Construct Only

The `“persistent”` property

  “persistent”               gboolean

If domain is persistent.

Flags: Read

Default value: TRUE

Signal Details

The `“pmsuspended”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks

The `“resumed”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks

The `“started”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks

The `“stopped”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks

The `“suspended”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks

The `“updated”` signal

void
user_function (GVirDomain *gvirdomain,
               gpointer    user_data)

Flags: No Hooks