A guest domain can refer to either a running virtual machine or a configuration which can be used to launch a virtual machine. The connection object provides APIs to enumerate the guest domains, create new guest domains and manage existing domains. A guest domain is represented with the virDomainPtr object and has a number of unique identifiers:
Unique identifiers
ID: positive integer, unique amongst running guest domains on a single host. An inactive domain does not have an ID. If the host OS is a virtual domain, it is given a ID of zero by default. For example, with the Xen hypervisor, Dom0 indicates a guest domain. Other domain IDs will be allocated starting at 1, and incrementing each time a new domain starts. Typically domain IDs will not be re-used until the entire ID space wraps around. The domain ID space is at least 16 bits in size, but often extends to 32 bits.
name: short string, unique amongst all guest domains on a single host, both running and inactive. For maximum portability between hypervisors applications should only rely on being able to use the characters a-Z,0-9,-,_ in names. Many hypervisors will store inactive domain configurations as files on disk, based on the domain name.
UUID: 16 unsigned bytes, guaranteed to be unique amongst all guest domains on any host. RFC 4122 defines the format for UUIDs and provides a recommended algorithm for generating UUIDs with guaranteed uniqueness. If the host OS is itself a virtual domain, then by convention it will be given a UUID of all zeros. This is the case with the Xen hypervisor, where Dom0 is a guest domain itself.
A guest domain may be transient, or persistent. A transient guest domain can only be managed while it is running on the host and, when powered off, all trace of it will disappear. A persistent guest domain has its configuration maintained in a data store on the host by the hypervisor, in an implementation defined format. Thus when a persistent guest is powered off, it is still possible to manage its inactive config. A transient guest can be turned into a persistent guest on the fly by defining a configuration for it.
Once an application has a unique identifier for a domain, it will often want to obtain the corresponding virDomainPtr object. There are three, imaginatively named, methods to do lookup existing domains, virDomainLookupByID, virDomainLookupByName and virDomainLookupByUUID. Each of these takes a connection object as first parameter, and the domain identifier as the other. They will return NULL if no matching domain exists. The connection's error object can be queried to find specific details of the error if required.
int domainID = 6;
virDomainPtr dom;
dom = virDomainLookupByID(conn, domainID);
Example 4.1. Fetching a domain object from an ID
int domainName = "someguest";
virDomainPtr dom;
dom = virDomainLookupByName(conn, domainName);
Example 4.2. Fetching a domain object from an name
char *domainUUID = "00311636-7767-71d2-e94a-26e7b8bad250";
virDomainPtr dom;
dom = virDomainLookupByUUIDString(conn, domainUUID);
Example 4.3. Fetching a domain object from an UUID
For convenience of this document, the UUID example used the printable format of UUID. There is an equivalent method which accepts the raw bytes unsigned char[]
