1NEON(3) neon API reference NEON(3)
2
6 neon - HTTP and WebDAV client library
7
9 neon is an HTTP and WebDAV client library. The major abstractions
10 exposed are the HTTP session, created by ne_session_create(3); and the
11 HTTP request, created by ne_request_create(3). HTTP authentication is
12 handled transparently for server and proxy servers, see
13 ne_set_server_auth(3); complete SSL/TLS support is also included, see
14 ne_ssl_set_verify(3).
15
18 Some conventions are used throughout the neon API, to provide a consis‐
19 tent and simple interface; these are documented below.
20 Thread-safeness and global initialization
23 neon itself is implemented to be thread-safe (avoiding any use of
24 global state), but relies on the operating system providing a
25 thread-safe resolver interface. Modern operating systems offer the
26 thread-safe getaddrinfo interface, which neon supports; some others
27 implement gethostbyname using thread-local storage.
28 To allow thread-safe use of the OpenSSL library, the application must
31 register some locking callbacks in accordance with the OpenSSL documen‐
32 tation: http://www.openssl.org/docs/crypto/threads.html.
33 Some platforms and libraries used by neon require global initialization
36 before use; notably:
37 · OpenSSL requires global initialization to load shared lookup tables.
40 · The SOCKS library requires initialization before use.
42 · The Win32 socket library requires initialization before use.
44 The ne_sock_init(3) function should be called before any other use of
46 neon to perform any necessary initialization needed for the particular
47 platform.
48 Namespaces
51 To avoid possible collisions between names used for symbols and pre‐
52 processor macros by an application and the libraries it uses, it is
53 good practice for each library to reserve a particular namespace pre‐
54 fix. An application which ensures it uses no names with these prefixes
55 is then guaranteed to avoid such collisions.
56 The neon library reserves the use of the namespace prefixes ne_ and
59 NE_. The libraries used by neon may also reserve certain namespaces;
60 collisions between these libraries and a neon-based application will
61 not be detected at compile time, since the underlying library inter‐
62 faces are not exposed through the neon header files. Such collisions
63 can only be detected at link time, when the linker attempts to resolve
64 symbols. The following list documents some of the namespaces claimed by
65 libraries used by neon; this list may be incomplete.
66 SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_
69 Some of the many prefixes used by the OpenSSL library; little
70 attempt has been made to keep exported symbols within any par‐
71 ticular prefixes for this library.
72 XML_, Xml[A-Z]
75 Namespaces used by the expat library.
76 xml[A-Z], html[A-Z], docb[A-Z]
79 Namespaces used by the libxml2 library; a relatively small num‐
80 ber of symbols are used without these prefixes.
81 Argument validation
84 neon does not attempt to validate that the parameters passed to func‐
85 tions conform to the API (for instance, checking that pointer arguments
86 are not NULL). Any use of the neon API which is not documented to pro‐
87 duce a certain behaviour results is said to produce undefined behav‐
88 iour; it is likely that neon will segfault under these conditions.
89 URI paths, WebDAV metadata
92 The path strings passed to any function must be URI-encoded by the
93 application; neon never performs any URI encoding or decoding inter‐
94 nally. WebDAV property names and values must be valid UTF-8 encoded
95 Unicode strings.
96 User interaction
99 As a pure library interface, neon will never produce output on stdout
100 or stderr; all user interaction is the responsibilty of the applica‐
101 tion.
102 Memory handling
105 neon does not attempt to cope gracefully with an out-of-memory situa‐
106 tion; instead, by default, the abort function is called to immediately
107 terminate the process. An application may register a custom function
108 which will be called before abort in such a situation; see ne_oom_call‐
109 back(3).
110 Callbacks and userdata
113 Whenever a callback is registered, a userdata pointer is also used to
114 allow the application to associate a context with the callback. The
115 userdata is of type void *, allowing any pointer to be used.
116
119 ne_session_create(3), ne_oom_callback(3)
120
123 Joe Orton <neon@webdav.org>.
124neon 0.25.5 20 January 2006 NEON(3)