1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
Guide to neon
=============
Using libneon from applications
-------------------------------
The neon source package is designed to be easily incorporated into
applications:
- autoconf macros are distributed in the 'macros' subdirectory of the
neon distribution. Use NEON_LIBRARY from your configure.in to check
for the presence of the neon library installed on the system. The
macro adds an '--with-neon=...' argument to configure, which allows
the user to specify a location for the library (the standard /usr
and /usr/local directories are checked automatically without having
to be specified).
- The 'src' directory of the neon package can be imported directly
into your application, if you do not wish to add an external
dependency. If you wish to bundle, use the NEON_BUNDLED macro
to configure neon in your application: here, the neon sources are
bundled in a directory called 'libneon':
NEON_BUNDLED(libneon, ...)
If your application supports builds where srcdir != builddir, you
should use the NEON_VPATH_BUNDLED macro like this:
NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)
(thanks to Peter Moulder for getting this working properly).
If you use this macro, a '--with-included-neon' option will
be added to the generated configure script. This allows the user
to force the bundled neon to be used in the application, rather than
any neon library found on the system. If you allow neon to be
configured this way, you must also configure an XML parser. Use
the NEON_XML_PARSER macro to do this.
- The final argument to the _BUNDLED macros is a set of actions which
are executed if the bundled build *is* chosen (rather than an
external neon which might have been found on the user's system).
In here, use either the NEON_LIBTOOL_BUILD or NEON_NORMAL_BUILD
macro to set up the neon Makefile appropriately: including adding
the neon source directory to the recursive make.
- A full fragment might be:
NEON_BUNDLED(libneon, [
NEON_NORMAL_BUILD
NEON_XML_PARSER
SUBDIRS="libneon $SUBDIRS"
])
This means the bundled neon source directory (called 'libneon') is
used if no neon is found on the system, and the standard XML parser
search is used.
The neon API
============
neon offers two levels of API for use in applications:
- Low-level HTTP request/response handling
- High-level method invocation
The low-level interface allows for easily designing new method
handlers, taking care of things like persistent connections,
authentication, and proxy servers. The high-level interface allows
you to easily integrate existing HTTP (and WebDAV) methods into your
application. This document details both interfaces.
N.B.: Documentation is always WRONG. The definitive API reference is in
src/*.c, with src/*.h is hopefully fairly similar.
PLEASE NOTE: the neon API is NOT STABLE, and is not considered to be
stable or backwards-compatible until version 1.0 is reached. If
you are not happy with this constraint, then please either:
1. pick a version of neon and never upgrade
2. don't use neon (yet).
3. contribute sufficient development resources to neon that all
bugs are fixed yesterday, features added tomorrow, and 1.0 is
reached on by the end of the week.
An Important Note
-----------------
Most neon functions which allocate memory with malloc() will call
abort() if malloc() returns NULL. This is a design decision, the
rationale being:
- it makes the interfaces cleaner.
- if malloc() DOES return NULL there is not much you can do about it.
- Apparently, malloc() won't return NULL on systems which over-commit
memory (e.g. Linux), so it doesn't make any real difference anyway.
The author is open to persuasion on this: mail neon@webdav.org.
Namespaces
----------
neon reserves these namespaces:
ne_*
uri_*
sock_*
Eventually all symbols globally defined by the library should fall
within a reserved namespace. The author is considering moving
all symbols into the ne_* namespace.
Note that the XML parser used will also reserve a namespace:
expat takes XML_*, libxml takes xml*
The http_session type
---------------------
The http_session type is used whether you are writing to the low-level
or the high-level interface. An http_session object is created to
store data which persists beyond a single HTTP request:
- Protocol options, e.g. (proxy) server details
- Authentication information
- Persistent connection
A session is created with the 'ne_session_create' call. Before
creating a request for the session, the server details must be set, as
follows:
ne_session *sess;
/* Initialize the socket library */
sock_init();
/* Create the session */
sess = ne_session_create();
/* Optionally, set a proxy server */
ne_session_proxy(sess, "proxy.myisp.com", 8080);
/* Set the server */
ne_session_server(sess, "my.server.com", 80);
The proxy server should be set BEFORE the origin server; otherwise a
DNS lookup will be performed on the origin server by the
ne_session_server call, which may well fail if the client is
firewalled. ne_session_{proxy,server} will return NE_LOOKUP if
the DNS lookup fails; otherwise NE_OK.
The 'ne_set_persist' call can be used to turn off persistent
connection handling: it is on by default.
The 'ne_set_useragent' call can be used to set the User-Agent header
to be sent with requests. A product token of the form
"myhttpclient/0.1.2" should be passed, and will have "neon/x.y.z"
appended in the actual header sent.
When a session has been finished with, it should be destroyed using
ne_session_destroy. Any subsequent operations on the session object
will have undefined results (i.e. will segfault).
Low-level HTTP Request/Response Handling
----------------------------------------
...
|