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; and the
11 HTTP request, created by ne_request_create. HTTP authentication is
12 handled transparently for server and proxy servers, see
13 ne_set_server_auth; complete SSL/TLS support is also included, see
14 ne_ssl_set_verify.
15
17 Some conventions are used throughout the neon API, to provide a
18 consistent and simple interface; these are documented below.
19 Thread-safeness and global initialization
21 neon itself is implemented to be thread-safe (avoiding any use of
22 global state), but relies on the operating system providing a
23 thread-safe resolver interface. Modern operating systems offer the
24 thread-safe getaddrinfo interface, which neon supports; some others
25 implement gethostbyname using thread-local storage.
26 To allow thread-safe use of SSL in the OpenSSL and GnuTLS libraries
28 neon must be configured using the --enable-threadsafe-ssl; if this is
29 done, locking callbacks will be registered by ne_sock_init; note that
30 care must be exercised if neon is used in conjunction with another
31 library which uses OpenSSL or GnuTLS.
32 Some platforms and libraries used by neon require global initialization
34 before use; notably:
35 · The SIGPIPE signal disposition must be set to ignored or otherwise
37 handled to avoid process termination when writing to a socket which
38 has been shutdown by the peer.
39 · OpenSSL and GnuTLS require global initialization to load shared
41 lookup tables.
42 · The Win32 socket library requires initialization before use.
44 The ne_sock_init function should be called before any other use of neon
46 to perform any necessary initialization needed for the particular
47 platform. Applications wishing to perform all the necessary
48 process-global initialization steps themselves may omit to call
49 ne_sock_init (and ne_sock_exit); neon neither checks whether these
50 functions are called nor calls them itself.
51 For some applications and configurations it may be necessary to call
53 ne_i18n_init to initialize the support for internationalization in
54 neon.
55 Asynchronous signal safety
57 No function in neon is defined to be “async-signal safe” - that is, no
58 function is safe to call from a signal handler. Any call into the neon
59 library from a signal handler will have undefined behaviour - in other
60 words, it may crash the process.
61 Functions using global state
63 Any function in neon may modify the errno global variable as a
64 side-effect. Except where explicitly documented, the value of errno is
65 unspecified after any neon function call.
66 Other than in the use of errno, the only functions which use or modify
68 process-global state in neon are as follows:
69 · ne_sock_init, ne_i18n_init, and ne_sock_exit, as described above
71 · ne_debug_init and ne_debug, if enabled at compile time; for
73 debugging output
74 · ne_oom_callback for installing a process-global callback to be
76 invoked on malloc failure
77 Namespaces
79 To avoid possible collisions between names used for symbols and
80 preprocessor macros by an application and the libraries it uses, it is
81 good practice for each library to reserve a particular namespace
82 prefix. An application which ensures it uses no names with these
83 prefixes is then guaranteed to avoid such collisions.
84 The neon library reserves the use of the namespace prefixes ne_ and
86 NE_. The libraries used by neon may also reserve certain namespaces;
87 collisions between these libraries and a neon-based application will
88 not be detected at compile time, since the underlying library
89 interfaces are not exposed through the neon header files. Such
90 collisions can only be detected at link time, when the linker attempts
91 to resolve symbols. The following list documents some of the namespaces
92 claimed by libraries used by neon; this list may be incomplete.
93 SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_
95 Some of the many prefixes used by the OpenSSL library; little
96 attempt has been made to keep exported symbols within any
97 particular prefixes for this library.
98 gnutls_, gcry_, gpg_
100 Namespaces used by the GnuTLS library (and dependencies thereof)
101 XML_, Xml[A-Z]
103 Namespaces used by the expat library.
104 xml[A-Z], html[A-Z], docb[A-Z]
106 Namespaces used by the libxml2 library; a relatively small number
107 of symbols are used without these prefixes.
108 inflate, deflate, crc32, compress, uncompres, adler32, zlib
110 Namespaces used by the zlib library; a relatively small number of
111 symbols are used without these prefixes.
112 krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit
114 Some of the prefixes used by the MIT GSSAPI library and
115 dependencies thereof; a number of symbols lie outside these
116 prefixes.
117 pakchois_
119 Namespace used by the pakchois library.
120 px_
122 Namespace used by the libproxy library.
123 Argument validation
125 neon does not attempt to validate that the parameters passed to
126 functions conform to the API (for instance, checking that pointer
127 arguments are not NULL). Any use of the neon API which is not
128 documented to produce a certain behaviour results is said to produce
129 undefined behaviour; it is likely that neon will segfault under these
130 conditions.
131 URI paths, WebDAV metadata
133 The path strings passed to any function must be URI-encoded by the
134 application; neon never performs any URI encoding or decoding
135 internally. WebDAV property names and values must be valid UTF-8
136 encoded Unicode strings.
137 User interaction
139 As a pure library interface, neon will never produce output on stdout
140 or stderr; all user interaction is the responsibilty of the
141 application.
142 Memory handling
144 neon does not attempt to cope gracefully with an out-of-memory
145 situation; instead, by default, the abort function is called to
146 immediately terminate the process. An application may register a custom
147 function which will be called before abort in such a situation; see
148 ne_oom_callback.
149 Callbacks and userdata
151 Whenever a callback is registered, a userdata pointer is also used to
152 allow the application to associate a context with the callback. The
153 userdata is of type void *, allowing any pointer to be used.
154 Large File Support
156 Since version 0.27.0, neon transparently uses the "LFS transitional"
157 interfaces in places where file-backed file descriptors are
158 manipulated. This means files larger than 2GiB can be handled on
159 platforms with a native 32-bit off_t type, where LFS support is
160 available.
161 Some interfaces use the ne_off_t type, which is defined to be either
163 off_t or off64_t according to whether LFS support is detected at build
164 time. neon does not use or require the -D_FILE_OFFSET_BITS=64 macro
165 definition.
166
168 ne_session_create(3), ne_oom_callback
169
171 Joe Orton <neon@lists.manyfish.co.uk>
172 Author.
173
175neon 0.30.0 31 July 2013 NEON(3)