[libvirt] [PATCH v2 07/11] domain: Add VIR_DOMAIN_XML_SNAPSHOTS flag

[Eric Blake]

Right now, copying the state of a transient domain with snapshots
from one host to another requires multiple API calls on both
machines - on the host: get the domain XML, get a list of the
snapshots, and then for each snapshot get the snapshot's XML;
then on the destination: create the domain, then multiple
domain snapshot create calls with the REDEFINE flag.  This
patch aims to make the process use fewer APIs by making it
possible to grab the XML for all snapshots at the same time as
grabbing the domain XML.  Note that we had to do the modification
to virDomainGetXMLDesc(), rather than virDomainSnapshotGetXMLDesc(),
since the latter requires a single non-NULL snapshot object,
whereas we want the list of all snapshots for the domain (even
if the list has 0 elements).

Once wired up in drivers in later patches, the new information
is provided as:

<domain ...>
  ...
  </devices>
  <snapshots current='name'>
    <domainsnapshot>
      ...
    </domainsnapshot>
    <domainsnapshot>
      ...
    </domainsnapshot>
  </snapshots>
</domain>

For now, I did not modify the schema to permit this information
during virDomainDefineXML; it is still necessary to use
virDomainSnapshotCreateXML with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE
multiple times to recreate the added state output here.

Unfortunately, libvirt versions between 1.2.12 and 5.0.0 will
silently ignore the new flag, rather than diagnosing that they
don't support it; but at least silent lack of snapshots from
an older server is not a security hole.

Signed-off-by: Eric Blake <eblake at redhat.com>
---
 include/libvirt/libvirt-domain.h |  1 +
 src/conf/domain_conf.c           | 13 ++++++++-----
 src/libvirt-domain.c             |  5 +++++
 3 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 1d5bdb545d..a8ebb68388 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1570,6 +1570,7 @@ typedef enum {
     VIR_DOMAIN_XML_INACTIVE     = (1 << 1), /* dump inactive domain information */
     VIR_DOMAIN_XML_UPDATE_CPU   = (1 << 2), /* update guest CPU requirements according to host CPU */
     VIR_DOMAIN_XML_MIGRATABLE   = (1 << 3), /* dump XML suitable for migration */
+    VIR_DOMAIN_XML_SNAPSHOTS    = (1 << 4), /* include all snapshots in the dump */
 } virDomainXMLFlags;

 typedef enum {
diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c
index 46ae79e738..90e2dbe465 100644
--- a/src/conf/domain_conf.c
+++ b/src/conf/domain_conf.c
@@ -29057,11 +29057,12 @@ virDomainDefFormatInternal(virDomainDefPtr def,
     return -1;
 }

-/* Converts VIR_DOMAIN_XML_COMMON_FLAGS into VIR_DOMAIN_DEF_FORMAT_*
- * flags, and silently ignores any other flags.  Note that the caller
- * should validate the set of flags it is willing to accept; see also
- * the comment on VIR_DOMAIN_XML_COMMON_FLAGS about security
- * considerations with adding new flags. */
+/* Converts VIR_DOMAIN_XML_COMMON_FLAGS and VIR_DOMAIN_XML_SNAPSHOTS
+ * into VIR_DOMAIN_DEF_FORMAT_* flags, and silently ignores any other
+ * flags.  Note that the caller should validate the set of flags it is
+ * willing to accept; see also the comment on
+ * VIR_DOMAIN_XML_COMMON_FLAGS about security considerations with
+ * adding new flags. */
 unsigned int virDomainDefFormatConvertXMLFlags(unsigned int flags)
 {
     unsigned int formatFlags = 0;
@@ -29072,6 +29073,8 @@ unsigned int virDomainDefFormatConvertXMLFlags(unsigned int flags)
         formatFlags |= VIR_DOMAIN_DEF_FORMAT_INACTIVE;
     if (flags & VIR_DOMAIN_XML_MIGRATABLE)
         formatFlags |= VIR_DOMAIN_DEF_FORMAT_MIGRATABLE;
+    if (flags & VIR_DOMAIN_XML_SNAPSHOTS)
+        formatFlags |= VIR_DOMAIN_DEF_FORMAT_SNAPSHOTS;

     return formatFlags;
 }
diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c
index 072b92b717..2691698bd5 100644
--- a/src/libvirt-domain.c
+++ b/src/libvirt-domain.c
@@ -2570,6 +2570,11 @@ virDomainGetControlInfo(virDomainPtr domain,
  * XML might not validate against the schema, so it is mainly for
  * internal use.
  *
+ * If @flags contains VIR_DOMAIN_XML_SNAPSHOTS, the XML will include
+ * an additional <snapshots> child element describing all snapshots
+ * belonging to the domain, including an attribute current='name' if
+ * one of those snapshots is current.
+ *
  * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
  *         the caller must free() the returned value.
  */
-- 
2.20.1