1<refentry id="refneon">
2
3  <refmeta>
4    <refentrytitle>neon</refentrytitle>
5    <manvolnum>3</manvolnum>
6  </refmeta>
7
8  <refnamediv>
9    <refname>neon</refname>
10    <refpurpose>HTTP and WebDAV client library</refpurpose>
11  </refnamediv>
12
13  <refsect1>
14    <title>Description</title>
15
16    <para>neon is an HTTP and WebDAV client library.  The major
17    abstractions exposed are the HTTP <emphasis>session</emphasis>,
18    created by <xref linkend="ne_session_create"/>; and the HTTP
19    <emphasis>request</emphasis>, created by <xref
20    linkend="ne_request_create"/>.  HTTP authentication is handled
21    transparently for server and proxy servers, see <xref
22    linkend="ne_set_server_auth"/>; complete SSL/TLS support is also
23    included, see <xref linkend="ne_ssl_set_verify"/>.</para>
24
25  </refsect1>
26
27  <refsect1>
28    <title>Conventions</title>
29
30    <para>Some conventions are used throughout the neon API, to
31    provide a consistent and simple interface; these are documented
32    below.</para>
33
34  <refsect2>
35    <title>Thread-safeness and global initialization</title>
36
37    <para>&neon; itself is implemented to be thread-safe (avoiding any
38    use of global state), but relies on the operating system providing
39    a thread-safe resolver interface.  Modern operating systems offer
40    the thread-safe <function>getaddrinfo</function> interface, which
41    &neon; supports; some others implement
42    <function>gethostbyname</function> using thread-local
43    storage.</para>
44
45    <para>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
46    libraries &neon; must be configured using the
47    <literal>--enable-threadsafe-ssl</literal>; if this is done,
48    locking callbacks will be registered by <xref
49    linkend="ne_sock_init"/>; note that care must be exercised if
50    &neon; is used in conjunction with another library which uses
51    OpenSSL or GnuTLS.</para>
52
53    <para>Some platforms and libraries used by &neon; require global
54    initialization before use; notably:
55
56    <itemizedlist>
57      <listitem><simpara>The <literal>SIGPIPE</literal> signal
58      disposition must be set to <emphasis>ignored</emphasis> or
59      otherwise handled to avoid process termination when writing to a
60      socket which has been shutdown by the peer.</simpara></listitem>
61
62      <listitem><simpara>OpenSSL and GnuTLS require global
63      initialization to load shared lookup
64      tables.</simpara></listitem>
65
66      <listitem><simpara>The Win32 socket library requires
67      initialization before use.</simpara></listitem>
68    </itemizedlist>
69
70    The <xref linkend="ne_sock_init"/> function should be called
71    before any other use of &neon; to perform any necessary
72    initialization needed for the particular platform.  Applications
73    wishing to perform all the necessary process-global initialization
74    steps themselves may omit to call <xref linkend="ne_sock_init"/>
75    (and <xref linkend="ne_sock_exit"/>); &neon; neither checks whether
76    these functions are called nor calls them itself.</para>
77
78    <para>For some applications and configurations it may be necessary
79    to call <xref linkend="ne_i18n_init"/> to initialize the support
80    for internationalization in &neon;.</para>
81
82  </refsect2>
83
84  <refsect2>
85    <title>Asynchronous signal safety</title>
86    
87    <para>No function in &neon; is defined to be <quote>async-signal safe</quote> -
88    that is, no function is safe to call from a signal handler.  Any
89    call into the &neon; library from a signal handler will have
90    undefined behaviour - in other words, it may crash the
91    process.</para>
92  </refsect2>
93
94  <refsect2>
95    <title>Functions using global state</title>
96
97    <para>Any function in &neon; may modify the
98    <literal>errno</literal> global variable as a side-effect.  Except
99    where explicitly documented, the value of <literal>errno</literal>
100    is unspecified after any &neon; function call.</para>
101
102    <para>Other than in the use of <literal>errno</literal>, the only
103    functions which use or modify process-global state in &neon; are
104    as follows:
105
106    <itemizedlist>
107      <listitem><simpara><xref linkend="ne_sock_init"/>, <xref
108      linkend="ne_i18n_init"/>, and <xref linkend="ne_sock_exit"/>, as
109      described above</simpara></listitem>
110
111      <listitem><simpara><function>ne_debug_init</function> and
112      <function>ne_debug</function>, if enabled at compile time; for
113      debugging output</simpara></listitem>
114
115      <listitem><simpara><xref linkend="ne_oom_callback"/> for
116      installing a process-global callback to be invoked on
117      <function>malloc</function> failure</simpara></listitem>
118
119    </itemizedlist></para>
120
121  </refsect2>      
122
123  <refsect2>
124    <title>Namespaces</title>
125
126    <para>To avoid possible collisions between names used for symbols
127    and preprocessor macros by an application and the libraries it
128    uses, it is good practice for each library to reserve a particular
129    <emphasis>namespace prefix</emphasis>.  An application which
130    ensures it uses no names with these prefixes is then guaranteed to
131    avoid such collisions.</para>
132
133    <para>The &neon; library reserves the use of the namespace
134    prefixes <literal>ne_</literal> and <literal>NE_</literal>.  The
135    libraries used by &neon; may also reserve certain namespaces;
136    collisions between these libraries and a &neon;-based application
137    will not be detected at compile time, since the underlying library
138    interfaces are not exposed through the &neon; header files.  Such
139    collisions can only be detected at link time, when the linker
140    attempts to resolve symbols.  The following list documents some of
141    the namespaces claimed by libraries used by &neon;; this list may
142    be incomplete.</para>
143
144    <variablelist>
145
146      <varlistentry>
147	<term>SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</term>
148	<listitem><simpara>Some of the many prefixes used by the OpenSSL
149	library; little attempt has been made to keep exported symbols
150	within any particular prefixes for this
151	library.</simpara></listitem>
152      </varlistentry>
153
154      <varlistentry>
155        <term>gnutls_, gcry_, gpg_</term>
156        <listitem><simpara>Namespaces used by the GnuTLS library (and
157        dependencies thereof)</simpara></listitem>
158      </varlistentry>
159
160      <varlistentry>
161	<term>XML_, Xml[A-Z]</term> <listitem><simpara>Namespaces
162	used by the expat library.</simpara></listitem>
163      </varlistentry>
164
165      <varlistentry>
166	<term>xml[A-Z], html[A-Z], docb[A-Z]</term>
167	<listitem><simpara>Namespaces used by the libxml2 library; a
168	relatively small number of symbols are used without these
169	prefixes.</simpara></listitem>
170      </varlistentry>
171
172      <varlistentry>
173        <term>inflate, deflate, crc32, compress, uncompres, adler32,
174        zlib</term>
175	<listitem><simpara>Namespaces used by the zlib library; a
176	relatively small number of symbols are used without these
177	prefixes.</simpara></listitem>
178      </varlistentry>
179
180      <varlistentry>
181        <term>krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
182        mit</term>
183
184        <listitem><simpara>Some of the prefixes used by the MIT GSSAPI
185        library and dependencies thereof; a number of symbols lie
186        outside these prefixes.</simpara></listitem>
187      </varlistentry>
188
189      <varlistentry>
190        <term>pakchois_</term>
191        <listitem><simpara>Namespace used by the pakchois 
192         library.</simpara></listitem>
193      </varlistentry>
194
195      <varlistentry>
196        <term>px_</term>
197        <listitem><simpara>Namespace used by the libproxy
198         library.</simpara></listitem>
199      </varlistentry>
200
201    </variablelist>
202
203  </refsect2>
204
205  <refsect2>
206    <title>Argument validation</title>
207  
208    <para>&neon; does not attempt to validate that the parameters
209    passed to functions conform to the API (for instance, checking
210    that pointer arguments are not &null;).  Any use of the &neon; API
211    which is not documented to produce a certain behaviour results is
212    said to produce <emphasis>undefined behaviour</emphasis>; it is
213    likely that &neon; will segfault under these conditions.</para>
214
215  </refsect2>
216
217  <refsect2>
218    <title>URI paths, WebDAV metadata</title>
219
220    <para>The path strings passed to any function must be
221    <emphasis>URI-encoded</emphasis> by the application; &neon; never
222    performs any URI encoding or decoding internally.  WebDAV property
223    names and values must be valid UTF-8 encoded Unicode
224    strings.</para>
225
226  </refsect2>
227
228  <refsect2>
229    <title>User interaction</title>
230
231    <para>As a pure library interface, &neon; will never produce
232    output on <constant>stdout</constant> or
233    <constant>stderr</constant>; all user interaction is the
234    responsibilty of the application.</para>
235  </refsect2>
236
237  <refsect2>
238    <title>Memory handling</title>
239
240    <para>neon does not attempt to cope gracefully with an
241    out-of-memory situation; instead, by default, the
242    <function>abort</function> function is called to immediately
243    terminate the process.  An application may register a custom
244    function which will be called before <function>abort</function> in
245    such a situation; see <xref linkend="ne_oom_callback"/>.</para>
246  
247  </refsect2>
248
249  <refsect2>
250    <title>Callbacks and userdata</title>
251
252    <para>Whenever a callback is registered, a
253    <literal>userdata</literal> pointer is also used to allow the
254    application to associate a context with the callback.  The
255    userdata is of type <type>void *</type>, allowing any pointer to
256    be used.</para>
257
258  </refsect2>
259
260  <refsect2>
261    <title>Large File Support</title>
262
263    <para>Since version 0.27.0, &neon; transparently uses the "LFS
264    transitional" interfaces in places where file-backed file
265    descriptors are manipulated.  This means files larger than 2GiB
266    can be handled on platforms with a native 32-bit
267    <literal>off_t</literal> type, where LFS support is
268    available.</para>
269
270    <para>Some interfaces use the <literal>ne_off_t</literal> type,
271    which is defined to be either <literal>off_t</literal> or
272    <literal>off64_t</literal> according to whether LFS support is
273    detected at build time.  &neon; does not use or require the
274    <literal>-D_FILE_OFFSET_BITS=64</literal> macro definition.</para>
275
276  </refsect2>
277
278  </refsect1>
279
280  <refsect1>
281    <title>See also</title>
282
283    <para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para>
284  </refsect1>
285
286</refentry>
287
288