[libvirt] [PATCH][RFC] adding a title to the domain description informations

[Daniel Veillard]

 The idea is that currently we have only the domain name usable as
a description for the domain. It is not really a good human readable
identifier, as the kind of string allowed is limited (no space for
example). The idea would then be to extend the existing <description>
field in the domain XML to keep 40 or less character string to describe
a domain and provide that information later for example in an extended
virsh list command or for other interfaces.
  While the idea is simple, see attached patch for this, it becomes more
complex when one tries to make accessors to set/get that title for a
domain, since it's mutable and possibly could be coming from the
hypervisor itself (is there anything like this in VMWare or VirtualBox?)
it should to be implemented down at the driver level. Is that worth the
effort ? If we go that route should we do this for other objects
(network, storage, etc ...) too in the end ?

here is a basic patch for just the XML side to give an idea, but
adding APIs is far more work.

  Opinions ?

Daniel
 
    Provide a title attribute on domain descriptions

    Allow to provide a title attribute to domain descriptions
    useful when presenting the domain in an user interface.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index de9b480..ad5ffb0 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -58,7 +58,13 @@
       <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>. It is also possible
+      to provide an human readable title for the virtual machine, by
+      providing it as a <code>title<code> attribute on the
+      <code>description</code> element, this can be useful to provide an
+      human description when listing virtual machines (<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 2041dfb..78ba67c 100644
--- a/docs/schemas/domaincommon.rng
+++ b/docs/schemas/domaincommon.rng
@@ -10,6 +10,11 @@
     -->
   <define name="description">
     <element name="description">
+      <optional>
+        <attribute name="title">
+          <ref name="title-value"/>
+        </attribute>
+      </optional>
       <text/>
     </element>
   </define>
@@ -3115,4 +3120,9 @@
     </element>
     <empty/>
   </define>
+  <define name="title-value">
+    <data type="string">
+      <param name="pattern">.{0,40}</param>
+    </data>
+  </define>
 </grammar>
diff --git a/src/conf/domain_conf.c b/src/conf/domain_conf.c
index f97014e..0e1ff44 100644
--- a/src/conf/domain_conf.c
+++ b/src/conf/domain_conf.c
@@ -1478,6 +1478,7 @@ void virDomainDefFree(virDomainDefPtr def)
     VIR_FREE(def->cpumask);
     VIR_FREE(def->emulator);
     VIR_FREE(def->description);
+    VIR_FREE(def->title);
 
     virBlkioDeviceWeightArrayClear(def->blkio.devices,
                                    def->blkio.ndevices);
@@ -7092,6 +7093,7 @@ static virDomainDefPtr virDomainDefParseXML(virCapsPtr caps,
 
     /* Extract documentation if present */
     def->description = virXPathString("string(./description[1])", ctxt);
+    def->title = virXPathString("string(./description[1]/@title)", ctxt);
 
     /* analysis of security label, done early even though we format it
      * late, so devices can refer to this for defaults */
@@ -11417,8 +11419,16 @@ virDomainDefFormatInternal(virDomainDefPtr def,
     virUUIDFormat(uuid, uuidstr);
     virBufferAsprintf(buf, "  <uuid>%s</uuid>\n", uuidstr);
 
-    virBufferEscapeString(buf, "  <description>%s</description>\n",
-                          def->description);
+    if (def->title || def->description) {
+        virBufferAddLit(buf, "  <description");
+        if (def->title)
+            virBufferEscapeString(buf, " title='%s'", def->title);
+        if (def->description)
+            virBufferEscapeString(buf, ">%s</description>\n",
+                                  def->description);
+        else
+            virBufferAddLit(buf, "/>");
+    }
 
     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 b121f9c..45d70e6 100644
--- a/src/conf/domain_conf.h
+++ b/src/conf/domain_conf.h
@@ -1421,6 +1421,7 @@ struct _virDomainDef {
     unsigned char uuid[VIR_UUID_BUFLEN];
     char *name;
     char *description;
+    char *title;
 
     struct {
         unsigned int weight;

-- 
Daniel Veillard      | libxml Gnome XML XSLT toolkit  http://xmlsoft.org/
daniel at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/