diff options
-rw-r--r-- | doc/manual.xml | 6 | ||||
-rw-r--r-- | doc/ref/neon.xml | 45 | ||||
-rw-r--r-- | doc/ref/req.xml | 20 | ||||
-rw-r--r-- | doc/ref/reqbody.xml | 23 | ||||
-rw-r--r-- | doc/ref/reqflags.xml | 81 | ||||
-rw-r--r-- | doc/ref/reqopts.xml | 60 | ||||
-rw-r--r-- | doc/ref/sess.xml | 9 | ||||
-rw-r--r-- | doc/ref/sessflags.xml | 104 |
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 <ne_request.h></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 <ne_request.h></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 <ne_request.h></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> |