[libvirt] [PATCH 1/4] xml: Add attribute to <description> element to hold a short note

[Peter Krempa]

This patch adds an optional attribute note=""  to the <description>
element in the domain XML. This attribute can hold a short note defined
by the user to ease the identification of domains. The note is limited
to 40 characters.

 *docs/formatdomain.html.in
 *docs/schemas/domaincommon.rng
        - add schema grammar for the new element and documentation

  *src/conf/domain_conf.c
  *src/conf/domain_conf.h
        - add field to hold the new attribute
        - add code to parse and create XML with the new attribute
---
 docs/formatdomain.html.in     |    7 +++++--
 docs/schemas/domaincommon.rng |   14 +++++++++++++-
 src/conf/domain_conf.c        |   27 +++++++++++++++++++++++++--
 src/conf/domain_conf.h        |    1 +
 4 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 4b31e2a..0315734 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -32,7 +32,8 @@
 <domain type='xen' id='3'>
   <name>fv0</name>
   <uuid>4dea22b31d52d8f32516782e98ab3fa0</uuid>
-  <description>Some human readable description</description>
+  <description note='Some short description'>
+     Some human readable (optional) long description</description>
   ...</pre>

     <dl>
@@ -58,7 +59,9 @@
       <dd>The content of the <code>description</code> element provides a
       human readable description of the virtual machine. This data is not
       used by libvirt in any way, it can contain any information the user
-      wants. <span class="since">Since 0.7.2</span></dd>
+      wants. <span class="since">Since 0.7.2</span> The optional attribute
+      <code>note</code> provides space for a shorter description.
+      <span class="since">Since 0.9.10</span></dd>
     </dl>

     <h3><a name="elementsOS">Operating system booting</a></h3>
diff --git a/docs/schemas/domaincommon.rng b/docs/schemas/domaincommon.rng
index fdcbc28..0cf5caf 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -10,7 +10,19 @@
     -->
   <define name="description">
     <element name="description">
-      <text/>
+      <optional>
+        <attribute name="note">
+          <data type="string"/>
+        </attribute>
+      </optional>
+      <choice>
+        <group>
+          <text/>
+        </group>
+        <group>
+          <empty/>
+        </group>
+      </choice>
     </element>
   </define>

diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c
index d474551..d1e0ab2 100644
--- a/src/conf/domain_conf.c
+++ b/src/conf/domain_conf.c
@@ -1472,6 +1472,7 @@ void virDomainDefFree(virDomainDefPtr def)
     VIR_FREE(def->cpumask);
     VIR_FREE(def->emulator);
     VIR_FREE(def->description);
+    VIR_FREE(def->note);

     virBlkioDeviceWeightArrayClear(def->blkio.devices,
                                    def->blkio.ndevices);
@@ -7103,6 +7104,22 @@ static virDomainDefPtr virDomainDefParseXML(virCapsPtr caps,
         VIR_FREE(tmp);
     }

+    /* Extract short description of domain (note) */
+    def->note = virXPathString("string(./description[1]/@note)", ctxt);
+    if (def->note) {
+        if (strchr(def->note, '\n')) {
+            virDomainReportError(VIR_ERR_XML_ERROR,
+                               "%s", _("Note attribute can't contain newlines"));
+            goto error;
+        }
+
+        if (strlen(def->note) > 40) {
+            virDomainReportError(VIR_ERR_XML_ERROR,
+                                 "%s", _("Note too long"));
+            goto error;
+        }
+    }
+
     /* Extract documentation if present */
     def->description = virXPathString("string(./description[1])", ctxt);

@@ -11422,8 +11439,14 @@ virDomainDefFormatInternal(virDomainDefPtr def,
     virUUIDFormat(uuid, uuidstr);
     virBufferAsprintf(buf, "  <uuid>%s</uuid>\n", uuidstr);

-    virBufferEscapeString(buf, "  <description>%s</description>\n",
-                          def->description);
+    if (def->note || def->description) {
+        virBufferAddLit(buf, "  <description");
+        virBufferEscapeString(buf, " note='%s'", def->note);
+        if (def->description)
+            virBufferEscapeString(buf, ">%s</description>\n", def->description);
+        else
+            virBufferAddLit(buf, "/>\n");
+    }

     virBufferAsprintf(buf, "  <memory>%lu</memory>\n", def->mem.max_balloon);
     virBufferAsprintf(buf, "  <currentMemory>%lu</currentMemory>\n",
diff --git a/src/conf/domain_conf.h b/src/conf/domain_conf.h
index bac5a87..208a011 100644
--- a/src/conf/domain_conf.h
+++ b/src/conf/domain_conf.h
@@ -1409,6 +1409,7 @@ struct _virDomainDef {
     int id;
     unsigned char uuid[VIR_UUID_BUFLEN];
     char *name;
+    char *note;
     char *description;

     struct {
-- 
1.7.3.4