.\"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 "20 January 2006" "neon 0.25.5" "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 \fIsession\fR, created by \fBne_session_create\fR(3); and the HTTP \fIrequest\fR, 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 \fInamespace prefix\fR\&. 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 \fIundefined behaviour\fR; 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 \fIURI\-encoded\fR 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 .