[libvirt] [RFC]: Snapshot API v2

[Daniel P. Berrange]

On Wed, Mar 24, 2010 at 09:16:46AM -0400, Chris Lalancette wrote:
> 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);

This is still better as 'Delete'. Deactivate implies that the snapshot has
a boolean state where it can switch between active & inactive, which is
not the case here.

Regards,
Daniel
-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|