[libvirt] [PATCH 1/8] save: document new public API

[Eric Blake]

On 07/14/2011 08:24 AM, Eric Blake wrote:
> In order to choose whether to use O_DIRECT when saving a domain image
> to a file, we need a new flag.  But virDomainSave was implemented
> before our policy of all new APIs having a flag argument.
> 
> 
>  /**
> + * virDomainSaveFlags:
> + * @domain: a domain object
> + * @to: path for the output file
> + * @dxml: (optional) XML config for adjusting guest xml used on restore
> + * @flags: bitwise-OR of virDomainSaveFlagValues
> + *
> + * This method will suspend a domain and save its memory contents to
> + * a file on disk. After the call, if successful, the domain is not
> + * listed as running anymore (this may be a problem).
> + * Use virDomainRestore() to restore a domain after saving.
> + *
> + * If the hypervisor supports it, @dxml can be used to alter
> + * host-specific portions of the domain XML that will be used when
> + * restoring an image.  For example, it is possible to alter the
> + * backing filename that is associated with a disk device, in order to
> + * prepare for file renaming done as part of backing up the disk
> + * device while the domain is stopped.

Oh, I forgot to mention in my cover letter that this is also still on my
to-do queue, by reusing the work in the virDomainMigrate2 series to
allow compatible changes to the XML (oh, and @dxml is undocumented in
virDomainMigrate2 at the moment).  Likewise, I plan to add a @dxml
argument to virDomainRestoreFlags (some people know in advance what
changes they plan to make to the xml before saving, others won't know
until restore time what changes have to be accommodated), as well as two
new API:

/**
 * virConnectDomainSaveGetXMLDesc:
 * @conn: a connection object
 * @file: a file created by virDomainSave[Flags]
 * @flags: currently unused, pass 0
 *
 * Extract the XML from the saved state file that corresponds to the
 * domain at the time it was saved.
 *
 * Returns the XML, or NULL in case of error.  The caller must free()
 * the returned value.
 */
char *virConnectDomainSaveGetXMLDesc(virConnectPtr conn,
 const char *file, unsigned int flags);

/**
 * virConnectDomainSaveModify:
 * @conn: a connection object
 * @file: a file created by virDomainSave[Flags]
 * @dxml: the new XML description to use
 * @flags: currently unused, pass 0
 *
 * If the hypervisor supports it, @dxml can be used to alter
 * host-specific portions of the domain XML that will be used when
 * restoring an image.  For example, it is possible to alter the
 * backing filename that is associated with a disk device, in order
 * to manage file renames due to snapshots or file backups done
 * after the domain state was saved.
 *
 * Returns 0 on success, -1 on error.
 */
int virConnectDomainSaveModify(virConnectPtr conn,
 const char *file, const char *dxml, unsigned int flags);

-- 
Eric Blake   eblake at redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 619 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20110714/d6fbbe78/attachment-0001.sig>