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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
<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 SSL in the OpenSSL and GnuTLS
libraries &neon; must be configured using the
<literal>--enable-threadsafe-ssl</literal>; if this is done,
locking callbacks will be registered by <xref
linkend="ne_sock_init"/>; note that care must be exercised if
&neon; is used in conjunction with another library which uses
OpenSSL or GnuTLS.</para>
<para>Some platforms and libraries used by &neon; require global
initialization before use; notably:
<itemizedlist>
<listitem><simpara>The <literal>SIGPIPE</literal> signal
disposition must be set to
<emphasis>ignored</emphasis>.</simpara></listitem>
<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>
<para>For some applications it may be necessary to call <xref
linkend="ne_i18n_init"/> to initialize the internationalization
support &neon;.</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>
|
