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@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/