public API for domain XML conversions

ChangeLog

+Thu May 21 14:32:22 BST 2009 Daniel P. Berrange <berrange@redhat.com>
+
+	Public APIs for domain XML conversions.
+	* docs/devhelp/libvirt-libvirt.html, docs/devhelp/libvirt-virterror.html,
+	docs/html/libvirt-libvirt.html, docs/html/libvirt-virterror.html,
+	docs/libvirt-api.xml, docs/libvirt-refs.xml: Regenerate with new public
+	APIs
+	* include/libvirt/libvirt.h, include/libvirt/libvirt.h.in,
+	src/driver.h, src/libvirt.c, src/libvirt_public.syms: Add
+	virConnectDomainXMLFromNative and virConnectDomainXMLToNative
+	* src/lxc_driver.c, src/openvz_driver.c, src/qemu_driver.c,
+	src/remote_internal.c, src/test.c, src/uml_driver.c,
+	src/xen_unified.c: Stub out new API entry points
+	* src/virsh.c: Add domxml-to-native and domxml-from-native commands
+
 Thu May 21 11:52:22 BST 2009 Daniel P. Berrange <berrange@redhat.com>
 
 	* python/generator.py, python/libvirt_wrap.h, python/types.c: Add

docs/devhelp/libvirt-virterror.html

@@ -107,7 +107,8 @@ void	<a href="#virConnResetLastError">virConnResetLastError</a>		(<a href="libvi
     <a name="VIR_FROM_NODEDEV">VIR_FROM_NODEDEV</a> = 22 /* Error from node device monitor */
     <a name="VIR_FROM_XEN_INOTIFY">VIR_FROM_XEN_INOTIFY</a> = 23 /* Error from xen inotify layer */
     <a name="VIR_FROM_SECURITY">VIR_FROM_SECURITY</a> = 24 /* Error from security framework */
-    <a name="VIR_FROM_VBOX">VIR_FROM_VBOX</a> = 25 /*  Error from VirtualBox driver */
+    <a name="VIR_FROM_VBOX">VIR_FROM_VBOX</a> = 25 /* Error from VirtualBox driver */
+    <a name="VIR_FROM_INTERFACE">VIR_FROM_INTERFACE</a> = 26 /*  Error when operating on an interface */
 };
 </pre><p/>
 </div>
@@ -176,7 +177,10 @@ void	<a href="#virConnResetLastError">virConnResetLastError</a>		(<a href="libvi
     <a name="VIR_ERR_INVALID_NODE_DEVICE">VIR_ERR_INVALID_NODE_DEVICE</a> = 52 /* invalid node device object */
     <a name="VIR_ERR_NO_NODE_DEVICE">VIR_ERR_NO_NODE_DEVICE</a> = 53 /* node device not found */
     <a name="VIR_ERR_NO_SECURITY_MODEL">VIR_ERR_NO_SECURITY_MODEL</a> = 54 /* security model not found */
-    <a name="VIR_ERR_OPERATION_INVALID">VIR_ERR_OPERATION_INVALID</a> = 55 /*  operation is not applicable at this time */
+    <a name="VIR_ERR_OPERATION_INVALID">VIR_ERR_OPERATION_INVALID</a> = 55 /* operation is not applicable at this time */
+    <a name="VIR_WAR_NO_INTERFACE">VIR_WAR_NO_INTERFACE</a> = 56 /* failed to start interface driver */
+    <a name="VIR_ERR_NO_INTERFACE">VIR_ERR_NO_INTERFACE</a> = 57 /* interface driver not running */
+    <a name="VIR_ERR_INVALID_INTERFACE">VIR_ERR_INVALID_INTERFACE</a> = 58 /*  invalid interface object */
 };
 </pre><p/>
 </div>

include/libvirt/libvirt.h

