[libvirt] [PATCH v2 0/8] Add ability to store notes with domains

[Daniel P. Berrange]

On Mon, Jan 23, 2012 at 09:17:51AM -0700, Eric Blake wrote:
> On 01/23/2012 08:50 AM, Peter Krempa wrote:
> > On 01/18/2012 03:23 PM, Peter Krempa wrote:
> >> I've reworked this patches to use a separate element for storing the
> >> short note. This v2 also contains som new patches, especially added
> >> support for the LXC driver, and optionaly API to get the description.
> >> (See patches marked as optional). These are not required, just add
> >> a helper api to get the description and it's usage in virsh.
> > 
> > I noticed a discussion [1] about adding metadata to domains definition
> > and methods of accessing it.
> > 
> > As these patches can also be considered to deal with metadata and we
> > probably shouldn't add a ton of API's for accessing them we could as
> > well as add an API to support various formats of metadata.
> > 
> > What are your opinions on this? Should we add such a general function
> > (virDomain[Get|Set]Metadata)? Is it a good idea to use the virTypedParam
> > to do this? Is the string support on virTypedParam complete?
> 
> Changing <title> or <description> of a transient domain is a
> nice-to-have, but not the end of the world.  Changing <metadata> of a
> transient domain is a must-have, so we need at least one new API.
> Setting is important, while getting is only a shortcut (we can make the
> user call virDomainGetXMLDesc, and do an XPath query), but symmetry is
> nice.  Meanwhile, libvirt shouldn't care about the contents of
> <metadata>, other than that it is a well-formed XML string.  We do _not_
> need virTypedParams, but can stick with just an enum for which piece of
> metadata to be modifying.  We can get by with just one API for all three
> elements, as well as leaving the door open for any future metadata.  So

For the <metadata> element we want more tha njust a well-formed XML
string. The intention is that every top level element inside
<metadata> *must* declare its own private XML namespace. The
default namespace is to be reserved for any libvirt official metadata
elements we might introduce in the future.

> I'm starting to think:
> 
> new error type VIR_ERR_NO_DOMAIN_METADATA = 79, /* Metadata element not
> present */
> 
> typedef enum {
>     VIR_DOMAIN_METADATA_DESCRIPTION = 0, /* Operate on <description> */
>     VIR_DOMAIN_METADATA_TITLE       = 1, /* Operate on <title> */
>     VIR_DOMAIN_METADATA_ELEMENT     = 2, /* Operate on <metadata> */
> 
> #ifdef VIR_ENUM_SENTINELS
>     VIR_DOMAIN_METADATA_LAST
> #endif
> } virDomainMetadataType;
> 
> 
> /**
>  * virDomainSetMetadata:
>  * @domain: a domain object
>  * @type: type of description, from virDomainMetadataType
>  * @description: new description text
>  * @flags: bitwise-OR of virDomainModificationImpact
>  *
>  * Sets the appropriate domain element given by @type to the
>  * value of @description.  A @type of VIR_DOMAIN_METADATA_DESCRIPTION
>  * is free-form text; VIR_DOMAIN_METADATA_TITLE is free-form but
>  * length-limited to 40 bytes, and VIR_DOMAIN_METADATA_ELEMENT must
>  * be well-formed XML but is otherwise uninterpreted by libvirt.
>  * Passing NULL for @description says to remove that element from the
>  * domain XML (passing the empty string leaves the element present).
>  *
>  * The resulting metadata will be present in virDomainGetXMLDesc(),
>  * as well as quick access through virDomainGetMetadata().
>  *
>  * @flags controls whether the live domain, persistent configuration,
>  * or both will be modified.
>  *
>  * Returns 0 on success, -1 in case of failure.
>  */
> int
> virDomainSetMetadata(virDomainPtr domain,
>                      int type,
>                      const char *description,
>                      unsigned int flags);
> 
> /**
>  * virDomainGetMetadata:
>  * @domain: a domain object
>  * @type: type of description, from virDomainMetadataType
>  * @flags: bitwise-OR of virDomainModificationImpact
>  *
>  * Retrieves the appropriate domain element given by @type.
>  * If an element of the domain XML is not present, the resulting
>  * error will be VIR_ERR_NO_DOMAIN_METADATA.  This method forms
>  * a shortcut for seeing information from virDomainSetMetadata()
>  * without having to go through virDomainGetXMLDesc().
>  *
>  * @flags controls whether the live domain or persistent
>  * configuration will be queried.
>  *
>  * Returns the metadata string on success (caller must free),
>  * or NULL in case of failure.
>  */
> char *
> virDomainGetMetadata(virDomainPtr domain,
>                      int type,
>                      unsigned int flags);

While fine for title/description, I don't think this really works
for <metadata>.  When setting the metadata we'd want to specify
an XML namespace key and URI, and when getting the metadata we'd
really want to specify a namespace URI


Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|