* doc/ref/proxy.xml, doc/ref/sess.xml, doc/manual.xml: Split out, and

  complete, documentation of proxy support.


git-svn-id: http://svn.webdav.org/repos/projects/neon/trunk@1846 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

4 files changed, 205 insertions, 31 deletions

diff --git a/doc/manual.xml b/doc/manual.xml
index 82f669c..a6bb531 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -44,6 +44,7 @@
 <!ENTITY refsessflags SYSTEM "ref/sessflags.xml">
 <!ENTITY referr SYSTEM "ref/err.xml">
 <!ENTITY refopts SYSTEM "ref/opts.xml">
+<!ENTITY refproxy SYSTEM "ref/proxy.xml">
 <!ENTITY refsslvfy SYSTEM "ref/sslvfy.xml">
 <!ENTITY refsslcert SYSTEM "ref/sslcert.xml">
 <!ENTITY refsslcert2 SYSTEM "ref/sslcert2.xml">
@@ -176,6 +177,7 @@ ignoring the WebDAV support if desired.</para>
     &refiaddr; <!-- ne_iaddr_make -->
     &refalloc; <!-- ne_malloc -->
     &refsess; <!-- ne_session_create -->
+    &refproxy; <!-- ne_session_proxy -->
     &refsessflags; <!-- ne_set_session_flag -->
     &refreq; <!-- ne_request_create -->
     &refreqhdr; <!-- ne_add_request_header -->
