1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
<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.72.0"><link rel="start" 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" lang="en"><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" lang="en"><a name="id2585579"></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 href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP
<span class="emphasis"><em>request</em></span>, created by <a href="refreq.html#ne_request_create">ne_request_create</a>. HTTP authentication is handled
transparently for server and proxy servers, see <a href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also
included, see <a href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1" lang="en"><a name="id2586256"></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" lang="en"><a name="id2586267"></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 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 type="disc"><li>The <code class="literal">SIGPIPE</code> signal
disposition must be set to
<span class="emphasis"><em>ignored</em></span>.</li><li>OpenSSL requires global initialization to
load shared lookup tables.</li><li>The SOCKS library requires initialization
before use.</li><li>The Win32 socket library requires
initialization before use.</li></ul></div><p>
The <a 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.</p><p>For some applications it may be necessary to call <a href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the internationalization
support in neon.</p></div><div class="refsect2" lang="en"><a name="id2586376"></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><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></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><span class="term">XML_, Xml[A-Z]</span></td><td>Namespaces
used by the expat library.</td></tr><tr><td><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></td><td>Namespaces used by the libxml2 library; a
relatively small number of symbols are used without these
prefixes.</td></tr></tbody></table></div></div><div class="refsect2" lang="en"><a name="id2586461"></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" lang="en"><a name="id2586477"></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" lang="en"><a name="id2586506"></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" lang="en"><a name="id2586529"></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 href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2" lang="en"><a name="id2586561"></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><div class="refsect1" lang="en"><a name="id2586583"></a><h2>See also</h2><p><a href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a 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>
|
