| 1 |
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon</title><link rel="stylesheet" type="text/css" href="../manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><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="id446181"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library. The major |
| 2 |
abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>, |
| 3 |
created by <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP |
| 4 |
<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 |
| 5 |
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 |
| 6 |
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="id446521"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to |
| 7 |
provide a consistent and simple interface; these are documented |
| 8 |
below.</p><div class="refsect2" title="Thread-safeness and global initialization"><a name="id446602"></a><h3>Thread-safeness and global initialization</h3><p>neon itself is implemented to be thread-safe (avoiding any |
| 9 |
use of global state), but relies on the operating system providing |
| 10 |
a thread-safe resolver interface. Modern operating systems offer |
| 11 |
the thread-safe <code class="function">getaddrinfo</code> interface, which |
| 12 |
neon supports; some others implement |
| 13 |
<code class="function">gethostbyname</code> using thread-local |
| 14 |
storage.</p><p>To allow thread-safe use of SSL in the OpenSSL and GnuTLS |
| 15 |
libraries neon must be configured using the |
| 16 |
<code class="literal">--enable-threadsafe-ssl</code>; if this is done, |
| 17 |
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 |
| 18 |
neon is used in conjunction with another library which uses |
| 19 |
OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global |
| 20 |
initialization before use; notably: |
| 21 |
|
| 22 |
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The <code class="literal">SIGPIPE</code> signal |
| 23 |
disposition must be set to <span class="emphasis"><em>ignored</em></span> or |
| 24 |
otherwise handled to avoid process termination when writing to a |
| 25 |
socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global |
| 26 |
initialization to load shared lookup |
| 27 |
tables.</li><li class="listitem">The Win32 socket library requires |
| 28 |
initialization before use.</li></ul></div><p> |
| 29 |
|
| 30 |
The <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> function should be called |
| 31 |
before any other use of neon to perform any necessary |
| 32 |
initialization needed for the particular platform. Applications |
| 33 |
wishing to perform all the necessary process-global initialization |
| 34 |
steps themselves may omit to call <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> |
| 35 |
(and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether |
| 36 |
these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary |
| 37 |
to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support |
| 38 |
for internationalization in neon.</p></div><div class="refsect2" title="Asynchronous signal safety"><a name="id446695"></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> - |
| 39 |
that is, no function is safe to call from a signal handler. Any |
| 40 |
call into the neon library from a signal handler will have |
| 41 |
undefined behaviour - in other words, it may crash the |
| 42 |
process.</p></div><div class="refsect2" title="Functions using global state"><a name="id446711"></a><h3>Functions using global state</h3><p>Any function in neon may modify the |
| 43 |
<code class="literal">errno</code> global variable as a side-effect. Except |
| 44 |
where explicitly documented, the value of <code class="literal">errno</code> |
| 45 |
is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only |
| 46 |
functions which use or modify process-global state in neon are |
| 47 |
as follows: |
| 48 |
|
| 49 |
</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 |
| 50 |
described above</li><li class="listitem"><code class="function">ne_debug_init</code> and |
| 51 |
<code class="function">ne_debug</code>, if enabled at compile time; for |
| 52 |
debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for |
| 53 |
installing a process-global callback to be invoked on |
| 54 |
<code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2" title="Namespaces"><a name="id446785"></a><h3>Namespaces</h3><p>To avoid possible collisions between names used for symbols |
| 55 |
and preprocessor macros by an application and the libraries it |
| 56 |
uses, it is good practice for each library to reserve a particular |
| 57 |
<span class="emphasis"><em>namespace prefix</em></span>. An application which |
| 58 |
ensures it uses no names with these prefixes is then guaranteed to |
| 59 |
avoid such collisions.</p><p>The neon library reserves the use of the namespace |
| 60 |
prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>. The |
| 61 |
libraries used by neon may also reserve certain namespaces; |
| 62 |
collisions between these libraries and a neon-based application |
| 63 |
will not be detected at compile time, since the underlying library |
| 64 |
interfaces are not exposed through the neon header files. Such |
| 65 |
collisions can only be detected at link time, when the linker |
| 66 |
attempts to resolve symbols. The following list documents some of |
| 67 |
the namespaces claimed by libraries used by neon; this list may |
| 68 |
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 |
| 69 |
library; little attempt has been made to keep exported symbols |
| 70 |
within any particular prefixes for this |
| 71 |
library.</td></tr><tr><td><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and |
| 72 |
dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces |
| 73 |
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 |
| 74 |
relatively small number of symbols are used without these |
| 75 |
prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompres, adler32, |
| 76 |
zlib</span></p></td><td>Namespaces used by the zlib library; a |
| 77 |
relatively small number of symbols are used without these |
| 78 |
prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, |
| 79 |
mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI |
| 80 |
library and dependencies thereof; a number of symbols lie |
| 81 |
outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois |
| 82 |
library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy |
| 83 |
library.</td></tr></tbody></table></div></div><div class="refsect2" title="Argument validation"><a name="id446915"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters |
| 84 |
passed to functions conform to the API (for instance, checking |
| 85 |
that pointer arguments are not <code class="literal">NULL</code>). Any use of the neon API |
| 86 |
which is not documented to produce a certain behaviour results is |
| 87 |
said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is |
| 88 |
likely that neon will segfault under these conditions.</p></div><div class="refsect2" title="URI paths, WebDAV metadata"><a name="id446928"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be |
| 89 |
<span class="emphasis"><em>URI-encoded</em></span> by the application; neon never |
| 90 |
performs any URI encoding or decoding internally. WebDAV property |
| 91 |
names and values must be valid UTF-8 encoded Unicode |
| 92 |
strings.</p></div><div class="refsect2" title="User interaction"><a name="id446952"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce |
| 93 |
output on <code class="constant">stdout</code> or |
| 94 |
<code class="constant">stderr</code>; all user interaction is the |
| 95 |
responsibilty of the application.</p></div><div class="refsect2" title="Memory handling"><a name="id446973"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an |
| 96 |
out-of-memory situation; instead, by default, the |
| 97 |
<code class="function">abort</code> function is called to immediately |
| 98 |
terminate the process. An application may register a custom |
| 99 |
function which will be called before <code class="function">abort</code> in |
| 100 |
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="id447001"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a |
| 101 |
<code class="literal">userdata</code> pointer is also used to allow the |
| 102 |
application to associate a context with the callback. The |
| 103 |
userdata is of type <em class="type">void *</em>, allowing any pointer to |
| 104 |
be used.</p></div><div class="refsect2" title="Large File Support"><a name="id447021"></a><h3>Large File Support</h3><p>Since version 0.27.0, neon transparently uses the "LFS |
| 105 |
transitional" interfaces in places where file-backed file |
| 106 |
descriptors are manipulated. This means files larger than 2GiB |
| 107 |
can be handled on platforms with a native 32-bit |
| 108 |
<code class="literal">off_t</code> type, where LFS support is |
| 109 |
available.</p><p>Some interfaces use the <code class="literal">ne_off_t</code> type, |
| 110 |
which is defined to be either <code class="literal">off_t</code> or |
| 111 |
<code class="literal">off64_t</code> according to whether LFS support is |
| 112 |
detected at build time. neon does not use or require the |
| 113 |
<code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1" title="See also"><a name="id447067"></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> |