NEON
Section: neon API reference (3)
Updated: 30 September 2016
Index
Return to Main Contents
NAME
neon - HTTP and WebDAV client library
DESCRIPTION
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.
CONVENTIONS
Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below.
Thread-safeness and global initialization
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 SSL in the OpenSSL and GnuTLS libraries neon must be configured using the
--enable-threadsafe-ssl; if this is done, locking callbacks will be registered by
ne_sock_init; note that care must be exercised if neon is used in conjunction with another library which uses OpenSSL or GnuTLS.
Some platforms and libraries used by neon require global initialization before use; notably:
-
*
The
SIGPIPE
signal disposition must be set to
ignored
or otherwise handled to avoid process termination when writing to a socket which has been shutdown by the peer.
-
*
OpenSSL and GnuTLS require global initialization to load shared lookup tables.
-
*
The Win32 socket library requires initialization before use.
The
ne_sock_init
function should be called before any other use of neon to perform any necessary initialization needed for the particular platform. Applications wishing to perform all the necessary process-global initialization steps themselves may omit to call
ne_sock_init
(and
ne_sock_exit); neon neither checks whether these functions are called nor calls them itself.
For some applications and configurations it may be necessary to call
ne_i18n_init
to initialize the support for internationalization in neon.
Asynchronous signal safety
No function in neon is defined to be
lqasync-signal saferq
- that is, no function is safe to call from a signal handler. Any call into the neon library from a signal handler will have undefined behaviour - in other words, it may crash the process.
Functions using global state
Any function in neon may modify the
errno
global variable as a side-effect. Except where explicitly documented, the value of
errno
is unspecified after any neon function call.
Other than in the use of
errno, the only functions which use or modify process-global state in neon are as follows:
-
*
ne_sock_init,
ne_i18n_init, and
ne_sock_exit, as described above
-
*
ne_debug_init
and
ne_debug, if enabled at compile time; for debugging output
-
*
ne_oom_callback
for installing a process-global callback to be invoked on
malloc
failure
Namespaces
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.
gnutls_, gcry_, gpg_
-
Namespaces used by the GnuTLS library (and dependencies thereof)
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.
inflate, deflate, crc32, compress, uncompres, adler32, zlib
-
Namespaces used by the zlib library; a relatively small number of symbols are used without these prefixes.
krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit
-
Some of the prefixes used by the MIT GSSAPI library and dependencies thereof; a number of symbols lie outside these prefixes.
pakchois_
-
Namespace used by the pakchois library.
px_
-
Namespace used by the libproxy library.
Argument validation
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.
URI paths, WebDAV metadata
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.
User interaction
As a pure library interface, neon will never produce output on
stdout
or
stderr; all user interaction is the responsibilty of the application.
Memory handling
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.
Callbacks and userdata
Whenever a callback is registered, a
userdata
pointer is also used to allow the application to associate a context with the callback. The userdata is of type
void *, allowing any pointer to be used.
Large File Support
Since version 0.27.0, neon transparently uses the "LFS transitional" interfaces in functions which use file descriptors. This allows use of files larger than 2GiB on platforms with a native 32-bit
off_t
type, where LFS support is available.
Some neon interfaces use the
ne_off_t
type, which is defined to be either
off_t
or
off64_t
according to whether LFS support is detected at build time. neon does not use or require the
-D_FILE_OFFSET_BITS=64
macro definition.
SEE ALSO
ne_session_create(3),
ne_oom_callback
AUTHOR
Joe Orton <neon@lists.manyfish.co.uk>
-
Author.
COPYRIGHT
Index
- NAME
-
- DESCRIPTION
-
- CONVENTIONS
-
- Thread-safeness and global initialization
-
- Asynchronous signal safety
-
- Functions using global state
-
- Namespaces
-
- Argument validation
-
- URI paths, WebDAV metadata
-
- User interaction
-
- Memory handling
-
- Callbacks and userdata
-
- Large File Support
-
- SEE ALSO
-
- AUTHOR
-
- COPYRIGHT
-
|
|
- Running on 
-
:
: 