* doc/: Add documentation for _set_*_flag interfaces, misc.

updates to neon(3) main page.


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

8 files changed, 242 insertions, 106 deletions

diff --git a/doc/manual.xml b/doc/manual.xml
index 3641b77..42b575e 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -40,6 +40,7 @@
 <!ENTITY refconfig SYSTEM "ref/config.xml">
 
 <!ENTITY refsess SYSTEM "ref/sess.xml">
+<!ENTITY refsessflags SYSTEM "ref/sessflags.xml">
 <!ENTITY referr SYSTEM "ref/err.xml">
 <!ENTITY refopts SYSTEM "ref/opts.xml">
 <!ENTITY refsslvfy SYSTEM "ref/sslvfy.xml">
@@ -51,7 +52,7 @@
 <!ENTITY refreq SYSTEM "ref/req.xml">
 <!ENTITY refreqhdr SYSTEM "ref/reqhdr.xml">
 <!ENTITY refresphdr SYSTEM "ref/resphdr.xml">
-<!ENTITY refreqopts SYSTEM "ref/reqopts.xml">
+<!ENTITY refreqflags SYSTEM "ref/reqflags.xml">
 <!ENTITY refstatus SYSTEM "ref/status.xml">
 <!ENTITY refgetst SYSTEM "ref/getst.xml">
 <!ENTITY refreqbody SYSTEM "ref/reqbody.xml">
@@ -172,11 +173,12 @@ ignoring the WebDAV support if desired.</para>
     &refiaddr; <!-- ne_iaddr_make -->
     &refalloc; <!-- ne_malloc -->
     &refsess; <!-- ne_session_create -->
+    &refsessflags; <!-- ne_set_session_flag -->
     &refreq; <!-- ne_request_create -->
     &refreqhdr; <!-- ne_add_request_header -->
     &refresphdr; <!-- ne_add_request_header -->
     &refopts; <!-- ne_set_useragent -->
-    &refreqopts; <!-- ne_set_useragent -->
+    &refreqflags; <!-- ne_set_request_flag -->
     &refreqbody; <!-- ne_set_request_body_buffer -->
     &refauth; <!-- ne_set_server_auth -->
     &refshave; <!-- ne_shave -->
diff --git a/doc/ref/neon.xml b/doc/ref/neon.xml
index dcc61bc..1f20f53 100644
--- a/doc/ref/neon.xml
+++ b/doc/ref/neon.xml
@@ -55,14 +55,13 @@
 
     <itemizedlist>
       <listitem><simpara>The <literal>SIGPIPE</literal> signal
-      disposition must be set to
-      <emphasis>ignored</emphasis>.</simpara></listitem>
+      disposition must be set to <emphasis>ignored</emphasis> or
+      otherwise handled to avoid process termination when writing to a
+      socket which has been shutdown by the peer.</simpara></listitem>
 
-      <listitem><simpara>OpenSSL requires global initialization to
-      load shared lookup tables.</simpara></listitem>
-
-      <listitem><simpara>The SOCKS library requires initialization
-      before use.</simpara></listitem>
+      <listitem><simpara>OpenSSL and GnuTLSrequire global
+      initialization to load shared lookup
+      tables.</simpara></listitem>
 
       <listitem><simpara>The Win32 socket library requires
       initialization before use.</simpara></listitem>
@@ -70,11 +69,15 @@
 
     The <xref linkend="ne_sock_init"/> function should be called
     before any other use of &neon; to perform any necessary
-    initialization needed for the particular platform.</para>
+    initialization needed for the particular platform.  Applications
+    wishing to perform all the necessary process-global initialization
+    steps themselves may omit to call <xref linkend="ne_sock_init"/>
+    (and <xref linkend="ne_sock_exit"/>); &neon; neither checks whether
+    these functions are called nor calls them itself.</para>
 
-    <para>For some applications it may be necessary to call <xref
-    linkend="ne_i18n_init"/> to initialize the internationalization
-    support in &neon;.</para>
+    <para>For some applications and configurations it may be necessary
+    to call <xref linkend="ne_i18n_init"/> to initialize the support
+    for internationalization in &neon;.</para>
 
   </refsect2>
 
@@ -142,7 +145,7 @@
         <term>gnutls_, gcry_, gpg_</term>
         <listitem><simpara>Namespaces used by the GnuTLS library (and
         dependencies thereof)</simpara></listitem>
