neon.3

linux subdivision ying gai ke yi le ba

.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NEON" 3 "5 July 2004" "neon 0.24.7" "neon API reference"
.SH NAME
neon \- HTTP and WebDAV client library
.SH "DESCRIPTION"

.PP
neon is an HTTP and WebDAV client library\&. The major abstractions exposed are the HTTP session, created by \fBne_session_create\fR(3); and the HTTP request, created by \fBne_request_create\fR(3)\&. HTTP authentication is handled transparently for server and proxy servers, see \fBne_set_server_auth\fR(3); complete SSL/TLS support is also included, see \fBne_ssl_set_verify\fR(3)\&.

.SH "CONVENTIONS"

.PP
Some conventions are used throughout the neon API, to provide a consistent and simple interface; these are documented below\&.

.SS "Thread-safeness and global initialization"

.PP
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 \fBgetaddrinfo\fR interface, which neon supports; some others implement \fBgethostbyname\fR using thread\-local storage\&.

.PP
To allow thread\-safe use of the OpenSSL library, the application must register some locking callbacks in accordance with the OpenSSL documentation: \fIhttp://www.openssl.org/docs/crypto/threads.html\fR\&.

.PP
Some platforms and libraries used by neon require global initialization before use; notably: 

.TP 3
\(bu
OpenSSL requires global initialization to load shared lookup tables\&.
.TP
\(bu
The SOCKS library requires initialization before use\&.
.TP
\(bu
The Win32 socket library requires initialization before use\&.
.LP
 The \fBne_sock_init\fR(3) function should be called before any other use of neon to perform any necessary initialization needed for the particular platform\&.

.SS "Namespaces"

.PP
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\&.

.PP
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\&.

.TP
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\&.

.TP
XML_, Xml[A\-Z]
Namespaces used by the expat library\&.

.TP
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\&.

.SS "Argument validation"

.PP
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\&.

.SS "URI paths, WebDAV metadata"

.PP
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\&.

.SS "User interaction"

.PP
As a pure library interface, neon will never produce output on \fBstdout\fR or \fBstderr\fR; all user interaction is the responsibilty of the application\&.

.SS "Memory handling"

.PP
neon does not attempt to cope gracefully with an out\-of\-memory situation; instead, by default, the \fBabort\fR function is called to immediately terminate the process\&. An application may register a custom function which will be called before \fBabort\fR in such a situation; see \fBne_oom_callback\fR(3)\&.

.SS "Callbacks and userdata"

.PP
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 \fBvoid *\fR, allowing any pointer to be used\&.

.SH "SEE ALSO"

.PP
\fBne_session_create\fR(3), \fBne_oom_callback\fR(3)

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.