path: root/doc/ref/neon.xml

<refentry id="refneon">

  <refmeta>
    <refentrytitle>neon</refentrytitle>
    <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>neon</refname>
    <refpurpose>HTTP and WebDAV client library</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>neon is an HTTP and WebDAV client library.  The major
    abstractions exposed are the HTTP <emphasis>session</emphasis>,
    created by <xref linkend="ne_session_create"/>; and the HTTP
    <emphasis>request</emphasis>, created by <xref
    linkend="ne_request_create"/>.  HTTP authentication is handled
    transparently for server and proxy servers, see <xref
    linkend="ne_set_server_auth"/>; complete SSL/TLS support is also
    included, see <xref linkend="ne_ssl_set_verify"/>.</para>

  </refsect1>

  <refsect1>
    <title>Conventions</title>

    <para>Some conventions are used throughout the neon API, to
    provide a consistent and simple interface; these are documented
    below.</para>

  <refsect2>
    <title>Thread-safeness and global initialization</title>

    <para>&neon; itself is implemented to be thread-safe (avoiding any
    use of global state), but relies on the operating system providing
    a thread-safe resolver interface.  Modern operating systems offer
    the thread-safe <function>getaddrinfo</function> interface, which
    &neon; supports; some others implement
    <function>gethostbyname</function> using thread-local
    storage.</para>

    <para>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
    libraries &neon; must be configured using the
    <literal>--enable-threadsafe-ssl</literal>; if this is done,
    locking callbacks will be registered by <xref
    linkend="ne_sock_init"/>; note that care must be exercised if
    &neon; is used in conjunction with another library which uses
    OpenSSL or GnuTLS.</para>

    <para>Some platforms and libraries used by &neon; require global
    initialization before use; notably:

    <itemizedlist>
      <listitem><simpara>The <literal>SIGPIPE</literal> signal
      disposition must be set to <emphasis>ignored</emphasis> or
      otherwise handled to avoid process termination when writing to a
      socket which has been shutdown by the peer.</simpara></listitem>

      <listitem><simpara>OpenSSL and GnuTLSrequire global
      initialization to load shared lookup
      tables.</simpara></listitem>

      <listitem><simpara>The Win32 socket library requires
      initialization before use.</simpara></listitem>
    </itemizedlist>

    The <xref linkend="ne_sock_init"/> function should be called
    before any other use of &neon; to perform any necessary
    initialization needed for the particular platform.  Applications
    wishing to perform all the necessary process-global initialization
    steps themselves may omit to call <xref linkend="ne_sock_init"/>
    (and <xref linkend="ne_sock_exit"/>); &neon; neither checks whether
    these functions are called nor calls them itself.</para>

    <para>For some applications and configurations it may be necessary
    to call <xref linkend="ne_i18n_init"/> to initialize the support
    for internationalization in &neon;.</para>

  </refsect2>

  <refsect2>
    <title>Functions using global state</title>

    <para>Any function call in &neon; may modify the
    <literal>errno</literal> global variable as a side-effect.  Except
    where explicitly documented, the value of <literal>errno</literal>
    is unspecified after any &neon; function call.</para>

    <para>Other than in the use of <literal>errno</literal>, the only
    functions which use or modify process-global state in &neon; are
    as follows:

    <itemizedlist>
      <listitem><simpara><xref linkend="ne_sock_init"/>, <xref
      linkend="ne_i18n_init"/>, and <xref linkend="ne_sock_exit"/>, as
      described above</simpara></listitem>

      <listitem><simpara><function>ne_debug_init</function> and
      <function>ne_debug</function>, if enabled at compile time; for
      debugging output</simpara></listitem>

      <listitem><simpara><xref linkend="ne_oom_callback"/> for
      installing a process-global callback to be invoked on
      <function>malloc</function> failure</simpara></listitem>

    </itemizedlist></para>

  </refsect2>      

  <refsect2>
    <title>Namespaces</title>

    <para>To avoid possible collisions between names used for symbols
    and preprocessor macros by an application and the libraries it
    uses, it is good practice for each library to reserve a particular
    <emphasis>namespace prefix</emphasis>.  An application which
    ensures it uses no names with these prefixes is then guaranteed to
    avoid such collisions.</para>

    <para>The &neon; library reserves the use of the namespace
    prefixes <literal>ne_</literal> and <literal>NE_</literal>.  The
    libraries used by &neon; may also reserve certain namespaces;
    collisions between these libraries and a &neon;-based application
    will not be detected at compile time, since the underlying library
    interfaces are not exposed through the &neon; header files.  Such
    collisions can only be detected at link time, when the linker
    attempts to resolve symbols.  The following list documents some of
    the namespaces claimed by libraries used by &neon;; this list may
    be incomplete.</para>

    <variablelist>

      <varlistentry>
	<term>SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</term>
	<listitem><simpara>Some of the many prefixes used by the OpenSSL
	library; little attempt has been made to keep exported symbols
	within any particular prefixes for this
	library.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>gnutls_, gcry_, gpg_</term>
        <listitem><simpara>Namespaces used by the GnuTLS library (and
        dependencies thereof)</simpara></listitem>
      </varlistentry>

      <varlistentry>
	<term>XML_, Xml[A-Z]</term> <listitem><simpara>Namespaces
	used by the expat library.</simpara></listitem>
      </varlistentry>

      <varlistentry>
	<term>xml[A-Z], html[A-Z], docb[A-Z]</term>
	<listitem><simpara>Namespaces used by the libxml2 library; a
	relatively small number of symbols are used without these
	prefixes.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>inflate, deflate, crc32, compress, uncompres, adler32,
        zlib</term>
	<listitem><simpara>Namespaces used by the zlib library; a
	relatively small number of symbols are used without these
	prefixes.</simpara></listitem>
      </varlistentry>

      <varlistentry>
        <term>krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
        mit</term>

        <listitem><simpara>Some of the prefixes used by the MIT GSSAPI
        library and dependencies thereof; a number of symbols lie
        outside these prefixes.</simpara></listitem>
      </varlistentry>

    </variablelist>

  </refsect2>

  <refsect2>
    <title>Argument validation</title>
  
    <para>&neon; does not attempt to validate that the parameters
    passed to functions conform to the API (for instance, checking
    that pointer arguments are not &null;).  Any use of the &neon; API
    which is not documented to produce a certain behaviour results is
    said to produce <emphasis>undefined behaviour</emphasis>; it is
    likely that &neon; will segfault under these conditions.</para>

  </refsect2>

  <refsect2>
    <title>URI paths, WebDAV metadata</title>

    <para>The path strings passed to any function must be
    <emphasis>URI-encoded</emphasis> by the application; &neon; never
    performs any URI encoding or decoding internally.  WebDAV property
    names and values must be valid UTF-8 encoded Unicode
    strings.</para>

  </refsect2>

  <refsect2>
    <title>User interaction</title>

    <para>As a pure library interface, &neon; will never produce
    output on <constant>stdout</constant> or
    <constant>stderr</constant>; all user interaction is the
    responsibilty of the application.</para>
  </refsect2>

  <refsect2>
    <title>Memory handling</title>

    <para>neon does not attempt to cope gracefully with an
    out-of-memory situation; instead, by default, the
    <function>abort</function> function is called to immediately
    terminate the process.  An application may register a custom
    function which will be called before <function>abort</function> in
    such a situation; see <xref linkend="ne_oom_callback"/>.</para>
  
  </refsect2>

  <refsect2>
    <title>Callbacks and userdata</title>

    <para>Whenever a callback is registered, a
    <literal>userdata</literal> pointer is also used to allow the
    application to associate a context with the callback.  The
    userdata is of type <type>void *</type>, allowing any pointer to
    be used.</para>

  </refsect2>

  <refsect2>
    <title>Large File Support</title>

    <para>Since version 0.27.0, &neon; transparently uses the "LFS
    transitional" interfaces in places where file-backed file
    descriptors are manipulated.  This means files larger than 2GiB
    can be handled on platforms with a native 32-bit
    <literal>off_t</literal> type, where LFS support is
    available.</para>

    <para>Some interfaces use the <literal>ne_off_t</literal> type,
    which is defined to be either <literal>off_t</literal> or
    <literal>off64_t</literal> according to whether LFS support is
    detected at build time.  &neon; does not use or require the
    <literal>-D_FILE_OFFSET_BITS=64</literal> macro definition.</para>

  </refsect2>

  </refsect1>

  <refsect1>
    <title>See also</title>

    <para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para>
  </refsect1>

</refentry>