-      </varlistentry>        
+      </varlistentry>
 
       <varlistentry>
 	<term>XML_, Xml[A-Z]</term> <listitem><simpara>Namespaces
@@ -232,6 +235,24 @@
 
   </refsect2>
 
+  <refsect2>
+    <title>Large File Support</title>
+
+    <para>Since version 0.27.0, &neon; transparently uses the "LFS
+    transitional" interfaces in places where file-backed file
+    descriptors are manipulated.  This means files larger than 2GiB
+    can be handled on platforms with a native 32-bit
+    <literal>off_t</literal> type, where LFS support is
+    available.</para>
+
+    <para>Some interfaces use the <literal>ne_off_t</literal> type,
+    which is defined to be either <literal>off_t</literal> or
+    <literal>off64_t</literal> according to whether LFS support is
+    detected at build time.  &neon; does use or require the
+    <literal>-D_FILE_OFFSET_BITS=64</literal> macro definition.</para>
+
+  </refsect2>
+
   </refsect1>
 
   <refsect1>
diff --git a/doc/ref/req.xml b/doc/ref/req.xml
index 0dfcd9a..cfcd456 100644
--- a/doc/ref/req.xml
+++ b/doc/ref/req.xml
@@ -80,12 +80,18 @@ result of the operation, <xref linkend="ne_get_status"/>, along with
 any processing of the response headers and message body.</para>
 
 	<para>A request can only be dispatched once: calling
-<function>ne_request_dispatch</function> more than once on a single
-<type>ne_request</type> object produces undefined behaviour.  Once all
-processing associated with the request object is complete, use the
-<function>ne_request_destroy</function> function to destroy the
-resources associated with it.  Any subsequent use of the request
-object produces undefined behaviour.</para>
+	<function>ne_request_dispatch</function> more than once on a
+	single <type>ne_request</type> object produces undefined
+	behaviour.  Once all processing associated with the request
+	object is complete, use the
+	<function>ne_request_destroy</function> function to destroy
+        the resources associated with it.  Any subsequent use of the
+	request object produces undefined behaviour.</para>
+
+        <para>If a request is being using a non-idempotent method such
+        as <literal>POST</literal>, the
+        <literal>NE_REQFLAG_IDEMPOTENT</literal> flag should be
+        disabled; see <xref linkend="ne_set_request_flag"/>.</para>
 
       </refsect1>
 
@@ -162,7 +168,7 @@ ne_request_destroy(req);</programlisting>
 	<para><xref linkend="ne_get_error"/>, <xref
 linkend="ne_set_error"/>, <xref linkend="ne_get_status"/>, <xref
 linkend="ne_add_request_header"/>, <xref
-linkend="ne_set_request_body_buffer"/>.</para>
+linkend="ne_set_request_body_buffer"/>, <xref linkend="ne_set_request_flag"/>.</para>
 
       </refsect1>
 
diff --git a/doc/ref/reqbody.xml b/doc/ref/reqbody.xml
index 58f307e..9249c31 100644
--- a/doc/ref/reqbody.xml
+++ b/doc/ref/reqbody.xml
@@ -33,14 +33,6 @@
 	    <paramdef>off_t <parameter>length</parameter></paramdef>
 	  </funcprototype>
 
-	  <funcprototype>
-	    <funcdef>int <function>ne_set_request_body_fd64</function></funcdef>
-	    <paramdef>ne_request *<parameter>req</parameter></paramdef>
-	    <paramdef>int <parameter>fd</parameter></paramdef>
-	    <paramdef>off64_t <parameter>begin</parameter></paramdef>
-	    <paramdef>off64_t <parameter>length</parameter></paramdef>
-	  </funcprototype>
-
 	</funcsynopsis>
 	
       </refsynopsisdiv>
@@ -62,25 +54,12 @@ bytes are read, beginning at offset <parameter>begin</parameter>
 (hence, passing <parameter>begin</parameter> as zero means the body is read
 from the beginning of the file).</para>
 
