108 lines
4.8 KiB
Plaintext
108 lines
4.8 KiB
Plaintext
.\"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 October 2005" "neon 0.25.4" "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 <neon@webdav\&.org>.
|