123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205 |
- <sect1 id="using">
- <title>How to use neon from your application</title>
- <para>This section describes how to add &neon; support to an
- application. If you just want to quickly try out &neon;, use
- the <xref linkend="refconfig"/> script.</para>
- <para>The &neon; source code is designed to be easily embedded
- into an application source tree. &neon; has no dependencies on
- libraries other than an SSL toolkit and XML parser, though the
- source tree can be configured to have no support for SSL or XML
- if desired. To configure the &neon; source code some <ulink
- url="http://www.gnu.org/software/autoconf/">GNU autoconf</ulink>
- macros are supplied, which can be used in a number of ways, as
- follows:</para>
-
- <itemizedlist>
- <listitem>
-
- <para>autoconf macros are distributed in the 'macros'
- subdirectory of the neon distribution. Use the NEON_LIBRARY
- macro 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).</para></listitem>
-
- <listitem><para>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':</para>
-
- <programlisting>NEON_BUNDLED(libneon, ...)</programlisting>
-
- <para>If your application supports builds where srcdir != builddir,
- you should use the NEON_VPATH_BUNDLED macro like this:</para>
-
- <programlisting>NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)</programlisting>
-
- <para>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.</para></listitem>
-
- <listitem><para>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.</para></listitem>
-
- </itemizedlist>
-
- <para>A full fragment might be:</para>
-
- <programlisting>NEON_BUNDLED(libneon, [
- NEON_NORMAL_BUILD
- NEON_XML_PARSER
- SUBDIRS="libneon $SUBDIRS"
- ])</programlisting>
-
- <para>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.</para>
-
- </sect1>
- <sect1 id="example">
- <title>Example application</title>
- <para>The code below is a simple example which sends a
- <literal>PUT</literal> request, using the API from
- <literal><ne_basic.h></literal>:
- <programlisting><![CDATA[
- #include <stdio.h>
- #include <stdlib.h>
- #include <ne_basic.h>
- static const char data[] = "Example data.\n";
- int main(int argc, char **argv)
- {
- ne_session *sess;
- int ec = EXIT_SUCCESS;
- ne_sock_init(); /* Global library initialization. */
- sess = ne_session_create("http", "localhost", 80);
- if (ne_putbuf(sess, "/dav/data.txt", data, sizeof data)) {
- fprintf(stderr, "PUT Request failed: %s\n", ne_get_error(sess));
- ec = EXIT_FAILURE;
- }
- ne_session_destroy(sess);
- return ec;
- }
- ]]></programlisting></para></sect1>
-
- <sect1 id="compliance">
- <title>Standards compliance</title>
-
- <para>&neon; is intended to be compliant with the IETF and W3C
- standards which it implements, with a few exceptions due to
- practical necessity or interoperability issues. These
- exceptions are documented in this section.</para>
- <sect2><title>RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV</title>
-
- <para>&neon; is deliberately not compliant with section
- 23.4.2, and treats property names as a (namespace-URI, name)
- pair. This is <ulink
- url="http://lists.w3.org/Archives/Public/w3c-dist-auth/1999OctDec/0343.html">generally
- considered</ulink> to be correct behaviour by the WebDAV
- working group, and is likely to formally adopted in a future
- revision of the specification.</para></sect2>
-
- <sect2><title>RFC 2616, Hypertext Transfer Protocol—HTTP/1.1</title>
-
- <para>There is some confusion in this specification about the
- use of the <quote>identity</quote>
- <firstterm>transfer-coding</firstterm>. &neon; ignores the
- <literal>Transfer-Encoding</literal> response header if it
- contains only the (now deprecated) <quote>identity</quote>
- token, and will determine the response message length as if
- the header was not present. &neon; will give an error if a
- response includes a <literal>Transfer-Encoding</literal>
- header with a value other than <quote>identity</quote> or
- <quote>chunked</quote>.</para></sect2>
- <sect2>
- <title><ulink url="https://datatracker.ietf.org/doc/html/rfc3986">RFC 3986</ulink> Uniform Resource Identifier (URI): Generic Syntax and <ulink url="https://datatracker.ietf.org/doc/html/rfc6874">RFC 6874</ulink>, Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers</title>
- <para>&neon; parses and handles scoped IPv6 link-local literal
- addresses passed to <xref linkend="refsess"/> since version
- <literal>0.34</literal>, following the syntax in RFC 6874. An
- example <literal>host</literal> argument would be
- <literal>"[fe80::cafe%25eth0]"</literal> where
- <literal>"eth0"</literal> is the scope ID. Since <ulink
- url="https://datatracker.ietf.org/doc/html/rfc9110">RFC
- 9110</ulink> does not reference the extended syntax of scoped
- IPv6 literals, and a scope ID has no meaningful interpretation
- outside of the client host, it is omitted from the
- <literal>Host</literal> header sent over the wire. So the
- example argument here translates to an HTTP/1.1 header field
- of <literal>Host: [fe80::cafe]</literal>.</para>
- </sect2>
- <sect2>
- <title>RFC 7616, HTTP Digest Access Authentication</title>
- <para>&neon; is not strictly compliant with the quoting rules
- given in the grammar for the <literal>Authorization</literal>
- header. The grammar requires that the <literal>qop</literal>
- and <literal>algorithm</literal> parameters are not quoted,
- however one widely deployed server implementation
- (Microsoft® IIS 5) rejects the request if these parameters
- are not quoted. &neon; sends these parameters with
- quotes—this is not known to cause any problems with
- other server implementations.</para>
- <para>RFC 7616 predates RFC 9112 and uses conflicting language
- around URIs. &neon; uses the RFC 9112
- <literal>request-target</literal> in both the
- <literal>A2</literal> grammar and the <literal>uri=</literal>
- parameter of the <literal>Authorization</literal>
- header. &neon; will accept (and resolve) any URI-reference in
- the <literal>domain=</literal> parameter for
- <literal>WWW-Authenticate</literal> response header
- field.</para>
- </sect2>
- <sect2>
- <title>Namespaces in XML</title>
- <para>The &neon; XML parser interface will accept and parse
- without error some XML documents which are well-formed
- according to the XML specification but do not conform to the
- "Namespaces in XML" specification <xref
- linkend="bib.xmlnames"/>. Specifically: the restrictions on
- the first character of the <literal>NCName</literal> rule are
- not all implemented; &neon; will allow any
- <literal>CombiningChar</literal>, <literal>Extender</literal>
- and some characters from the <literal>Digit</literal> class in
- this position.</para> </sect2>
-
- <!-- a few RFC2818/3280 issues: rules about when to cache
- sessions in the face of unclean shutdown are strict, neon is
- probably not compliant: document or fix. Likewise SSL
- shutdown issues in general. Cert hostname checks allow
- wildcard "*." syntax which is less than 2818 but more than
- 3280 requires. -->
- </sect1>
|