-	<para>If the <literal>NE_LFS</literal> macro is defined, then
-	the <function>ne_set_request_body_fd64</function> function is
-	also available, to provide large file support.  This function
-	can be used on 32-bit platforms supporting the LFS standard;
-	the <parameter>offset</parameter> and
-	<parameter>length</parameter> parameters can then be passed as
-	64-bit values.  When using large files,
-	<parameter>fd</parameter> must be opened using
-	<function>open64</function> or by passing the
-	<literal>O_LARGEFILE</literal> flag to
-	<function>open</function>.</para>
-
         <para>For all the above functions, the source of the request
         body must survive until the request has been dispatched;
         neither the memory buffer passed to
         <function>ne_set_request_body_buffer</function> nor the file
         descriptor passed to
-        <function>ne_set_request_body_fd</function> or
-        <function>ne_set_request_body_fd64</function> are copied
+        <function>ne_set_request_body_fd</function> are copied
         internally.</para>
 
       </refsect1>
diff --git a/doc/ref/reqflags.xml b/doc/ref/reqflags.xml
new file mode 100644
index 0000000..9ac698a
--- /dev/null
+++ b/doc/ref/reqflags.xml
@@ -0,0 +1,81 @@
+<refentry id="refreqflags">
+
+  <refmeta>
+    <refentrytitle>ne_set_request_flag</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_set_request_flag">ne_set_request_flag</refname>
+    <refname id="ne_get_request_flag">ne_get_request_flag</refname>
+    <refpurpose>set and retrieve per-request flags</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_request.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>void <function>ne_set_request_flag</function></funcdef>
+        <paramdef>ne_request *<parameter>req</parameter></paramdef>
+        <paramdef>ne_request_flag <parameter>flag</parameter></paramdef>
+        <paramdef>int <parameter>value</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>ne_get_request_flag</function></funcdef>
+        <paramdef>ne_request *<parameter>req</parameter></paramdef>
+        <paramdef>ne_request_flag <parameter>flag</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <function>ne_set_request_flag</function> function
+    enables or disables a per-request flag.  Passing a non-zero
+    <parameter>value</parameter> argument enables the flag, and zero
+    disables it.</para>
+
+    <para>The following flags are defined:</para>
+
+	<variablelist>
+	  <varlistentry>
+            <term><constant>NE_REQFLAG_EXPECT100</constant></term>
+	    <listitem>
+	      <simpara>enables this flag to use the "Expect:
+	      100-continue" feature of HTTP/1.1</simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_REQFLAG_IDEMPOTENT</constant></term>
+	    <listitem>
+	      <simpara>disable this flag if the request uses a
+	      non-idempotent method such as
+	      <literal>POST</literal></simpara>
+	    </listitem>
+	  </varlistentry>
+        </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Return value</title>
+
+    <para>The <function>ne_get_request_flag</function> function returns
+    zero if a flag is disabled, less than zero if the flag is not
+    supported, or greater than zero if the flag is enabled.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+    <para><xref linkend="ne_request_create"/>.</para>
+
+  </refsect1>
+
+</refentry>
diff --git a/doc/ref/reqopts.xml b/doc/ref/reqopts.xml
deleted file mode 100644
index bb4ca4a..0000000
--- a/doc/ref/reqopts.xml
+++ /dev/null
@@ -1,60 +0,0 @@
-<refentry id="refreqopts">
-
-  <refmeta>
-    <refentrytitle>ne_set_request_expect100</refentrytitle>
-    <manvolnum>3</manvolnum>
-  </refmeta>
-
-  <refnamediv>
-    <refname id="ne_set_request_expect100">ne_set_request_expect100</refname>
-    <refpurpose>function to enable Expect: 100-continue support</refpurpose>
-  </refnamediv>
-  
-  <refsynopsisdiv>
-
-    <funcsynopsis>
-
-      <funcsynopsisinfo>#include &lt;ne_request.h&gt;</funcsynopsisinfo>
-
-      <funcprototype>
-        <funcdef>void <function>ne_set_request_expect100</function></funcdef>
-        <paramdef>ne_request *<parameter>request</parameter></paramdef>
-        <paramdef>int <parameter>flag</parameter></paramdef>
-      </funcprototype>
-
-    </funcsynopsis>
-
-  </refsynopsisdiv>
-
-  <refsect1>
-    <title>Description</title>
-
-    <para>An extension introduced in the HTTP/1.1 specification was
-    the use of the <literal>Expect: 100-continue</literal> header.
-    This header allows an HTTP client to be informed of the expected
-    response status before the request message body is sent: a useful
-    optimisation for situations where a large message body is to be
-    sent.  The <function>ne_set_request_expect100</function> function
-    can be used to enable this feature by passing the
-    <parameter>flag</parameter> parameter as any non-zero
-    integer.</para>
-
-    <warning><para>Unfortunately, if this header is sent to a server
-    which is not fully compliant with the HTTP/1.1 specification, a
-    deadlock occurs resulting in a temporarily "hung" connection.
-    neon will recover gracefully from this situation, but only after a
-    15 second timeout.  It is highly recommended that this option is
-    not enabled unless it is known that the server in use correctly
-    implements <literal>Expect: 100-continue</literal>
-    support.</para></warning>
-
-  </refsect1>
-
-  <refsect1>
-    <title>See also</title>
-
-    <para><xref linkend="ne_request_create"/>.</para>
-
-  </refsect1>
-
-</refentry>
diff --git a/doc/ref/sess.xml b/doc/ref/sess.xml
index 93f0038..8c407ab 100644
--- a/doc/ref/sess.xml
+++ b/doc/ref/sess.xml
@@ -70,8 +70,11 @@ 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>
+	<function>ne_session_proxy</function> must be called giving
+	the hostname and port on which to contact the proxy.</para>
+
+        <para>Further per-session options may be changed using the
+        <xref linkend="ne_set_request_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>
@@ -117,7 +120,7 @@ ne_session_destroy(sess);
       <refsect1>
 	<title>See Also</title>
 
