288 lines
10 KiB
XML
288 lines
10 KiB
XML
<refentry id="refneon">
|
|
|
|
<refmeta>
|
|
<refentrytitle>neon</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>neon</refname>
|
|
<refpurpose>HTTP and WebDAV client library</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1>
|
|
<title>Description</title>
|
|
|
|
<para>neon is an HTTP and WebDAV client library. The major
|
|
abstractions exposed are the HTTP <emphasis>session</emphasis>,
|
|
created by <xref linkend="ne_session_create"/>; and the HTTP
|
|
<emphasis>request</emphasis>, created by <xref
|
|
linkend="ne_request_create"/>. HTTP authentication is handled
|
|
transparently for server and proxy servers, see <xref
|
|
linkend="ne_set_server_auth"/>; complete SSL/TLS support is also
|
|
included, see <xref linkend="ne_ssl_set_verify"/>.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Conventions</title>
|
|
|
|
<para>Some conventions are used throughout the neon API, to
|
|
provide a consistent and simple interface; these are documented
|
|
below.</para>
|
|
|
|
<refsect2>
|
|
<title>Thread-safeness and global initialization</title>
|
|
|
|
<para>&neon; itself is implemented to be thread-safe (avoiding any
|
|
use of global state), but relies on the operating system providing
|
|
a thread-safe resolver interface. Modern operating systems offer
|
|
the thread-safe <function>getaddrinfo</function> interface, which
|
|
&neon; supports; some others implement
|
|
<function>gethostbyname</function> using thread-local
|
|
storage.</para>
|
|
|
|
<para>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
|
|
libraries &neon; must be configured using the
|
|
<literal>--enable-threadsafe-ssl</literal>; if this is done,
|
|
locking callbacks will be registered by <xref
|
|
linkend="ne_sock_init"/>; note that care must be exercised if
|
|
&neon; is used in conjunction with another library which uses
|
|
OpenSSL or GnuTLS.</para>
|
|
|
|
<para>Some platforms and libraries used by &neon; require global
|
|
initialization before use; notably:
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara>The <literal>SIGPIPE</literal> signal
|
|
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 and GnuTLS require global
|
|
initialization to load shared lookup
|
|
tables.</simpara></listitem>
|
|
|
|
<listitem><simpara>The Win32 socket library requires
|
|
initialization before use.</simpara></listitem>
|
|
</itemizedlist>
|
|
|
|
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. 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 and configurations it may be necessary
|
|
to call <xref linkend="ne_i18n_init"/> to initialize the support
|
|
for internationalization in &neon;.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Asynchronous signal safety</title>
|
|
|
|
<para>No function in &neon; is defined to be <quote>async-signal safe</quote> -
|
|
that is, no function is safe to call from a signal handler. Any
|
|
call into the &neon; library from a signal handler will have
|
|
undefined behaviour - in other words, it may crash the
|
|
process.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Functions using global state</title>
|
|
|
|
<para>Any function in &neon; may modify the
|
|
<literal>errno</literal> global variable as a side-effect. Except
|
|
where explicitly documented, the value of <literal>errno</literal>
|
|
is unspecified after any &neon; function call.</para>
|
|
|
|
<para>Other than in the use of <literal>errno</literal>, the only
|
|
functions which use or modify process-global state in &neon; are
|
|
as follows:
|
|
|
|
<itemizedlist>
|
|
<listitem><simpara><xref linkend="ne_sock_init"/>, <xref
|
|
linkend="ne_i18n_init"/>, and <xref linkend="ne_sock_exit"/>, as
|
|
described above</simpara></listitem>
|
|
|
|
<listitem><simpara><function>ne_debug_init</function> and
|
|
<function>ne_debug</function>, if enabled at compile time; for
|
|
debugging output</simpara></listitem>
|
|
|
|
<listitem><simpara><xref linkend="ne_oom_callback"/> for
|
|
installing a process-global callback to be invoked on
|
|
<function>malloc</function> failure</simpara></listitem>
|
|
|
|
</itemizedlist></para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Namespaces</title>
|
|
|
|
<para>To avoid possible collisions between names used for symbols
|
|
and preprocessor macros by an application and the libraries it
|
|
uses, it is good practice for each library to reserve a particular
|
|
<emphasis>namespace prefix</emphasis>. An application which
|
|
ensures it uses no names with these prefixes is then guaranteed to
|
|
avoid such collisions.</para>
|
|
|
|
<para>The &neon; library reserves the use of the namespace
|
|
prefixes <literal>ne_</literal> and <literal>NE_</literal>. The
|
|
libraries used by &neon; may also reserve certain namespaces;
|
|
collisions between these libraries and a &neon;-based application
|
|
will not be detected at compile time, since the underlying library
|
|
interfaces are not exposed through the &neon; header files. Such
|
|
collisions can only be detected at link time, when the linker
|
|
attempts to resolve symbols. The following list documents some of
|
|
the namespaces claimed by libraries used by &neon;; this list may
|
|
be incomplete.</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</term>
|
|
<listitem><simpara>Some of the many prefixes used by the OpenSSL
|
|
library; little attempt has been made to keep exported symbols
|
|
within any particular prefixes for this
|
|
library.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>gnutls_, gcry_, gpg_</term>
|
|
<listitem><simpara>Namespaces used by the GnuTLS library (and
|
|
dependencies thereof)</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>XML_, Xml[A-Z]</term> <listitem><simpara>Namespaces
|
|
used by the expat library.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>xml[A-Z], html[A-Z], docb[A-Z]</term>
|
|
<listitem><simpara>Namespaces used by the libxml2 library; a
|
|
relatively small number of symbols are used without these
|
|
prefixes.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>inflate, deflate, crc32, compress, uncompres, adler32,
|
|
zlib</term>
|
|
<listitem><simpara>Namespaces used by the zlib library; a
|
|
relatively small number of symbols are used without these
|
|
prefixes.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
|
|
mit</term>
|
|
|
|
<listitem><simpara>Some of the prefixes used by the MIT GSSAPI
|
|
library and dependencies thereof; a number of symbols lie
|
|
outside these prefixes.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>pakchois_</term>
|
|
<listitem><simpara>Namespace used by the pakchois
|
|
library.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>px_</term>
|
|
<listitem><simpara>Namespace used by the libproxy
|
|
library.</simpara></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Argument validation</title>
|
|
|
|
<para>&neon; does not attempt to validate that the parameters
|
|
passed to functions conform to the API (for instance, checking
|
|
that pointer arguments are not &null;). Any use of the &neon; API
|
|
which is not documented to produce a certain behaviour results is
|
|
said to produce <emphasis>undefined behaviour</emphasis>; it is
|
|
likely that &neon; will segfault under these conditions.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>URI paths, WebDAV metadata</title>
|
|
|
|
<para>The path strings passed to any function must be
|
|
<emphasis>URI-encoded</emphasis> by the application; &neon; never
|
|
performs any URI encoding or decoding internally. WebDAV property
|
|
names and values must be valid UTF-8 encoded Unicode
|
|
strings.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>User interaction</title>
|
|
|
|
<para>As a pure library interface, &neon; will never produce
|
|
output on <constant>stdout</constant> or
|
|
<constant>stderr</constant>; all user interaction is the
|
|
responsibilty of the application.</para>
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Memory handling</title>
|
|
|
|
<para>neon does not attempt to cope gracefully with an
|
|
out-of-memory situation; instead, by default, the
|
|
<function>abort</function> function is called to immediately
|
|
terminate the process. An application may register a custom
|
|
function which will be called before <function>abort</function> in
|
|
such a situation; see <xref linkend="ne_oom_callback"/>.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2>
|
|
<title>Callbacks and userdata</title>
|
|
|
|
<para>Whenever a callback is registered, a
|
|
<literal>userdata</literal> pointer is also used to allow the
|
|
application to associate a context with the callback. The
|
|
userdata is of type <type>void *</type>, allowing any pointer to
|
|
be used.</para>
|
|
|
|
</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 not use or require the
|
|
<literal>-D_FILE_OFFSET_BITS=64</literal> macro definition.</para>
|
|
|
|
</refsect2>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|