| 1 |
<sect1 id="using"> |
| 2 |
<title>How to use neon from your application</title> |
| 3 |
|
| 4 |
<para>This section describes how to add &neon; support to an |
| 5 |
application. If you just want to quickly try out &neon;, use |
| 6 |
the <xref linkend="refconfig"/> script.</para> |
| 7 |
|
| 8 |
<para>The &neon; source code is designed to be easily embedded |
| 9 |
into an application source tree. &neon; has no dependencies on |
| 10 |
libraries other than an SSL toolkit and XML parser, though the |
| 11 |
source tree can be configured to have no support for SSL or XML |
| 12 |
if desired. To configure the &neon; source code some <ulink |
| 13 |
url="http://www.gnu.org/software/autoconf/">GNU autoconf</ulink> |
| 14 |
macros are supplied, which can be used in a number of ways, as |
| 15 |
follows:</para> |
| 16 |
|
| 17 |
<itemizedlist> |
| 18 |
<listitem> |
| 19 |
|
| 20 |
<para>autoconf macros are distributed in the 'macros' |
| 21 |
subdirectory of the neon distribution. Use the NEON_LIBRARY |
| 22 |
macro from your configure.in to check for the presence of |
| 23 |
the neon library installed on the system. The macro adds an |
| 24 |
'--with-neon=...' argument to configure, which allows the |
| 25 |
user to specify a location for the library (the standard |
| 26 |
/usr and /usr/local directories are checked automatically |
| 27 |
without having to be specified).</para></listitem> |
| 28 |
|
| 29 |
<listitem><para>The 'src' directory of the neon package can be |
| 30 |
imported directly into your application, if you do not wish |
| 31 |
to add an external dependency. If you wish to bundle, use |
| 32 |
the NEON_BUNDLED macro to configure neon in your application: |
| 33 |
here, the neon sources are bundled in a directory called |
| 34 |
'libneon':</para> |
| 35 |
|
| 36 |
<programlisting>NEON_BUNDLED(libneon, ...)</programlisting> |
| 37 |
|
| 38 |
<para>If your application supports builds where srcdir != builddir, |
| 39 |
you should use the NEON_VPATH_BUNDLED macro like this:</para> |
| 40 |
|
| 41 |
<programlisting>NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)</programlisting> |
| 42 |
|
| 43 |
<para>If you use this macro, a '--with-included-neon' option |
| 44 |
will be added to the generated configure script. This |
| 45 |
allows the user to force the bundled neon to be used in the |
| 46 |
application, rather than any neon library found on the |
| 47 |
system. If you allow neon to be configured this way, you |
| 48 |
must also configure an XML parser. Use the NEON_XML_PARSER |
| 49 |
macro to do this.</para></listitem> |
| 50 |
|
| 51 |
<listitem><para>The final argument to the _BUNDLED macros is a |
| 52 |
set of actions which are executed if the bundled build *is* |
| 53 |
chosen (rather than an external neon which might have been |
| 54 |
found on the user's system). In here, use either the |
| 55 |
NEON_LIBTOOL_BUILD or NEON_NORMAL_BUILD macro to set up the |
| 56 |
neon Makefile appropriately: including adding the neon source |
| 57 |
directory to the recursive make.</para></listitem> |
| 58 |
|
| 59 |
</itemizedlist> |
| 60 |
|
| 61 |
<para>A full fragment might be:</para> |
| 62 |
|
| 63 |
<programlisting>NEON_BUNDLED(libneon, [ |
| 64 |
NEON_NORMAL_BUILD |
| 65 |
NEON_XML_PARSER |
| 66 |
SUBDIRS="libneon $SUBDIRS" |
| 67 |
])</programlisting> |
| 68 |
|
| 69 |
<para>This means the bundled neon source directory (called 'libneon') |
| 70 |
is used if no neon is found on the system, and the standard XML |
| 71 |
parser search is used.</para> |
| 72 |
|
| 73 |
</sect1> |
| 74 |
|
| 75 |
<sect1 id="compliance"> |
| 76 |
<title>Standards compliance</title> |
| 77 |
|
| 78 |
<para>&neon; is intended to be compliant with the IETF and W3C |
| 79 |
standards which it implements, with a few exceptions due to |
| 80 |
practical necessity or interoperability issues. These |
| 81 |
exceptions are documented in this section.</para> |
| 82 |
|
| 83 |
<sect2><title>RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV</title> |
| 84 |
|
| 85 |
<para>&neon; is deliberately not compliant with section |
| 86 |
23.4.2, and treats property names as a (namespace-URI, name) |
| 87 |
pair. This is <ulink |
| 88 |
url="http://lists.w3.org/Archives/Public/w3c-dist-auth/1999OctDec/0343.html">generally |
| 89 |
considered</ulink> to be correct behaviour by the WebDAV |
| 90 |
working group, and is likely to formally adopted in a future |
| 91 |
revision of the specification.</para></sect2> |
| 92 |
|
| 93 |
<sect2><title>RFC 2616, Hypertext Transfer Protocol—HTTP/1.1</title> |
| 94 |
|
| 95 |
<para>There is some confusion in this specification about the |
| 96 |
use of the <quote>identity</quote> |
| 97 |
<firstterm>transfer-coding</firstterm>. &neon; ignores the |
| 98 |
<literal>Transfer-Encoding</literal> response header if it |
| 99 |
contains only the (now deprecated) <quote>identity</quote> |
| 100 |
token, and will determine the response message length as if |
| 101 |
the header was not present. &neon; will give an error if a |
| 102 |
response includes a <literal>Transfer-Encoding</literal> |
| 103 |
header with a value other than <quote>identity</quote> or |
| 104 |
<quote>chunked</quote>.</para></sect2> |
| 105 |
|
| 106 |
<sect2> |
| 107 |
<title>RFC 2617, HTTP Authentication: Basic and Digest Access Authentication</title> |
| 108 |
|
| 109 |
<para>&neon; is not strictly compliant with the quoting rules |
| 110 |
given in the grammar for the <literal>Authorization</literal> |
| 111 |
header. The grammar requires that the <literal>qop</literal> |
| 112 |
and <literal>algorithm</literal> parameters are not quoted, |
| 113 |
however one widely deployed server implementation |
| 114 |
(Microsoft® IIS 5) rejects the request if these parameters |
| 115 |
are not quoted. &neon; sends these parameters with |
| 116 |
quotes—this is not known to cause any problems with |
| 117 |
other server implementations.</para></sect2> |
| 118 |
|
| 119 |
<sect2> |
| 120 |
<title>Namespaces in XML</title> |
| 121 |
|
| 122 |
<para>The &neon; XML parser interface will accept and parse |
| 123 |
without error some XML documents which are well-formed |
| 124 |
according to the XML specification but do not conform to the |
| 125 |
"Namespaces in XML" specification <xref |
| 126 |
linkend="bib.xmlnames"/>. Specifically: the restrictions on |
| 127 |
the first character of the <literal>NCName</literal> rule are |
| 128 |
not all implemented; &neon; will allow any |
| 129 |
<literal>CombiningChar</literal>, <literal>Extender</literal> |
| 130 |
and some characters from the <literal>Digit</literal> class in |
| 131 |
this position.</para> </sect2> |
| 132 |
|
| 133 |
<!-- a few RFC2818/3280 issues: rules about when to cache |
| 134 |
sessions in the face of unclean shutdown are strict, neon is |
| 135 |
probably not compliant: document or fix. Likewise SSL |
| 136 |
shutdown issues in general. Cert hostname checks allow |
| 137 |
wildcard "*." syntax which is less than 2818 but more than |
| 138 |
3280 requires. --> |
| 139 |
|
| 140 |
</sect1> |