undefine: Define the new API

This introduces a new API virDomainUndefineFlags to control the
domain undefine process, as the existing API virDomainUndefine
doesn't support flags.

Currently only flag VIR_DOMAIN_UNDEFINE_MANAGED_SAVE is supported.
If the domain has a managed save image, including
VIR_DOMAIN_UNDEFINE_MANAGED_SAVE in @flags will also remove that
file, and omitting the flag will cause undefine process to fail.

This patch also changes the behavior of virDomainUndefine, if the
domain has a managed save image, the undefine will be refused.

include/libvirt/libvirt.h.in

@@ -1200,6 +1200,16 @@ int                     virDomainMemoryPeek (virDomainPtr dom,
 virDomainPtr            virDomainDefineXML      (virConnectPtr conn,
                                                  const char *xml);
 int                     virDomainUndefine       (virDomainPtr domain);
+
+typedef enum {
+    VIR_DOMAIN_UNDEFINE_MANAGED_SAVE = (1 << 0),
+
+    /* Future undefine control flags should come here. */
+} virDomainUndefineFlagsValues;
+
+
+int                     virDomainUndefineFlags   (virDomainPtr domain,
+                                                  unsigned int flags);
 int                     virConnectNumOfDefinedDomains  (virConnectPtr conn);
 int                     virConnectListDefinedDomains (virConnectPtr conn,
                                                  char **const names,

src/driver.h

@@ -218,6 +218,9 @@ typedef virDomainPtr
                                          const char *xml);
 typedef int
         (*virDrvDomainUndefine)		(virDomainPtr dom);
+typedef int
+        (*virDrvDomainUndefineFlags)	(virDomainPtr dom,
+                                         unsigned int flags);
 typedef int
         (*virDrvDomainSetVcpus)		(virDomainPtr domain,
                                          unsigned int nvcpus);
@@ -733,6 +736,7 @@ struct _virDriver {
     virDrvDomainCreateWithFlags	domainCreateWithFlags;
     virDrvDomainDefineXML           domainDefineXML;
     virDrvDomainUndefine            domainUndefine;
+    virDrvDomainUndefineFlags       domainUndefineFlags;
     virDrvDomainAttachDevice	domainAttachDevice;
     virDrvDomainAttachDeviceFlags	domainAttachDeviceFlags;
     virDrvDomainDetachDevice	domainDetachDevice;

src/libvirt.c

@@ -6374,7 +6374,13 @@ error:
  * virDomainUndefine:
  * @domain: pointer to a defined domain
  *
- * Undefine a domain but does not stop it if it is running
+ * Undefine a domain. If the domain is running, it's converted to
+ * transient domain, without stopping it. If the domain is inactive,
+ * the domain configuration is removed.
+ *
+ * If the domain has a managed save image (see
+ * virDomainHasManagedSaveImage()), then the undefine will fail. See
+ * virDomainUndefineFlags() for more control.
  *
  * Returns 0 in case of success, -1 in case of error
  */
@@ -6412,6 +6418,58 @@ error:
     return -1;
 }
 
+/**
+ * virDomainUndefineFlags:
+ * @domain: pointer to a defined domain
+ * @flags: bitwise-or of supported virDomainUndefineFlagsValues
+ *
+ * Undefine a domain. If the domain is running, it's converted to
+ * transient domain, without stopping it. If the domain is inactive,
+ * the domain configuration is removed.
+ *
+ * If the domain has a managed save image (see virDomainHasManagedSaveImage()),
+ * then including VIR_DOMAIN_UNDEFINE_MANAGED_SAVE in @flags will also remove
+ * that file, and omitting the flag will cause the undefine process to fail.
+ *
+ * Returns 0 in case of success, -1 in case of error
+ */
+int
+virDomainUndefineFlags(virDomainPtr domain,
+                       unsigned int flags)
+{
+    virConnectPtr conn;
+
+    VIR_DOMAIN_DEBUG(domain, "flags=%x", flags);
+
+    virResetLastError();
+
+    if (!VIR_IS_CONNECTED_DOMAIN(domain)) {
+        virLibDomainError(VIR_ERR_INVALID_DOMAIN, __FUNCTION__);
+        virDispatchError(NULL);
+        return -1;
+    }
+    conn = domain->conn;
+    if (conn->flags & VIR_CONNECT_RO) {
+        virLibDomainError(VIR_ERR_OPERATION_DENIED, __FUNCTION__);
+        goto error;
+    }
+
+    if (conn->driver->domainUndefineFlags) {
+        int ret;
+        ret = conn->driver->domainUndefineFlags (domain, flags);
+        if (ret < 0)
+            goto error;
+        return ret;
+    }
+
+    virLibConnError(VIR_ERR_NO_SUPPORT, __FUNCTION__);
+
+error:
+    virDispatchError(domain->conn);
+    return -1;
+}
+
+
 /**
  * virConnectNumOfDefinedDomains:
  * @conn: pointer to the hypervisor connection

src/libvirt_public.syms

@@ -466,4 +466,9 @@ LIBVIRT_0.9.3 {
         virNodeGetMemoryStats;
 } LIBVIRT_0.9.2;
 
+LIBVIRT_0.9.4 {
+    global:
+        virDomainUndefineFlags;
+} LIBVIRT_0.9.3;
+
 # .... define new API here using predicted next version number ....