xml: Add element <title> to allow short description of domains

This patch adds a new element <title> to the domain XML. This attribute
can hold a short title defined by the user to ease the identification of
domains. The title may not contain newlines and should be reasonably short.

 *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
This commit is contained in:
Peter Krempa 2012-02-01 14:03:49 +01:00 committed by Eric Blake
parent 26e9fdc0bc
commit b79ba8382e
6 changed files with 65 additions and 2 deletions

View File

@ -32,6 +32,7 @@
&lt;domain type='xen' id='3'&gt;
&lt;name&gt;fv0&lt;/name&gt;
&lt;uuid&gt;4dea22b31d52d8f32516782e98ab3fa0&lt;/uuid&gt;
&lt;title&gt;A short description - title - of the domain&lt;/title&gt;
&lt;description&gt;Some human readable description&lt;/description&gt;
&lt;metadata&gt;
&lt;app1:foo xmlns:app1="http://app1.org/app1/"&gt;..&lt;/app1:foo&gt;
@ -58,6 +59,11 @@
specification. <span class="since">Since 0.0.1, sysinfo
since 0.8.7</span></dd>
<dt><code>title</code></dt>
<dd>The optional element <code>title</code> provides space for a
short description of the domain. The title should not contain
any newlines. <span class="since">Since 0.9.10</span>.</dd>
<dt><code>description</code></dt>
<dd>The content of the <code>description</code> element provides a
human readable description of the virtual machine. This data is not
@ -72,7 +78,7 @@
(if the application needs structure, they should have
sub-elements to their namespace
element). <span class="since">Since 0.9.10</span></dd>
</dl>
</dl>
<h3><a name="elementsOS">Operating system booting</a></h3>

View File

@ -6,7 +6,7 @@
<include href='networkcommon.rng'/>
<!--
description element, may be placed anywhere under the root
description and title element, may be placed anywhere under the root
-->
<define name="description">
<element name="description">
@ -14,6 +14,16 @@
</element>
</define>
<define name="title">
<element name="title">
<data type="string">
<!-- Use literal newline instead of \n for bug in libxml2 2.7.6 -->
<param name="pattern">[^
]+</param>
</data>
</element>
</define>
<!--
We handle only document defining a domain
-->
@ -22,6 +32,9 @@
<ref name="hvs"/>
<ref name="ids"/>
<interleave>
<optional>
<ref name="title"/>
</optional>
<optional>
<ref name="description"/>
</optional>

View File

@ -1481,6 +1481,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);
@ -7158,6 +7159,14 @@ static virDomainDefPtr virDomainDefParseXML(virCapsPtr caps,
VIR_FREE(tmp);
}
/* Extract short description of domain (title) */
def->title = virXPathString("string(./title[1])", ctxt);
if (def->title && strchr(def->title, '\n')) {
virDomainReportError(VIR_ERR_XML_ERROR, "%s",
_("Domain title can't contain newlines"));
goto error;
}
/* Extract documentation if present */
def->description = virXPathString("string(./description[1])", ctxt);
@ -11487,6 +11496,8 @@ virDomainDefFormatInternal(virDomainDefPtr def,
virUUIDFormat(uuid, uuidstr);
virBufferAsprintf(buf, " <uuid>%s</uuid>\n", uuidstr);
virBufferEscapeString(buf, " <title>%s</title>\n", def->title);
virBufferEscapeString(buf, " <description>%s</description>\n",
def->description);

View File

@ -1425,6 +1425,7 @@ struct _virDomainDef {
int id;
unsigned char uuid[VIR_UUID_BUFLEN];
char *name;
char *title;
char *description;
struct {

View File

@ -0,0 +1,27 @@
<domain type='qemu'>
<name>qemu-demo</name>
<uuid>603cc28c-9841-864e-0949-8cc7d3bae9f8</uuid>
<memory>65536</memory>
<currentMemory>65536</currentMemory>
<title>A short description of this domain</title>
<description>
A longer explanation that this domain is a test domain
for validating domain schemas.
</description>
<vcpu>1</vcpu>
<os>
<type arch='x86_64' machine='pc-0.14'>hvm</type>
</os>
<features>
<acpi/>
<apic/>
<pae/>
</features>
<clock offset='utc'/>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>restart</on_crash>
<devices>
<emulator>/usr/bin/qemu-kvm</emulator>
</devices>
</domain>

View File

@ -1,6 +1,11 @@
<domain type='qemu'>
<name>QEMUGuest1</name>
<uuid>c7a5fdbd-edaf-9455-926a-d65c16db1809</uuid>
<title>A description of the test machine.</title>
<description>
A test of qemu&apos;s minimal configuration.
This test also tests the description and title elements.
</description>
<memory>219100</memory>
<currentMemory>219100</currentMemory>
<vcpu cpuset='1-4,8-20,525'>1</vcpu>