This patch adds new elements <title> and <description> to the Network XML.
- The <title> attribute holds a short title defined by the user and
cannot contain newlines.
- The <description> attribute holds any documentation that the user
wants to store.
- Schema definitions of <title> and <description> have been moved from
domaincommon.rng to basictypes.rng for use by network and future objects.
- Added Network XML parser logic for the above.
Signed-off-by: K Shiva Kiran <shiva_kr@xxxxxxxxxx>
---
docs/formatnetwork.rst | 11 +++++++++++
src/conf/network_conf.c | 18 ++++++++++++++++++
src/conf/network_conf.h | 2 ++
src/conf/schemas/basictypes.rng | 15 +++++++++++++++
src/conf/schemas/domaincommon.rng | 15 ---------------
src/conf/schemas/network.rng | 10 ++++++++++
6 files changed, 56 insertions(+), 15 deletions(-)
diff --git a/docs/formatnetwork.rst b/docs/formatnetwork.rst
index b5dc29db07..c54d53070a 100644
--- a/docs/formatnetwork.rst
+++ b/docs/formatnetwork.rst
@@ -30,6 +30,8 @@ The first elements provide basic metadata about the virtual network.
<network ipv6='yes' trustGuestRxFilters='no'>
<name>default</name>
<uuid>3e3fce45-4f53-4fa7-bb32-11f34168b82b</uuid>
+ <title>A short description - title - of the network</title>
+ <description>Some human readable description</description>
<metadata>
<app1:foo xmlns:app1="http://app1.org/app1/";>..</app1:foo>
<app2:bar xmlns:app2="http://app1.org/app2/";>..</app2:bar>
@@ -47,6 +49,7 @@ The first elements provide basic metadata about the virtual network.
the virtual network. The format must be RFC 4122 compliant, eg
``3e3fce45-4f53-4fa7-bb32-11f34168b82b``. If omitted when defining/creating a
new network, a random UUID is generated. :since:`Since 0.3.0`
+``metadata``
The ``metadata`` node can be used by applications to store custom metadata in
the form of XML nodes/trees. Applications must use custom namespaces on their
XML nodes/trees, with only one top-level element per namespace (if the
@@ -65,6 +68,14 @@ The first elements provide basic metadata about the virtual network.
documentation for more details. Note that an explicit setting of this
attribute in a portgroup or the individual domain interface will override the
setting in the network.
+``title``
+ The optional element ``title`` provides space for a short description of the
+ network. The title should not contain any newlines. :since:`Since 9.7.0` .
+``description``
+ The content of the ``description`` element provides a human readable
+ description of the network. This data is not used by libvirt in any
+ way, it can contain any information the user wants. :since:`Since 9.7.0`
+
Connectivity
~~~~~~~~~~~~
diff --git a/src/conf/network_conf.c b/src/conf/network_conf.c
index 3e137cb562..262e9a9fc7 100644
--- a/src/conf/network_conf.c
+++ b/src/conf/network_conf.c
@@ -281,6 +281,8 @@ virNetworkDefFree(virNetworkDef *def)
virNetDevBandwidthFree(def->bandwidth);
virNetDevVlanClear(&def->vlan);
+ g_free(def->title);
+ g_free(def->description);
xmlFreeNode(def->metadata);
if (def->namespaceData && def->ns.free)
@@ -1599,6 +1601,17 @@ virNetworkDefParseXML(xmlXPathContextPtr ctxt,
def->uuid_specified = true;
}
+ /* Extract short description of network (title) */
+ def->title = virXPathString("string(./title[1])", ctxt);
+ if (def->title && strchr(def->title, '\n')) {
+ virReportError(VIR_ERR_XML_ERROR, "%s",
+ _("Network title can't contain newlines"));
+ return NULL;
+ }
+
+ /* Extract documentation if present */
+ def->description = virXPathString("string(./description[1])", ctxt);
+
/* check if definitions with no IPv6 gateway addresses is to
* allow guest-to-guest communications.
*/
@@ -2311,6 +2324,11 @@ virNetworkDefFormatBuf(virBuffer *buf,
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);
+
if (virXMLFormatMetadata(buf, def->metadata) < 0)
return -1;
diff --git a/src/conf/network_conf.h b/src/conf/network_conf.h
index 2b2e9d15f0..5a1bdb1284 100644
--- a/src/conf/network_conf.h
+++ b/src/conf/network_conf.h
@@ -249,6 +249,8 @@ struct _virNetworkDef {
unsigned char uuid[VIR_UUID_BUFLEN];
bool uuid_specified;
char *name;
+ char *title;
+ char *description;
int connections; /* # of guest interfaces connected to this network */
char *bridge; /* Name of bridge device */
diff --git a/src/conf/schemas/basictypes.rng b/src/conf/schemas/basictypes.rng
index 2d6f1a2c84..26eb538077 100644
--- a/src/conf/schemas/basictypes.rng
+++ b/src/conf/schemas/basictypes.rng
@@ -610,6 +610,21 @@
</choice>
</define>
+ <!--
+ title and description element, may be placed anywhere under the root
+ -->
+ <define name="title">
+ <element name="title">
+ <ref name="objectNameWithSlash"/>
+ </element>
+ </define>
+
+ <define name="description">
+ <element name="description">
+ <text/>
+ </element>
+ </define>
+
<define name="metadata">
<element name="metadata">
<zeroOrMore>
diff --git a/src/conf/schemas/domaincommon.rng b/src/conf/schemas/domaincommon.rng
index c2f56b0490..2556ac01ed 100644
--- a/src/conf/schemas/domaincommon.rng
+++ b/src/conf/schemas/domaincommon.rng
@@ -8,21 +8,6 @@
<include href="nwfilter_params.rng"/>
<include href="privatedata.rng"/>
- <!--
- description and title element, may be placed anywhere under the root
- -->
- <define name="description">
- <element name="description">
- <text/>
- </element>
- </define>
-
- <define name="title">
- <element name="title">
- <ref name="objectNameWithSlash"/>
- </element>
- </define>
-
<define name="createMode">
<data type="unsignedInt">
<param name="pattern">0[0-7]{3}|[0-7]{1,3}</param>
diff --git a/src/conf/schemas/network.rng b/src/conf/schemas/network.rng
index 4317572208..cda174ab4b 100644
--- a/src/conf/schemas/network.rng
+++ b/src/conf/schemas/network.rng
@@ -37,6 +37,16 @@
<text/>
</element>
+ <!-- <title> element -->
+ <optional>
+ <ref name="title"/>
+ </optional>
+
+ <!-- <description> element -->
+ <optional>
+ <ref name="description"/>
+ </optional>
+
<!-- <metadata> element -->
<optional>
<ref name="metadata"/>
--
2.41.0
