using.xml 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. <sect1 id="using">
  2. <title>How to use neon from your application</title>
  3. <para>This section describes how to add &neon; support to an
  4. application. If you just want to quickly try out &neon;, use
  5. the <xref linkend="refconfig"/> script.</para>
  6. <para>The &neon; source code is designed to be easily embedded
  7. into an application source tree. &neon; has no dependencies on
  8. libraries other than an SSL toolkit and XML parser, though the
  9. source tree can be configured to have no support for SSL or XML
  10. if desired. To configure the &neon; source code some <ulink
  11. url="http://www.gnu.org/software/autoconf/">GNU autoconf</ulink>
  12. macros are supplied, which can be used in a number of ways, as
  13. follows:</para>
  14. <itemizedlist>
  15. <listitem>
  16. <para>autoconf macros are distributed in the 'macros'
  17. subdirectory of the neon distribution. Use the NEON_LIBRARY
  18. macro from your configure.in to check for the presence of
  19. the neon library installed on the system. The macro adds an
  20. '--with-neon=...' argument to configure, which allows the
  21. user to specify a location for the library (the standard
  22. /usr and /usr/local directories are checked automatically
  23. without having to be specified).</para></listitem>
  24. <listitem><para>The 'src' directory of the neon package can be
  25. imported directly into your application, if you do not wish
  26. to add an external dependency. If you wish to bundle, use
  27. the NEON_BUNDLED macro to configure neon in your application:
  28. here, the neon sources are bundled in a directory called
  29. 'libneon':</para>
  30. <programlisting>NEON_BUNDLED(libneon, ...)</programlisting>
  31. <para>If your application supports builds where srcdir != builddir,
  32. you should use the NEON_VPATH_BUNDLED macro like this:</para>
  33. <programlisting>NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)</programlisting>
  34. <para>If you use this macro, a '--with-included-neon' option
  35. will be added to the generated configure script. This
  36. allows the user to force the bundled neon to be used in the
  37. application, rather than any neon library found on the
  38. system. If you allow neon to be configured this way, you
  39. must also configure an XML parser. Use the NEON_XML_PARSER
  40. macro to do this.</para></listitem>
  41. <listitem><para>The final argument to the _BUNDLED macros is a
  42. set of actions which are executed if the bundled build *is*
  43. chosen (rather than an external neon which might have been
  44. found on the user's system). In here, use either the
  45. NEON_LIBTOOL_BUILD or NEON_NORMAL_BUILD macro to set up the
  46. neon Makefile appropriately: including adding the neon source
  47. directory to the recursive make.</para></listitem>
  48. </itemizedlist>
  49. <para>A full fragment might be:</para>
  50. <programlisting>NEON_BUNDLED(libneon, [
  51. NEON_NORMAL_BUILD
  52. NEON_XML_PARSER
  53. SUBDIRS="libneon $SUBDIRS"
  54. ])</programlisting>
  55. <para>This means the bundled neon source directory (called 'libneon')
  56. is used if no neon is found on the system, and the standard XML
  57. parser search is used.</para>
  58. </sect1>
  59. <sect1 id="example">
  60. <title>Example application</title>
  61. <para>The code below is a simple example which sends a
  62. <literal>PUT</literal> request, using the API from
  63. <literal>&lt;ne_basic.h&gt;</literal>:
  64. <programlisting><![CDATA[
  65. #include <stdio.h>
  66. #include <stdlib.h>
  67. #include <ne_basic.h>
  68. static const char data[] = "Example data.\n";
  69. int main(int argc, char **argv)
  70. {
  71. ne_session *sess;
  72. int ec = EXIT_SUCCESS;
  73. ne_sock_init(); /* Global library initialization. */
  74. sess = ne_session_create("http", "localhost", 80);
  75. if (ne_putbuf(sess, "/dav/data.txt", data, sizeof data)) {
  76. fprintf(stderr, "PUT Request failed: %s\n", ne_get_error(sess));
  77. ec = EXIT_FAILURE;
  78. }
  79. ne_session_destroy(sess);
  80. return ec;
  81. }
  82. ]]></programlisting></para></sect1>
  83. <sect1 id="compliance">
  84. <title>Standards compliance</title>
  85. <para>&neon; is intended to be compliant with the IETF and W3C
  86. standards which it implements, with a few exceptions due to
  87. practical necessity or interoperability issues. These
  88. exceptions are documented in this section.</para>
  89. <sect2><title>RFC 2518, HTTP Extensions for Distributed Authoring&mdash;WebDAV</title>
  90. <para>&neon; is deliberately not compliant with section
  91. 23.4.2, and treats property names as a (namespace-URI, name)
  92. pair. This is <ulink
  93. url="http://lists.w3.org/Archives/Public/w3c-dist-auth/1999OctDec/0343.html">generally
  94. considered</ulink> to be correct behaviour by the WebDAV
  95. working group, and is likely to formally adopted in a future
  96. revision of the specification.</para></sect2>
  97. <sect2><title>RFC 2616, Hypertext Transfer Protocol&mdash;HTTP/1.1</title>
  98. <para>There is some confusion in this specification about the
  99. use of the <quote>identity</quote>
  100. <firstterm>transfer-coding</firstterm>. &neon; ignores the
  101. <literal>Transfer-Encoding</literal> response header if it
  102. contains only the (now deprecated) <quote>identity</quote>
  103. token, and will determine the response message length as if
  104. the header was not present. &neon; will give an error if a
  105. response includes a <literal>Transfer-Encoding</literal>
  106. header with a value other than <quote>identity</quote> or
  107. <quote>chunked</quote>.</para></sect2>
  108. <sect2>
  109. <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>
  110. <para>&neon; parses and handles scoped IPv6 link-local literal
  111. addresses passed to <xref linkend="refsess"/> since version
  112. <literal>0.34</literal>, following the syntax in RFC 6874. An
  113. example <literal>host</literal> argument would be
  114. <literal>"[fe80::cafe%25eth0]"</literal> where
  115. <literal>"eth0"</literal> is the scope ID. Since <ulink
  116. url="https://datatracker.ietf.org/doc/html/rfc9110">RFC
  117. 9110</ulink> does not reference the extended syntax of scoped
  118. IPv6 literals, and a scope ID has no meaningful interpretation
  119. outside of the client host, it is omitted from the
  120. <literal>Host</literal> header sent over the wire. So the
  121. example argument here translates to an HTTP/1.1 header field
  122. of <literal>Host: [fe80::cafe]</literal>.</para>
  123. </sect2>
  124. <sect2>
  125. <title>RFC 7616, HTTP Digest Access Authentication</title>
  126. <para>&neon; is not strictly compliant with the quoting rules
  127. given in the grammar for the <literal>Authorization</literal>
  128. header. The grammar requires that the <literal>qop</literal>
  129. and <literal>algorithm</literal> parameters are not quoted,
  130. however one widely deployed server implementation
  131. (Microsoft&reg; IIS 5) rejects the request if these parameters
  132. are not quoted. &neon; sends these parameters with
  133. quotes&mdash;this is not known to cause any problems with
  134. other server implementations.</para>
  135. <para>RFC 7616 predates RFC 9112 and uses conflicting language
  136. around URIs. &neon; uses the RFC 9112
  137. <literal>request-target</literal> in both the
  138. <literal>A2</literal> grammar and the <literal>uri=</literal>
  139. parameter of the <literal>Authorization</literal>
  140. header. &neon; will accept (and resolve) any URI-reference in
  141. the <literal>domain=</literal> parameter for
  142. <literal>WWW-Authenticate</literal> response header
  143. field.</para>
  144. </sect2>
  145. <sect2>
  146. <title>Namespaces in XML</title>
  147. <para>The &neon; XML parser interface will accept and parse
  148. without error some XML documents which are well-formed
  149. according to the XML specification but do not conform to the
  150. "Namespaces in XML" specification <xref
  151. linkend="bib.xmlnames"/>. Specifically: the restrictions on
  152. the first character of the <literal>NCName</literal> rule are
  153. not all implemented; &neon; will allow any
  154. <literal>CombiningChar</literal>, <literal>Extender</literal>
  155. and some characters from the <literal>Digit</literal> class in
  156. this position.</para> </sect2>
  157. <!-- a few RFC2818/3280 issues: rules about when to cache
  158. sessions in the face of unclean shutdown are strict, neon is
  159. probably not compliant: document or fix. Likewise SSL
  160. shutdown issues in general. Cert hostname checks allow
  161. wildcard "*." syntax which is less than 2818 but more than
  162. 3280 requires. -->
  163. </sect1>