114 lines
12 KiB
HTML
114 lines
12 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="ref.html" title="neon API reference"><link rel="next" href="refconfig.html" title="neon-config"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">neon</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr></table><hr></div><div class="refentry" title="neon"><a name="refneon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>neon — HTTP and WebDAV client library</p></div><div class="refsect1" title="Description"><a name="id330539"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library. The major
|
||
abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>,
|
||
created by <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP
|
||
<span class="emphasis"><em>request</em></span>, created by <a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>. HTTP authentication is handled
|
||
transparently for server and proxy servers, see <a class="xref" href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also
|
||
included, see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1" title="Conventions"><a name="id330489"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to
|
||
provide a consistent and simple interface; these are documented
|
||
below.</p><div class="refsect2" title="Thread-safeness and global initialization"><a name="id330499"></a><h3>Thread-safeness and global initialization</h3><p>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 <code class="function">getaddrinfo</code> interface, which
|
||
neon supports; some others implement
|
||
<code class="function">gethostbyname</code> using thread-local
|
||
storage.</p><p>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
|
||
libraries neon must be configured using the
|
||
<code class="literal">--enable-threadsafe-ssl</code>; if this is done,
|
||
locking callbacks will be registered by <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>; note that care must be exercised if
|
||
neon is used in conjunction with another library which uses
|
||
OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global
|
||
initialization before use; notably:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The <code class="literal">SIGPIPE</code> signal
|
||
disposition must be set to <span class="emphasis"><em>ignored</em></span> or
|
||
otherwise handled to avoid process termination when writing to a
|
||
socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global
|
||
initialization to load shared lookup
|
||
tables.</li><li class="listitem">The Win32 socket library requires
|
||
initialization before use.</li></ul></div><p>
|
||
|
||
The <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> 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 <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>
|
||
(and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether
|
||
these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary
|
||
to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support
|
||
for internationalization in neon.</p></div><div class="refsect2" title="Asynchronous signal safety"><a name="id330739"></a><h3>Asynchronous signal safety</h3><p>No function in neon is defined to be <span class="quote">“<span class="quote">async-signal safe</span>”</span> -
|
||
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.</p></div><div class="refsect2" title="Functions using global state"><a name="id330755"></a><h3>Functions using global state</h3><p>Any function in neon may modify the
|
||
<code class="literal">errno</code> global variable as a side-effect. Except
|
||
where explicitly documented, the value of <code class="literal">errno</code>
|
||
is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only
|
||
functions which use or modify process-global state in neon are
|
||
as follows:
|
||
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>, <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a>, and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>, as
|
||
described above</li><li class="listitem"><code class="function">ne_debug_init</code> and
|
||
<code class="function">ne_debug</code>, if enabled at compile time; for
|
||
debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for
|
||
installing a process-global callback to be invoked on
|
||
<code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2" title="Namespaces"><a name="id330830"></a><h3>Namespaces</h3><p>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
|
||
<span class="emphasis"><em>namespace prefix</em></span>. An application which
|
||
ensures it uses no names with these prefixes is then guaranteed to
|
||
avoid such collisions.</p><p>The neon library reserves the use of the namespace
|
||
prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>. 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.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></p></td><td>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.</td></tr><tr><td><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and
|
||
dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces
|
||
used by the expat library.</td></tr><tr><td><p><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></p></td><td>Namespaces used by the libxml2 library; a
|
||
relatively small number of symbols are used without these
|
||
prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompres, adler32,
|
||
zlib</span></p></td><td>Namespaces used by the zlib library; a
|
||
relatively small number of symbols are used without these
|
||
prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
|
||
mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI
|
||
library and dependencies thereof; a number of symbols lie
|
||
outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois
|
||
library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy
|
||
library.</td></tr></tbody></table></div></div><div class="refsect2" title="Argument validation"><a name="id330960"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters
|
||
passed to functions conform to the API (for instance, checking
|
||
that pointer arguments are not <code class="literal">NULL</code>). Any use of the neon API
|
||
which is not documented to produce a certain behaviour results is
|
||
said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is
|
||
likely that neon will segfault under these conditions.</p></div><div class="refsect2" title="URI paths, WebDAV metadata"><a name="id330972"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be
|
||
<span class="emphasis"><em>URI-encoded</em></span> 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.</p></div><div class="refsect2" title="User interaction"><a name="id330996"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce
|
||
output on <code class="constant">stdout</code> or
|
||
<code class="constant">stderr</code>; all user interaction is the
|
||
responsibilty of the application.</p></div><div class="refsect2" title="Memory handling"><a name="id331017"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an
|
||
out-of-memory situation; instead, by default, the
|
||
<code class="function">abort</code> function is called to immediately
|
||
terminate the process. An application may register a custom
|
||
function which will be called before <code class="function">abort</code> in
|
||
such a situation; see <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2" title="Callbacks and userdata"><a name="id331045"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a
|
||
<code class="literal">userdata</code> pointer is also used to allow the
|
||
application to associate a context with the callback. The
|
||
userdata is of type <em class="type">void *</em>, allowing any pointer to
|
||
be used.</p></div><div class="refsect2" title="Large File Support"><a name="id331066"></a><h3>Large File Support</h3><p>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
|
||
<code class="literal">off_t</code> type, where LFS support is
|
||
available.</p><p>Some interfaces use the <code class="literal">ne_off_t</code> type,
|
||
which is defined to be either <code class="literal">off_t</code> or
|
||
<code class="literal">off64_t</code> according to whether LFS support is
|
||
detected at build time. neon does not use or require the
|
||
<code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1" title="See also"><a name="id331111"></a><h2>See also</h2><p><a class="xref" href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon API reference </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon-config</td></tr></table></div></body></html>
|