diff --git a/doc/ref/proxy.xml b/doc/ref/proxy.xml
new file mode 100644
index 0000000..7a410c7
--- /dev/null
+++ b/doc/ref/proxy.xml
@@ -0,0 +1,176 @@
+     <refentry id="refproxy">
+      
+      <refmeta>
+	<refentrytitle>ne_session_proxy</refentrytitle>
+	<manvolnum>3</manvolnum>
+      </refmeta>
+
+      <refnamediv>
+	<refname id="ne_session_proxy">ne_session_proxy</refname>
+	<refname id="ne_session_socks_proxy">ne_session_socks_proxy</refname>
+	<refname id="ne_session_system_proxy">ne_session_system_proxy</refname>
+	<refname id="ne_set_addrlist">ne_set_addrlist</refname>
+	<refpurpose>configure proxy servers</refpurpose>
+      </refnamediv>
+      
+      <refsynopsisdiv>
+	
+	<funcsynopsis>
+	  <funcsynopsisinfo>#include &lt;ne_session.h&gt;</funcsynopsisinfo>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_session_proxy</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	    <paramdef>const char *<parameter>hostname</parameter></paramdef>
+	    <paramdef>unsigned int <parameter>port</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_session_system_proxy</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	    <paramdef>unsigned int <parameter>flags</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_session_socks_proxy</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	    <paramdef>enum ne_sock_sversion <parameter>version</parameter></paramdef>
+	    <paramdef>const char *<parameter>hostname</parameter></paramdef>
+	    <paramdef>unsigned int <parameter>port</parameter></paramdef>
+	    <paramdef>const char *<parameter>username</parameter></paramdef>
+	    <paramdef>const char *<parameter>password</parameter></paramdef>
+	  </funcprototype>
+
+	  <funcprototype>
+	    <funcdef>void <function>ne_set_addrlist</function></funcdef>
+	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
+	    <paramdef>const ne_inet_addr **<parameter>addrlist</parameter></paramdef>
+	    <paramdef>size_t <parameter>count</parameter></paramdef>
+	  </funcprototype>
+
+	</funcsynopsis>
+      </refsynopsisdiv>
+
+      <refsect1>
+	<title>Description</title>
+
+	<para>One (and no more than one) of the functions
+	<function>ne_session_proxy</function>,
+	<function>ne_session_system_proxy</function>,
+	<function>ne_session_socks_proxy</function>,
+	<function>ne_set_addrlist</function> can be used to configure
+	a proxy server for a given session object.  If more than one
+	function is invoked for any given session object, only the
+	last call has effect.  If one of the functions is to be used,
+	it must be used before the creation of any request object for
+	the session.</para>
+        
+        <refsect2>
+          <title>HTTP proxy specification</title>
+          
+          <para>The <function>ne_session_proxy</function> function
+          configures use of an HTTP proxy server for the session, the
+          location of which is given by the
+          <parameter>hostname</parameter> and
+          <parameter>port</parameter> paramters.  If the proxy
+          requires authentication, <xref linkend="ne_set_proxy_auth"/>
+          should be used.</para>
+        </refsect2>
+          
+        <refsect2>
+          <title>System proxy configuration</title>
+          
+          <para>The <function>ne_session_system_proxy</function>
+          function configures the session to use any proxy servers
+          specified by the system configuration.  Support for this
+          function is platform-specific; if unsupported, the function
+          has no effect.</para>
+        </refsect2>
+
+        <refsect2>
+          <title>SOCKS proxy configuration</title>
+          
+          <para>The <function>ne_session_socks_proxy</function>
+          function configures the session to use a SOCKS proxy.  The
+          <parameter>version</parameter> indicates which version of
+          the SOCKS protocol should be used.  The
+          <parameter>hostname</parameter> and
+          <parameter>port</parameter> parameters specify the SOCKS
+          proxy location.  Note that a server with only an IPv6
+          address cannot be used with SOCKS v4 or v4A.  The
+          interpretation of the other arguments depends on the version
+          specified:</para>
+          
+          <variablelist>
+            <varlistentry><term><constant>NE_SOCK_SOCKSV4</constant> (version 4)</term>
+	    <listitem>
+	      <simpara>The <parameter>username</parameter> parameter
+	       must be non-&null;; the <parameter>password</parameter>
+	       parameter is ignored.</simpara>
+	    </listitem>
+            </varlistentry>
+
+            <varlistentry><term><constant>NE_SOCK_SOCKSV4A</constant> (version 4A)</term>
+	    <listitem>
+	      <simpara>The <parameter>username</parameter> parameter
+	      must be non-&null;; the <parameter>password</parameter>
+	      parameter is ignored.</simpara>
+	    </listitem>
+            </varlistentry>
+
+            <varlistentry><term><constant>NE_SOCK_SOCKSV5</constant> (version 5)</term>
+	    <listitem>
+	      <simpara>The <parameter>username</parameter> parameter
+	      may be &null;; if it is non-&null;,
+	      the <parameter>password</parameter> parameter must also
+	      be non-&null;; otherwise, it is ignored..</simpara>
+	    </listitem>
+            </varlistentry>
+          </variablelist>
+
+        </refsect2>
+
+        <refsect2>
+          <title>Origin server address override</title>
+          
+          <para>The <function>ne_set_addrlist</function> function
+          forces use of an address and port the a specified list when
+          establishing a TCP connection, ignoring the "real" hostname
+          and port identifying the origin server for the session (as
+          passed to <function>ne_session_create</function>).  The
+          origin server's "real" hostname and port will still be used
+          in the <literal>Host</literal> header in HTTP requests.
+          When a connection is required, the library will iterate
+          through the <parameter>addrlist</parameter> list, attempting
+          to connect to the address <parameter>addrlist[0]</parameter>
+          through to <parameter>addrlist[count-1]</parameter> in turn,
+          until a connection can be established.</para>
+
+        </refsect2>
+
+      </refsect1>
+
+      <refsect1>
+	<title>Return Values</title>
+	<para>None of the functions described here has a return
+	value.</para>
+      </refsect1>
+
+      <refsect1>
+	<title>Examples</title>
+	<para>Create and destroy a session:</para>
+	<programlisting>ne_session *sess;
+sess = ne_session_create("http", "host.example.com", 80);
+ne_session_proxy(sess, "proxy.example.com", 3128);
+/* ... use sess ... */
+ne_session_destroy(sess);
+</programlisting>
+      </refsect1>
+
+      <refsect1>
+	<title>See Also</title>
+
+	<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_trust_cert"/>, <xref linkend="ne_sock_init"/>, <xref linkend="ne_set_session_flag"/></para>
+      </refsect1>
+
+    </refentry>
diff --git a/doc/ref/req.xml b/doc/ref/req.xml
index cfcd456..b2d754d 100644
--- a/doc/ref/req.xml
+++ b/doc/ref/req.xml
@@ -41,14 +41,14 @@
       <refsect1>
 	<title>Description</title>
 
