diff options
Diffstat (limited to 'doc/ref/neon.xml')
| -rw-r--r-- | doc/ref/neon.xml | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/doc/ref/neon.xml b/doc/ref/neon.xml new file mode 100644 index 0000000..9857c63 --- /dev/null +++ b/doc/ref/neon.xml @@ -0,0 +1,145 @@ +<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 in some configurations makes use of + other libraries which require global initialization. The + <xref linkend="ne_sock_init"/> function should be called before + any other use of the &neon; library interface.</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>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> + + </variablelist> + + </refsect2> + + <refsect2> + <title>Argument validation</title> + + <para>&neon; does not attempt to validate that arguments 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 in + <emphasis>undefined behaviour</emphasis>, by definition.</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>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> + + </refsect1> + + <refsect1> + <title>See also</title> + + <para><xref linkend="refsess"/>, <xref linkend="ne_oom_callback"/></para> + </refsect1> + +</refentry> + |