-	<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_trust_cert"/>, <xref linkend="ne_sock_init"/></para>
+	<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/sessflags.xml b/doc/ref/sessflags.xml
new file mode 100644
index 0000000..0b8cf3f
--- /dev/null
+++ b/doc/ref/sessflags.xml
@@ -0,0 +1,104 @@
+<refentry id="refsessflags">
+
+  <refmeta>
+    <refentrytitle>ne_set_session_flag</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_set_session_flag">ne_set_session_flag</refname>
+    <refname id="ne_get_session_flag">ne_get_session_flag</refname>
+    <refpurpose>set and retrieve session flags</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_request.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>void <function>ne_set_session_flag</function></funcdef>
+        <paramdef>ne_session *<parameter>sess</parameter></paramdef>
+        <paramdef>ne_session_flag <parameter>flag</parameter></paramdef>
+        <paramdef>int <parameter>value</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>int <function>ne_get_session_flag</function></funcdef>
+        <paramdef>ne_session *<parameter>sess</parameter></paramdef>
+        <paramdef>ne_session_flag <parameter>flag</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>The <function>ne_set_session_flag</function> function
+    enables or disables a session flag.  Passing a non-zero
+    <parameter>value</parameter> argument enables the flag, and zero
+    disables it.</para>
+
+    <para>The following flags are defined:</para>
+
+	<variablelist>
+	  <varlistentry>
+            <term><constant>NE_SESSFLAG_PERSIST</constant></term>
+	    <listitem>
+	      <simpara>disable this flag to prevent use of persistent
+	      connections</simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_SESSFLAG_ICYPROTO</constant></term>
+	    <listitem>
+	      <simpara>enable this flag to enable support for non-HTTP
+	      ShoutCast-style "ICY" responses</simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_SESSFLAG_SSLv2</constant></term>
+	    <listitem>
+	      <simpara>disable this flag to disable support for the SSLv2
+	      protocol</simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_SESSFLAG_RFC4918</constant></term>
+	    <listitem>
+	      <simpara>enable this flag to enable support for
+	      RFC4918-only WebDAV features; losing
+	      backwards-compatibility with RFC2518 servers</simpara>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+            <term><constant>NE_SESSFLAG_CONNAUTH</constant></term>
+	    <listitem>
+	      <simpara>enable this flag if an RFC-violating
+	      connection-based HTTP authentication scheme is in
+	      use</simpara>
+	    </listitem>
+	  </varlistentry>
+
+        </variablelist>
+  </refsect1>
+
+  <refsect1>
+    <title>Return value</title>
+
+    <para>The <function>ne_get_session_flag</function> function
+    returns zero if a flag is disabled, less than zero if the flag is
+    not supported, or greater than zero if the flag is enabled.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+    <para><xref linkend="ne_session_create"/>.</para>
+
+  </refsect1>
+
+</refentry>