-	<para>An HTTP request, represented by the
-<type>ne_request</type> type, specifies that some operation is to be
-performed on some resource.  The
-<function>ne_request_create</function> function creates a request
-object, specifying the operation in the <parameter>method</parameter>
-parameter. The location of the resource is determined by the server in
-use for the session given by the <parameter>sess</parameter>
-parameter, combined with the <parameter>path</parameter> parameter.</para>
+	<para>The <type>ne_request</type> object represents an HTTP
+        request and the associated response.
+        The <function>ne_request_create</function> function creates a
+        new request object for the
+        given <parameter>session</parameter>.  The target resource for
+        the request is identified by the <parameter>path</parameter>,
+        and the method to be performed on that resource via
+        the <parameter>method</parameter> parameter.</para>
 
 <para>The <parameter>path</parameter> string used must conform to the
 <literal>abs_path</literal> definition given in RFC2396, with an
diff --git a/doc/ref/sess.xml b/doc/ref/sess.xml
index 8c407ab..8ff6358 100644
--- a/doc/ref/sess.xml
+++ b/doc/ref/sess.xml
@@ -8,7 +8,6 @@
       <refnamediv>
 	<refname id="ne_session_create">ne_session_create</refname>
 	<refname id="ne_close_connection">ne_close_connection</refname>
-	<refname id="ne_session_proxy">ne_session_proxy</refname>
 	<refname id="ne_session_destroy">ne_session_destroy</refname>
 	<refpurpose>set up HTTP sessions</refpurpose>
       </refnamediv>
@@ -25,13 +24,6 @@
 	  </funcprototype>
 
 	  <funcprototype>
-	    <funcdef>void <function>ne_session_proxy</function></funcdef>
-	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
-	    <paramdef>const char *<parameter>hostname</parameter></paramdef>
-	    <paramdef>unsigned int <parameter>port</parameter></paramdef>
-	  </funcprototype>
-
-	  <funcprototype>
 	    <funcdef>void <function>ne_close_connection</function></funcdef>
 	    <paramdef>ne_session *<parameter>session</parameter></paramdef>
 	  </funcprototype>
@@ -53,14 +45,15 @@ certain server. Any requests made using the session can use a
 persistent connection, share cached authentication credentials and any
 other common attributes.</para>
 
-	<para>A new HTTP session is created using
-<function>ne_session_create</function>, giving the
-<parameter>hostname</parameter> and <parameter>port</parameter> of the
-server to use, along with the <parameter>scheme</parameter> used to
-contact the server (usually <literal>"http"</literal>).  Before the
-first use of <function>ne_session_create</function> in a process,
-<xref linkend="ne_sock_init"/> must have been called to perform any
-global initialization needed by any libraries used by &neon;.</para>
+	<para>A new HTTP session is created using the
+<function>ne_session_create</function> function; the 
+<parameter>hostname</parameter> and <parameter>port</parameter>
+parameters specify the origin server to use, along with
+the <parameter>scheme</parameter> (usually <literal>"http"</literal>).
+Before the first use of <function>ne_session_create</function> in a
+process, <xref linkend="ne_sock_init"/> must have been called to
+perform any global initialization needed by any libraries used by
+&neon;.</para>
 
 	<para>To enable SSL/TLS for the session, pass the string
 <literal>"https"</literal> as the <parameter>scheme</parameter>
@@ -69,12 +62,12 @@ parameter, and either register a certificate verification function
 certificate (see <xref linkend="ne_ssl_trust_cert"/>, <xref
 linkend="ne_ssl_trust_default_ca"/>).</para>
 
-	<para>If an HTTP proxy server should be used for the session,
-	<function>ne_session_proxy</function> must be called giving
-	the hostname and port on which to contact the proxy.</para>
+	<para>To use a proxy server for the session, it must be
+	configured (see <xref linkend="ne_session_proxy"/>) before any
+	requests are created from session object.</para>
 
         <para>Further per-session options may be changed using the
-        <xref linkend="ne_set_request_flag"/> interface.</para>
+        <xref linkend="ne_set_session_flag"/> interface.</para>
 
 	<para>If it is known that the session will not be used for a
 significant period of time, <function>ne_close_connection</function>
@@ -83,9 +76,12 @@ this function is entirely optional, but it must not be called if there
 is a request active using the session.</para>
 
 	<para>Once a session has been completed,
-<function>ne_session_destroy</function> must be called to destroy the
-resources associated with the session.  Any subsequent use of the
-session pointer produces undefined behaviour.</para>
+	<function>ne_session_destroy</function> must be called to
+	destroy the resources associated with the session.  Any
+	subsequent use of the session pointer produces undefined
+	behaviour.  The session object must not be destroyed until
+	after all associated request objects have been
+	destroyed.</para>
 
       </refsect1>