@@ -591,6 +591,16 @@ typedef enum {
 char *                  virDomainGetXMLDesc     (virDomainPtr domain,
                                                  int flags);
 
+
+char *                  virConnectDomainXMLFromNative(virConnectPtr conn,
+                                                      const char *nativeFormat,
+                                                      const char *nativeConfig,
+                                                      unsigned int flags);
+char *                  virConnectDomainXMLToNative(virConnectPtr conn,
+                                                    const char *nativeFormat,
+                                                    const char *domainXml,
+                                                    unsigned int flags);
+
 int                     virDomainBlockStats     (virDomainPtr dom,
                                                  const char *path,
                                                  virDomainBlockStatsPtr stats,

include/libvirt/libvirt.h.in

@@ -591,6 +591,16 @@ typedef enum {
 char *                  virDomainGetXMLDesc     (virDomainPtr domain,
                                                  int flags);
 
+
+char *                  virConnectDomainXMLFromNative(virConnectPtr conn,
+                                                      const char *nativeFormat,
+                                                      const char *nativeConfig,
+                                                      unsigned int flags);
+char *                  virConnectDomainXMLToNative(virConnectPtr conn,
+                                                    const char *nativeFormat,
+                                                    const char *domainXml,
+                                                    unsigned int flags);
+
 int                     virDomainBlockStats     (virDomainPtr dom,
                                                  const char *path,
                                                  virDomainBlockStatsPtr stats,

src/driver.h

@@ -152,6 +152,16 @@ typedef int
 typedef char *
         (*virDrvDomainDumpXML)		(virDomainPtr dom,
                                          int flags);
+typedef char *
+        (*virDrvConnectDomainXMLFromNative) (virConnectPtr conn,
+                                             const char *nativeFormat,
+                                             const char *nativeConfig,
+                                             unsigned int flags);
+typedef char *
+        (*virDrvConnectDomainXMLToNative) (virConnectPtr conn,
+                                           const char *nativeFormat,
+                                           const char *domainXml,
+                                           unsigned int flags);
 typedef int
         (*virDrvListDefinedDomains)	(virConnectPtr conn,
                                          char **const names,
@@ -381,6 +391,8 @@ struct _virDriver {
     virDrvDomainGetSecurityLabel     domainGetSecurityLabel;
     virDrvNodeGetSecurityModel  nodeGetSecurityModel;
     virDrvDomainDumpXML		domainDumpXML;
+    virDrvConnectDomainXMLFromNative domainXMLFromNative;
+    virDrvConnectDomainXMLToNative domainXMLToNative;
     virDrvListDefinedDomains	listDefinedDomains;
     virDrvNumOfDefinedDomains	numOfDefinedDomains;
     virDrvDomainCreate		domainCreate;

src/libvirt.c

@@ -2730,6 +2730,111 @@ error:
     return NULL;
 }
 
+/**
+ * virConnectDomainXMLFromNative:
+ * @conn: a connection object
+ * @nativeFormat: configuration format importing from
+ * @nativeConfig: the configuration data to import
+ * @flags: currently unused, pass 0
+ *
+ * Reads native configuration data  describing a domain, and
+ * generates libvirt domain XML. The format of the native
+ * data is hypervisor dependant.
+ *
+ * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error.
+ *         the caller must free() the returned value.
+ */
+char *virConnectDomainXMLFromNative(virConnectPtr conn,
+                                    const char *nativeFormat,
+                                    const char *nativeConfig,
+                                    unsigned int flags)
+{
+    DEBUG("conn=%p, format=%s config=%s flags=%u", conn, nativeFormat, nativeConfig, flags);
+
+    virResetLastError();
+
+    if (!VIR_IS_CONNECT(conn)) {
+        virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
+        return (NULL);
+    }
+
+    if (nativeFormat == NULL || nativeConfig == NULL) {
+        virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return (NULL);
+    }
+
+    if (conn->driver->domainXMLFromNative) {
+        char *ret;
+        ret = conn->driver->domainXMLFromNative (conn,
+                                                 nativeFormat,
+                                                 nativeConfig,
+                                                 flags);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
+
+error:
+    /* Copy to connection error object for back compatability */
+    virSetConnError(conn);
+    return NULL;
+}
+
+/**
+ * virConnectDomainXMLToNative:
+ * @conn: a connection object
+ * @nativeFormat: configuration format exporting to
+ * @domainXml: the domain configuration to export
+ * @flags: currently unused, pass 0
+ *
+ * Reads a domain XML configuration document, and generates
+ * generates a native configuration file describing the domain.
+ * The format of the native data is hypervisor dependant.
+ *
+ * Returns a 0 terminated UTF-8 encoded native config datafile, or NULL in case of error.
+ *         the caller must free() the returned value.
+ */
+char *virConnectDomainXMLToNative(virConnectPtr conn,
+                                  const char *nativeFormat,
+                                  const char *domainXml,
+                                  unsigned int flags)
+{
+    DEBUG("conn=%p, format=%s xml=%s flags=%u", conn, nativeFormat, domainXml, flags);
+
+    virResetLastError();
+
+    if (!VIR_IS_CONNECT(conn)) {
+        virLibConnError(NULL, VIR_ERR_INVALID_CONN, __FUNCTION__);
+        return (NULL);
+    }
+
+    if (nativeFormat == NULL || domainXml == NULL) {
+        virLibConnError(conn, VIR_ERR_INVALID_ARG, __FUNCTION__);
+        return (NULL);
+    }
+
+    if (conn->driver->domainXMLToNative) {
+        char *ret;
+        ret = conn->driver->domainXMLToNative(conn,
+                                              nativeFormat,
+                                              domainXml,
+                                              flags);
+        if (!ret)
+            goto error;
+        return ret;
+    }
+
+    virLibConnError (conn, VIR_ERR_NO_SUPPORT, __FUNCTION__);
+
+error:
+    /* Copy to connection error object for back compatability */
+    virSetConnError(conn);
+    return NULL;
+}
+
+
 /**
  * virDomainMigrate:
  * @domain: a domain object

src/libvirt_public.syms

@@ -264,8 +264,6 @@ LIBVIRT_0.6.3 {
 	virNodeDeviceDestroy;
 } LIBVIRT_0.6.1;
 
-# .... define new API here using predicted next version number ....
-
 LIBVIRT_0.6.4 {
     global:
 	virInterfaceGetConnect;
@@ -283,4 +281,8 @@ LIBVIRT_0.6.4 {
 	virInterfaceCreate;
 	virInterfaceDestroy;
 	virStorageVolCreateXMLFrom;
+	virConnectDomainXMLFromNative;
+	virConnectDomainXMLToNative;
 } LIBVIRT_0.6.3;
+
+# .... define new API here using predicted next version number ....

src/lxc_driver.c

@@ -1457,6 +1457,8 @@ static virDriver lxcDriver = {
     NULL, /* domainGetSecurityLabel */
     NULL, /* nodeGetSecurityModel */
     lxcDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     lxcListDefinedDomains, /* listDefinedDomains */
     lxcNumDefinedDomains, /* numOfDefinedDomains */
     lxcDomainStart, /* domainCreate */

src/openvz_driver.c

@@ -1344,6 +1344,8 @@ static virDriver openvzDriver = {
     NULL, /* domainGetSecurityLabel */
     NULL, /* nodeGetSecurityModel */
     openvzDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     openvzListDefinedDomains, /* listDefinedDomains */
     openvzNumDefinedDomains, /* numOfDefinedDomains */
     openvzDomainCreate, /* domainCreate */

src/qemu_driver.c

@@ -5224,6 +5224,8 @@ static virDriver qemuDriver = {
     qemudDomainGetSecurityLabel, /* domainGetSecurityLabel */
     qemudNodeGetSecurityModel, /* nodeGetSecurityModel */
     qemudDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     qemudListDefinedDomains, /* listDefinedDomains */
     qemudNumDefinedDomains, /* numOfDefinedDomains */
     qemudDomainStart, /* domainCreate */

src/remote_internal.c

@@ -7301,6 +7301,8 @@ static virDriver driver = {
     remoteDomainGetSecurityLabel, /* domainGetSecurityLabel */
     remoteNodeGetSecurityModel, /* nodeGetSecurityModel */
     remoteDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     remoteListDefinedDomains, /* listDefinedDomains */
     remoteNumOfDefinedDomains, /* numOfDefinedDomains */
     remoteDomainCreate, /* domainCreate */

src/test.c

@@ -3591,6 +3591,8 @@ static virDriver testDriver = {
     NULL, /* domainGetSecurityLabel */
     NULL, /* nodeGetSecurityModel */
     testDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     testListDefinedDomains, /* listDefinedDomains */
     testNumOfDefinedDomains, /* numOfDefinedDomains */
     testDomainCreate, /* domainCreate */

src/uml_driver.c

@@ -1854,6 +1854,8 @@ static virDriver umlDriver = {
     NULL, /* domainGetSecurityLabel */
     NULL, /* nodeGetSecurityModel */
     umlDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     umlListDefinedDomains, /* listDefinedDomains */
     umlNumDefinedDomains, /* numOfDefinedDomains */
     umlDomainStart, /* domainCreate */

src/virsh.c

@@ -2209,6 +2209,98 @@ cmdDumpXML(vshControl *ctl, const vshCmd *cmd)
     return ret;
 }
 
+/*
+ * "domxml-from-native" command
+ */
+static const vshCmdInfo info_domxmlfromnative[] = {
+    {"help", gettext_noop("Convert native config to domain XML")},
+    {"desc", gettext_noop("Convert native guest configuration format to domain XML format.")},
+    {NULL, NULL}
+};
+
+static const vshCmdOptDef opts_domxmlfromnative[] = {
+    {"format", VSH_OT_DATA, VSH_OFLAG_REQ, gettext_noop("source config data format")},
+    {"config", VSH_OT_DATA, VSH_OFLAG_REQ, gettext_noop("config data file to import from")},
+    {NULL, 0, 0, NULL}
+};
+
+static int
+cmdDomXMLFromNative(vshControl *ctl, const vshCmd *cmd)
+{
+    int ret = TRUE;
+    char *format;
+    char *configFile;
+    char *configData;
+    char *xmlData;
+    int flags = 0;
+
+    if (!vshConnectionUsability(ctl, ctl->conn, TRUE))
+        return FALSE;
+
+    format = vshCommandOptString(cmd, "format", NULL);
+    configFile = vshCommandOptString(cmd, "config", NULL);
+
+    if (virFileReadAll(configFile, 1024*1024, &configData) < 0) {
+        return FALSE;
+    }
+
+    xmlData = virConnectDomainXMLFromNative(ctl->conn, format, configData, flags);
+    if (xmlData != NULL) {
+        printf("%s", xmlData);
+        free(xmlData);
+    } else {
+        ret = FALSE;
+    }
+
+    return ret;
+}
+
+/*
+ * "domxml-to-native" command
+ */
+static const vshCmdInfo info_domxmltonative[] = {
+    {"help", gettext_noop("Convert domain XML to native config")},
+    {"desc", gettext_noop("Convert domain XML config to a native guest configuration format.")},
+    {NULL, NULL}
+};
+
+static const vshCmdOptDef opts_domxmltonative[] = {
+    {"format", VSH_OT_DATA, VSH_OFLAG_REQ, gettext_noop("target config data type format")},
+    {"xml", VSH_OT_DATA, VSH_OFLAG_REQ, gettext_noop("xml data file to export from")},
+    {NULL, 0, 0, NULL}
+};
+
+static int
+cmdDomXMLToNative(vshControl *ctl, const vshCmd *cmd)
+{
+    int ret = TRUE;
+    char *format;
+    char *xmlFile;
+    char *configData;
+    char *xmlData;
+    int flags = 0;
+
+    if (!vshConnectionUsability(ctl, ctl->conn, TRUE))
+        return FALSE;
+
+    format = vshCommandOptString(cmd, "format", NULL);
+    xmlFile = vshCommandOptString(cmd, "xml", NULL);
+
+    if (virFileReadAll(xmlFile, 1024*1024, &xmlData) < 0) {
+        return FALSE;
+    }
+
+    configData = virConnectDomainXMLToNative(ctl->conn, format, xmlData, flags);
+    if (configData != NULL) {
+        printf("%s", configData);
+        free(configData);
+    } else {
+        ret = FALSE;
+    }
+
+    return ret;
+}
+
 /*
  * "domname" command
  */
@@ -6030,6 +6122,8 @@ static const vshCmdDef commands[] = {
     {"domstate", cmdDomstate, opts_domstate, info_domstate},
     {"domblkstat", cmdDomblkstat, opts_domblkstat, info_domblkstat},
     {"domifstat", cmdDomIfstat, opts_domifstat, info_domifstat},
+    {"domxml-from-native", cmdDomXMLFromNative, opts_domxmlfromnative, info_domxmlfromnative},
+    {"domxml-to-native", cmdDomXMLToNative, opts_domxmltonative, info_domxmltonative},
     {"dumpxml", cmdDumpXML, opts_dumpxml, info_dumpxml},
     {"edit", cmdEdit, opts_edit, info_edit},
     {"find-storage-pool-sources", cmdPoolDiscoverSources,

src/xen_unified.c

@@ -1580,6 +1580,8 @@ static virDriver xenUnifiedDriver = {
     NULL, /* domainGetSecurityLabel */
     NULL, /* nodeGetSecurityModel */
     xenUnifiedDomainDumpXML, /* domainDumpXML */
+    NULL, /* domainXmlFromNative */
+    NULL, /* domainXmlToNative */
     xenUnifiedListDefinedDomains, /* listDefinedDomains */
     xenUnifiedNumOfDefinedDomains, /* numOfDefinedDomains */
     xenUnifiedDomainCreate, /* domainCreate */