[libvirt] [RFC]: Snapshot API v2

[Chris Lalancette]

Based on discussion, I've modified the snapshot API to the below.  I've
incorporated most of the semantic changes we talked about; the renaming
of various API calls I've left for later, since it is a minor point.
More comments welcome!

/* NOTE: struct _virDomainSnapshot is a private structure, ala
 * struct _virDomain.
 */
typedef struct _virDomainSnapshot virDomainSnapshot;

/* Take a snapshot of the current VM state.  Throws an error if
 * the VM is not currently running */
virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain,
                                                const char *xmlDesc,
                                                unsigned int flags);

/* Dump the XML of a snapshot */
/* NOTE: see below for proposed XML */
char *virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
                                  unsigned int flags);

/* Return the number of snapshots for this domain */
int virDomainSnapshotNum(virDomainPtr domain, unsigned int flags);

/* Get the names of all snapshots for this domain */
int virDomainListSnapshotNames(virDomainPtr domain, char **names, int nameslen,
                               unsigned int flags);

/* Get a handle to a named snapshot */
virDomainSnapshotPtr virDomainSnapshotLookupByName(virDomainPtr domain,
                                                   const char *name,
                                                   unsigned int flags);

/* Start the guest "domain" from the snapshot "snapshot" */
int virDomainCreateWithSnapshot(virDomainPtr domain,
                                virDomainSnapshotPtr snapshot,
                                unsigned int flags);

/* Deactivate a snapshot - with no flags, the snapshot is not used anymore,
 * but also not removed.  With a MERGE flag, it merges the snapshot into
 * the parent snapshot (or the base image, if there is no parent snapshot).
 * Note that if other snapshots would be discarded because of this
 * MERGE action, this operation will fail.  If that is really what is intended,
 * use MERGE_FORCE.
 *
 * With a DISCARD flag, it deletes the snapshot.  Note that if other snapshots
 * would be discarded because of this delete action, this operation will
 * fail.  If this is really what is intended, use DISCARD_FORCE.
 *
 * MERGE, MERGE_FORCE, DISCARD, and DISCARD_FORCE are mutually-exclusive.
 *
 * Note that this operation can generally only happen when the domain is shut
 * down, though this is hypervisor-specific */
typedef enum {
    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE,
    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE_FORCE,
    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD,
    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD_FORCE,
} virDomainSnapshotDeactivate;
int virDomainSnapshotDeactivate(virDomainSnapshotPtr snapshot,
                                unsigned int flags);

int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);

NOTE: During snapshot creation, *none* of the fields are required.  That is,
you can call virDomainSnapshotCreateXML() with an XML of "<domainsnapshot/>".
In this case, the individual driver will make up a <name> for you, the
<creationdate> will be set to the current time+date, <description> will be
empty, <state> will be "off", <compression> will be empty, and <parent> will
be set to the current snapshot (if any).  If you do want to specify some
fields during virDomainSnapshotCreateXML(), note that the only ones that are
settable are <name>, <description>, and <compression>; the rest are ignored,
and filled in by the driver when the snapshot is actually created.
NOTE: <compression> is used to compress snapshots, and may or may not be
supported by individual hypervisor implementations.  If <compression> is
specified and the underlying hypervisor does not support it, an error will
be thrown.

<domainsnapshot>
   <name>XYZ</name>
   <creationdate>...</creationdate>
   <description>...</description>
   <state>RUNNING</state>
   <domain>
      <uuid>XXXXX-XXXX-XXXX-XXXX-XXXXXXXXX</uuid>
   </domain>
   <compression>gzip</compression>
   <parent>
     <name>ABC</name>
   </parent>
</domainsnapshot>

The virsh commands will be:
virsh snapshot-create [--compress] <dom> <xmlfile>
virsh snapshot-list <dom>
virsh snapshot-dumpxml <dom> <name>
virsh create-with-snapshot <dom> <snapshotname>
virsh snapshot-deactivate <dom> <snapshotname> [--merge|--delete|--mergeforce|--mergedelete]


-- 
Chris Lalancette