NEON(3) neon API reference NEON(3)
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(3); and the HTTP request, created by ne_request_cre-
ate(3). HTTP authentication is handled transparently for server and proxy servers, see
ne_set_server_auth(3); complete SSL/TLS support is also included, see ne_ssl_set_ver-
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 operat-
ing 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 lock-
ing callbacks in accordance with the OpenSSL documentation:
Some platforms and libraries used by neon require global initialization before use;
o OpenSSL requires global initialization to load shared lookup tables.
o The SOCKS library requires initialization before use.
o The Win32 socket library requires initialization before use.
The ne_sock_init(3) 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 pre-
fixes 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
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.
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 unde-
fined 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.
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
Callbacks and userdata
Whenever a callback is registered, a userdata pointer is also used to allow the applica-
tion to associate a context with the callback. The userdata is of type void *, allowing
any pointer to be used.
Joe Orton <email@example.com>.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|Availability | SUNWneon |
|Interface Stability | Volatile |
Source for Neon is available on http://opensolaris.org.
neon 0.25.5 20 January 2006 NEON(3)