From f251dedaa31b48f7c05a4b53c112b40ebca890ef Mon Sep 17 00:00:00 2001
From: Anas Nashif <anas.nashif@intel.com>
Date: Tue, 13 Nov 2012 12:30:55 -0800
Subject: Imported Upstream version 1.2.18

---
 docs/api/chapters/init-and-shutdown.sgml | 104 +++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 docs/api/chapters/init-and-shutdown.sgml

(limited to 'docs/api/chapters/init-and-shutdown.sgml')

diff --git a/docs/api/chapters/init-and-shutdown.sgml b/docs/api/chapters/init-and-shutdown.sgml
new file mode 100644
index 00000000..688a6372
--- /dev/null
+++ b/docs/api/chapters/init-and-shutdown.sgml
@@ -0,0 +1,104 @@
+<chapter id="xmlsec-notes-init-shutdown">
+    <title>Initialization and shutdown.</title>
+    <para>XML Security Library initialization/shutdown 
+	process includes initialization and shutdown of the
+	dependent libraries:
+	<itemizedlist>
+	    <listitem><para>libxml library;</para></listitem>
+	    <listitem><para>libxslt library;</para></listitem>
+	    <listitem><para>crypto library (OpenSSL, GnuTLS, GCrypt, NSS, ...);</para></listitem>
+	    <listitem><para>xmlsec library 
+		(<link linkend="xmlSecInit">xmlSecInit</link> 
+		and <link linkend="xmlSecShutdown">xmlSecShutdown</link> 
+		functions);
+	    </para></listitem>
+	    <listitem><para>xmlsec-crypto library
+		(<link linkend="xmlSecCryptoDLLoadLibrary">xmlSecCryptoDLLoadLibrary</link> 
+		to load xmlsec-crypto library dynamicaly if needed, 
+		<link linkend="xmlSecCryptoInit">xmlSecCryptoInit</link> 
+		and <link linkend="xmlSecCryptoShutdown">xmlSecCryptoShutdown</link> 
+		functions);
+	    </para></listitem>
+	</itemizedlist>
+	xmlsec-crypto library also provides a convinient functions 
+	<link linkend="xmlSecAppCryptoInit">xmlSecAppCryptoInit</link> 
+	and <link linkend="xmlSecAppCryptoShutdown">xmlSecAppCryptoShutdown</link> 
+	to initialize the crypto library itself but application can do it 
+	by itself.
+	</para>
+	<para>
+	     <example>
+		<title>Initializing application.</title>
+		<programlisting><![CDATA[
+    /* Init libxml and libxslt libraries */
+    xmlInitParser();
+    LIBXML_TEST_VERSION
+    xmlLoadExtDtdDefaultValue = XML_DETECT_IDS | XML_COMPLETE_ATTRS;
+    xmlSubstituteEntitiesDefault(1);
+#ifndef XMLSEC_NO_XSLT
+    xmlIndentTreeOutput = 1; 
+#endif /* XMLSEC_NO_XSLT */
+        	
+    /* Init xmlsec library */
+    if(xmlSecInit() < 0) {
+	fprintf(stderr, "Error: xmlsec initialization failed.\n");
+	return(-1);
+    }
+
+    /* Check loaded library version */
+    if(xmlSecCheckVersion() != 1) {
+	fprintf(stderr, "Error: loaded xmlsec library version is not compatible.\n");
+	return(-1);
+    }    
+
+    /* Load default crypto engine if we are supporting dynamic
+     * loading for xmlsec-crypto libraries. Use the crypto library
+     * name ("openssl", "nss", etc.) to load corresponding 
+     * xmlsec-crypto library.
+     */
+#ifdef XMLSEC_CRYPTO_DYNAMIC_LOADING
+    if(xmlSecCryptoDLLoadLibrary(BAD_CAST XMLSEC_CRYPTO) < 0) {
+	fprintf(stderr, "Error: unable to load default xmlsec-crypto library. Make sure\n"
+			"that you have it installed and check shared libraries path\n"
+			"(LD_LIBRARY_PATH) envornment variable.\n");
+	return(-1);	
+    }
+#endif /* XMLSEC_CRYPTO_DYNAMIC_LOADING */
+
+    /* Init crypto library */
+    if(xmlSecCryptoAppInit(NULL) < 0) {
+	fprintf(stderr, "Error: crypto initialization failed.\n");
+	return(-1);
+    }
+
+    /* Init xmlsec-crypto library */
+    if(xmlSecCryptoInit() < 0) {
+	fprintf(stderr, "Error: xmlsec-crypto initialization failed.\n");
+	return(-1);
+    }
+		]]></programlisting>
+	    </example>
+	</para>
+
+	<para>
+	     <example>
+		<title>Shutting down application.</title>
+		<programlisting><![CDATA[
+    /* Shutdown xmlsec-crypto library */
+    xmlSecCryptoShutdown();
+    
+    /* Shutdown crypto library */
+    xmlSecCryptoAppShutdown();
+    
+    /* Shutdown xmlsec library */
+    xmlSecShutdown();
+
+    /* Shutdown libxslt/libxml */
+#ifndef XMLSEC_NO_XSLT
+    xsltCleanupGlobals();            
+#endif /* XMLSEC_NO_XSLT */
+    xmlCleanupParser();		
+		]]></programlisting>
+	    </example>
+    </para>
+</chapter>
-- 
cgit v1.2.3