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

[Eric Blake]

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
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);


-- 
Eric Blake   eblake at redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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