* Makefile.am: extended make tests to run those in docs/examples

* docs/examples/suspend.c docs/examples/*: added an example of
  suspend/resume and regenerated
Daniel

6 files changed, 190 insertions, 3 deletions

diff --git a/ChangeLog b/ChangeLog
index 414899788..85cba21b2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Tue Feb 21 09:14:07 EST 2006 Daniel Veillard <veillard@redhat.com>
+
+	* Makefile.am: extended make tests to run those in docs/examples
+	* docs/examples/suspend.c docs/examples/*: added an example of
+	  suspend/resume and regenerated
+
 Tue Feb 21 14:21:39 CET 2006 Daniel Veillard <veillard@redhat.com>
 
 	* TODO: updated
diff --git a/Makefile.am b/Makefile.am
index c71ce6e32..04d89366b 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -15,6 +15,7 @@ rpm: clean
 check-local: all tests
 
 tests:
+	@(cd docs/examples ; $(MAKE) MAKEFLAGS+=--silent tests)
 	@(if [ "@PYTHON_SUBDIR@" != "" ] ; then cd python ; \
 	  $(MAKE) MAKEFLAGS+=--silent tests ; fi)
 	
diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am
index 26844e914..4866bfcd3 100644
--- a/docs/examples/Makefile.am
+++ b/docs/examples/Makefile.am
@@ -17,18 +17,24 @@ install-data-local:
 
 EXTRA_DIST=examples.xsl index.py examples.xml 
 
-noinst_PROGRAMS=info1 
+noinst_PROGRAMS=info1 suspend 
 
 info1_SOURCES=info1.c
 info1_LDFLAGS=
 info1_DEPENDENCIES= $(DEPS)
 info1_LDADD= $(LDADDS)
 
+suspend_SOURCES=suspend.c
+suspend_LDFLAGS=
+suspend_DEPENDENCIES= $(DEPS)
+suspend_LDADD= $(LDADDS)
+
 valgrind: 
 	$(MAKE) CHECKER='valgrind' tests
 
 tests: $(noinst_PROGRAMS)
 	@(echo '## examples regression tests')
 	@($(CHECKER) ./info1)
+	@($(CHECKER) ./suspend)
 
 
diff --git a/docs/examples/examples.xml b/docs/examples/examples.xml
index 5d541334e..84dbfe25f 100644
--- a/docs/examples/examples.xml
+++ b/docs/examples/examples.xml
@@ -18,29 +18,69 @@
       <function line='29' file='libvirt' name='virConnectOpenReadOnly'/>
     </uses>
   </example>
+  <example filename='suspend.c'>
+    <synopsis>Suspend a domain and then resume its execution</synopsis>
+    <purpose>Demonstrate the basic use of the library to suspend and resume a domain. If no id is given on the command line this script will suspend and resume the first domain found which is not Domain 0.</purpose>
+    <usage>suspend [id]</usage>
+    <test>suspend</test>
+    <author>Daniel Veillard</author>
+    <copy>see Copyright for the status of this software. </copy>
+    <section>Scheduling</section>
+    <includes>
+    </includes>
+    <uses>
+      <function line='30' file='libvirt' name='virDomainGetInfo'/>
+      <function line='110' file='libvirt' name='virConnectListDomains'/>
+      <function line='92' file='libvirt' name='virDomainFree'/>
+      <function line='72' file='libvirt' name='virDomainResume'/>
+      <function line='49' file='libvirt' name='virDomainLookupByID'/>
+      <function line='131' file='libvirt' name='virConnectClose'/>
+      <struct line='27' file='libvirt' name='virDomainInfo'/>
+      <function line='61' file='libvirt' name='virDomainSuspend'/>
+      <function line='99' file='libvirt' name='virConnectOpenReadOnly'/>
+    </uses>
+  </example>
   <symbols>
     <symbol name='virConnectClose'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
+    </symbol>
+    <symbol name='virConnectListDomains'>
+      <ref filename='suspend.c'/>
     </symbol>
     <symbol name='virConnectOpenReadOnly'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
     </symbol>
     <symbol name='virDomainFree'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
     </symbol>
     <symbol name='virDomainGetInfo'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
     </symbol>
     <symbol name='virDomainInfo'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
     </symbol>
     <symbol name='virDomainLookupByID'>
       <ref filename='info1.c'/>
+      <ref filename='suspend.c'/>
+    </symbol>
+    <symbol name='virDomainResume'>
+      <ref filename='suspend.c'/>
+    </symbol>
+    <symbol name='virDomainSuspend'>
+      <ref filename='suspend.c'/>
     </symbol>
   </symbols>
   <sections>
     <section name='Informations'>
       <example filename='info1.c'/>
     </section>
+    <section name='Scheduling'>
+      <example filename='suspend.c'/>
+    </section>
   </sections>
 </examples>
diff --git a/docs/examples/index.html b/docs/examples/index.html
index 8cdeed767..ceff46a43 100644
--- a/docs/examples/index.html
+++ b/docs/examples/index.html
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><link rel="stylesheet" type="text/css" href="../libvirt.css" /><link rel="SHORTCUT ICON" href="/32favicon.png" /><title>Libvirt set of C code examples</title></head><body><div id="container"><div id="intro"><div id="adjustments"></div><div id="pageHeader"></div><div id="content2"><h1 class="style1">Libvirt set of C code examples</h1><p> The examples are stored per section depending on the main focus
-    of the example:</p><ul><li><p><a href="#Informations">Informations</a> :</p><ul><li><a href="#info1.c">info1.c</a>: Extract informations about Xen domain 0</li></ul></li></ul><p> Getting the compilation options and libraries dependancies needed
+    of the example:</p><ul><li><p><a href="#Informations">Informations</a> :</p><ul><li><a href="#info1.c">info1.c</a>: Extract informations about Xen domain 0</li></ul></li><li><p><a href="#Scheduling">Scheduling</a> :</p><ul><li><a href="#suspend.c">suspend.c</a>: Suspend a domain and then resume its execution</li></ul></li></ul><p> Getting the compilation options and libraries dependancies needed
 to generate binaries from the examples is best done on Linux/Unix by using
 the pkg-config data which should have been installed as part of <i>make
-install</i> step or when installing the libvirt development package:</p><pre>gcc -o example example.c `pkg-config libvirt --libs`</pre><h2><a name="Informations" id="Informations"></a>Informations Examples</h2><h3><a name="info1.c" href="info1.c" id="info1.c">info1.c</a>: Extract informations about Xen domain 0</h3><p>Demonstrate the basic use of the library to connect to the hypervisor and extract domain informations.</p><p>Uses:</p><ul><li> line 29: Function <a href="../html/libvirt-libvirt.html#virConnectOpenReadOnly">virConnectOpenReadOnly</a> from libvirt.h</li><li> line 36: Function <a href="../html/libvirt-libvirt.html#virDomainLookupByID">virDomainLookupByID</a> from libvirt.h</li><li> line 43: Function <a href="../html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a> from libvirt.h</li><li> line 53: Function <a href="../html/libvirt-libvirt.html#virDomainFree">virDomainFree</a> from libvirt.h</li><li> line 55: Function <a href="../html/libvirt-libvirt.html#virConnectClose">virConnectClose</a> from libvirt.h</li></ul><p>Usage:</p><p>info1</p><p>Author: Daniel Veillard</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="../index.html">Home</a></li><li><a href="../html/index.html">API Menu</a></li><li><a href="../examples/index.html">C code examples</a></li><li><a href="../ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="../Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
+install</i> step or when installing the libvirt development package:</p><pre>gcc -o example example.c `pkg-config libvirt --libs`</pre><h2><a name="Informations" id="Informations"></a>Informations Examples</h2><h3><a name="info1.c" href="info1.c" id="info1.c">info1.c</a>: Extract informations about Xen domain 0</h3><p>Demonstrate the basic use of the library to connect to the hypervisor and extract domain informations.</p><p>Uses:</p><ul><li> line 29: Function <a href="../html/libvirt-libvirt.html#virConnectOpenReadOnly">virConnectOpenReadOnly</a> from libvirt.h</li><li> line 36: Function <a href="../html/libvirt-libvirt.html#virDomainLookupByID">virDomainLookupByID</a> from libvirt.h</li><li> line 43: Function <a href="../html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a> from libvirt.h</li><li> line 53: Function <a href="../html/libvirt-libvirt.html#virDomainFree">virDomainFree</a> from libvirt.h</li><li> line 55: Function <a href="../html/libvirt-libvirt.html#virConnectClose">virConnectClose</a> from libvirt.h</li></ul><p>Usage:</p><p>info1</p><p>Author: Daniel Veillard</p><h2><a name="Scheduling" id="Scheduling"></a>Scheduling Examples</h2><h3><a name="suspend.c" href="suspend.c" id="suspend.c">suspend.c</a>: Suspend a domain and then resume its execution</h3><p>Demonstrate the basic use of the library to suspend and resume a domain. If no id is given on the command line this script will suspend and resume the first domain found which is not Domain 0.</p><p>Uses:</p><ul><li> line 30: Function <a href="../html/libvirt-libvirt.html#virDomainGetInfo">virDomainGetInfo</a> from libvirt.h</li><li> line 49: Function <a href="../html/libvirt-libvirt.html#virDomainLookupByID">virDomainLookupByID</a> from libvirt.h</li><li> line 61: Function <a href="../html/libvirt-libvirt.html#virDomainSuspend">virDomainSuspend</a> from libvirt.h</li><li> line 72: Function <a href="../html/libvirt-libvirt.html#virDomainResume">virDomainResume</a> from libvirt.h</li><li> line 92: Function <a href="../html/libvirt-libvirt.html#virDomainFree">virDomainFree</a> from libvirt.h</li><li> line 99: Function <a href="../html/libvirt-libvirt.html#virConnectOpenReadOnly">virConnectOpenReadOnly</a> from libvirt.h</li><li> line 110: Function <a href="../html/libvirt-libvirt.html#virConnectListDomains">virConnectListDomains</a> from libvirt.h</li><li> line 131: Function <a href="../html/libvirt-libvirt.html#virConnectClose">virConnectClose</a> from libvirt.h</li></ul><p>Usage:</p><p>suspend [id]</p><p>Author: Daniel Veillard</p></div></div><div class="linkList2"><div class="llinks2"><h3 class="links2"><span>main menu</span></h3><ul><li><a href="../index.html">Home</a></li><li><a href="../html/index.html">API Menu</a></li><li><a href="../examples/index.html">C code examples</a></li><li><a href="../ChangeLog.html">Recent Changes</a></li></ul></div><div class="llinks2"><h3 class="links2"><span>related links</span></h3><ul><li><a href="https://www.redhat.com/archives/libvir-list/">Mail archive</a></li><li><a href="http://www.cl.cam.ac.uk/Research/SRG/netos/xen/index.html">Xen project</a></li><li><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="12" value="Search..." /><input name="submit" type="submit" value="Go" /></form></li><li><a href="http://xmlsoft.org/"><img src="../Libxml2-Logo-90x34.gif" alt="Made with Libxml2 Logo" /></a></li></ul><p class="credits">Graphics and design by <a href="mail:dfong@redhat.com">Diana Fong</a></p></div></div><div id="bottom"><p class="p1"></p></div></div></body></html>
diff --git a/docs/examples/suspend.c b/docs/examples/suspend.c
new file mode 100644
index 000000000..0c5678646
--- /dev/null
+++ b/docs/examples/suspend.c
@@ -0,0 +1,134 @@
+/**
+ * section: Scheduling
+ * synopsis: Suspend a domain and then resume its execution
+ * purpose: Demonstrate the basic use of the library to suspend and
+ *          resume a domain. If no id is given on the command line
+ *          this script will suspend and resume the first domain found
+ *          which is not Domain 0.
+ * usage: suspend [id]
+ * test: suspend
+ * author: Daniel Veillard
+ * copy: see Copyright for the status of this software.
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+#include <libvirt.h>
+
+virConnectPtr conn = NULL; /* the hypervisor connection */
+
+/**
+ * checkDomainState:
+ * @dom: the domain
+ *
+ * Return the current state of a domain or -1 if non-exsitant
+ */
+static int
+checkDomainState(virDomainPtr dom) {
+    virDomainInfo info;        /* the informations being fetched */
+    int ret;
+    
+    ret = virDomainGetInfo(dom, &info);
+    if (ret < 0) {
+	return(-1);
+    }
+    return(info.state);
+}
+
+/**
+ * SuspendAndResumeDomain:
+ * @id: the id of the domain
+ *
+ * extract the domain 0 informations
+ */
+static void
+SuspendAndResumeDomain(int id) {
+    virDomainPtr dom = NULL;   /* the domain being checked */
+    int ret, state;
+
+    /* Find the domain of the given id */
+    dom = virDomainLookupByID(conn, id);
+    if (dom == NULL) {
+        fprintf(stderr, "Failed to find Domain %d\n", id);
+	goto error;
+    }
+
+    /* Check state */
+    state = checkDomainState(dom);
+    if ((state == VIR_DOMAIN_RUNNING) ||
+        (state == VIR_DOMAIN_NOSTATE) ||
+	(state == VIR_DOMAIN_BLOCKED)) {
+	printf("Suspending domain...\n");
+	ret = virDomainSuspend(dom);
+	if (ret < 0) {
+	    fprintf(stderr, "Failed to suspend Domain %d\n", id);
+	    goto error;
+	}
+	state = checkDomainState(dom);
+	if (state != VIR_DOMAIN_PAUSED) {
+	    fprintf(stderr, "Domain %d state is not suspended\n", id);
+	} else {
+	    printf("Domain suspended, resuming it...\n");
+	}
+	ret = virDomainResume(dom);
+	if (ret < 0) {
+	    fprintf(stderr, "Failed to resume Domain %d\n", id);
+	    goto error;
+	}
+	state = checkDomainState(dom);
+	if ((state == VIR_DOMAIN_RUNNING) ||
+	    (state == VIR_DOMAIN_NOSTATE) ||
+	    (state == VIR_DOMAIN_BLOCKED)) {
+	    printf("Domain resumed\n");
+	} else {
+	    fprintf(stderr, "Domain %d state indicate it is not resumed\n", id);
+	}
+    } else {
+        fprintf(stderr, "Domain %d is not in a state where it should be suspended\n", id);
+	goto error;
+    }
+
+error:
+    if (dom != NULL)
+        virDomainFree(dom);
+}
+
+int main(int argc, char **argv) {
+    int id = 0;
+
+    /* NULL means connect to local Xen hypervisor */
+    conn = virConnectOpenReadOnly(NULL);
+    if (conn == NULL) {
+        fprintf(stderr, "Failed to connect to hypervisor\n");
+	goto error;
+    }
+
+    if (argc > 1) {
+        id = atoi(argv[1]);
+    }
+    if (id == 0) {
+        int i, j, ids[10];
+	i = virConnectListDomains(conn, &ids[0], 10);
+	if (i < 0) {
+	    fprintf(stderr, "Failed to list the domains\n");
+	    goto error;
+	}
+	for (j = 0;j < i;j++) {
+	    if (ids[j] != 0) {
+	        id = ids[j];
+		break;
+	    }
+	}
+    }
+    if (id == 0) {
+	fprintf(stderr, "Failed find a running guest domain\n");
+	goto error;
+    }
+    
+    SuspendAndResumeDomain(id);
+
+error:
+    if (conn != NULL)
+	virConnectClose(conn);
+    return(0);
+}