neon — HTTP and WebDAV client library
neon is an HTTP and WebDAV client library. The major abstractions exposed are the HTTP session, created by ne_session_create; and the HTTP request, created by ne_request_create. HTTP authentication is handled transparently for server and proxy servers, see ne_set_server_auth; complete SSL/TLS support is also included, see ne_ssl_set_verify.
Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below.
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 getaddrinfo
interface, which
neon supports; some others implement
gethostbyname
using thread-local
storage.
To allow thread-safe use of the OpenSSL library, the application must register some locking callbacks in accordance with the OpenSSL documentation.
Some platforms and libraries used by neon require global initialization before use; notably:
The ne_sock_init function should be called before any other use of neon to perform any necessary initialization needed for the particular platform.
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 namespace prefix. An application which ensures it uses no names with these prefixes is then guaranteed to avoid such collisions.
The neon library reserves the use of the namespace
prefixes ne_
and NE_
. 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.
SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_ | 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. |
XML_, Xml[A-Z] | Namespaces used by the expat library. |
xml[A-Z], html[A-Z], docb[A-Z] | Namespaces used by the libxml2 library; a relatively small number of symbols are used without these prefixes. |
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 undefined behaviour; it is
likely that neon will segfault under these conditions.
The path strings passed to any function must be URI-encoded 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.
As a pure library interface, neon will never produce
output on stdout
or
stderr
; all user interaction is the
responsibilty of the application.
neon does not attempt to cope gracefully with an
out-of-memory situation; instead, by default, the
abort
function is called to immediately
terminate the process. An application may register a custom
function which will be called before abort
in
such a situation; see ne_oom_callback.