183 lines
6.2 KiB
XML
183 lines
6.2 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 the OpenSSL library, the
|
|
application must register some locking callbacks in accordance
|
|
with the <ulink
|
|
url="http://www.openssl.org/docs/crypto/threads.html">OpenSSL
|
|
documentation</ulink>.</para>
|
|
|
|
<para>Some platforms and libraries used by &neon; require global
|
|
initialization before use; notably:
|
|
|
|
<itemizedlist>
|
|
<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>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.</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>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>
|
|
|
|
</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>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See also</title>
|
|
|
|
<para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|