base
This commit is contained in:
biosvos
@@ -0,0 +1,68 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="ref.html" title="neon API reference"><link rel="next" href="refconfig.html" title="neon-config"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">neon</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr></table><hr></div><div class="refentry" lang="en"><a name="refneon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>neon — HTTP and WebDAV client library</p></div><div class="refsect1" lang="en"><a name="id2928090"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library. The major
|
||||
abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>,
|
||||
created by <a href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP
|
||||
<span class="emphasis"><em>request</em></span>, created by <a href="refreq.html#ne_request_create">ne_request_create</a>. HTTP authentication is handled
|
||||
transparently for server and proxy servers, see <a href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also
|
||||
included, see <a href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1" lang="en"><a name="id2928747"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to
|
||||
provide a consistent and simple interface; these are documented
|
||||
below.</p><div class="refsect2" lang="en"><a name="id2928758"></a><h3>Thread-safeness and global initialization</h3><p>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 <code class="function">getaddrinfo</code> interface, which
|
||||
neon supports; some others implement
|
||||
<code class="function">gethostbyname</code> using thread-local
|
||||
storage.</p><p>To allow thread-safe use of the OpenSSL library, the
|
||||
application must register some locking callbacks in accordance
|
||||
with the <a href="http://www.openssl.org/docs/crypto/threads.html" target="_top">OpenSSL
|
||||
documentation</a>.</p><p>Some platforms and libraries used by neon require global
|
||||
initialization before use; notably:
|
||||
|
||||
</p><div class="itemizedlist"><ul type="disc"><li>OpenSSL requires global initialization to
|
||||
load shared lookup tables.</li><li>The SOCKS library requires initialization
|
||||
before use.</li><li>The Win32 socket library requires
|
||||
initialization before use.</li></ul></div><p>
|
||||
|
||||
The <a href="refsockinit.html#ne_sock_init">ne_sock_init</a> function should be called
|
||||
before any other use of neon to perform any necessary
|
||||
initialization needed for the particular platform.</p></div><div class="refsect2" lang="en"><a name="id2928833"></a><h3>Namespaces</h3><p>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
|
||||
<span class="emphasis"><em>namespace prefix</em></span>. An application which
|
||||
ensures it uses no names with these prefixes is then guaranteed to
|
||||
avoid such collisions.</p><p>The neon library reserves the use of the namespace
|
||||
prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>. 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.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></td><td>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.</td></tr><tr><td><span class="term">XML_, Xml[A-Z]</span></td><td>Namespaces
|
||||
used by the expat library.</td></tr><tr><td><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></td><td>Namespaces used by the libxml2 library; a
|
||||
relatively small number of symbols are used without these
|
||||
prefixes.</td></tr></tbody></table></div></div><div class="refsect2" lang="en"><a name="id2928918"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters
|
||||
passed to functions conform to the API (for instance, checking
|
||||
that pointer arguments are not <code class="literal">NULL</code>). Any use of the neon API
|
||||
which is not documented to produce a certain behaviour results is
|
||||
said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is
|
||||
likely that neon will segfault under these conditions.</p></div><div class="refsect2" lang="en"><a name="id2928933"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be
|
||||
<span class="emphasis"><em>URI-encoded</em></span> 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.</p></div><div class="refsect2" lang="en"><a name="id2928962"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce
|
||||
output on <code class="constant">stdout</code> or
|
||||
<code class="constant">stderr</code>; all user interaction is the
|
||||
responsibilty of the application.</p></div><div class="refsect2" lang="en"><a name="id2928986"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an
|
||||
out-of-memory situation; instead, by default, the
|
||||
<code class="function">abort</code> function is called to immediately
|
||||
terminate the process. An application may register a custom
|
||||
function which will be called before <code class="function">abort</code> in
|
||||
such a situation; see <a href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2" lang="en"><a name="id2929018"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a
|
||||
<code class="literal">userdata</code> pointer is also used to allow the
|
||||
application to associate a context with the callback. The
|
||||
userdata is of type <em class="type">void *</em>, allowing any pointer to
|
||||
be used.</p></div></div><div class="refsect1" lang="en"><a name="id2929040"></a><h2>See also</h2><p><a href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a href="refalloc.html#ne_oom_callback">ne_oom_callback</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon API reference </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon-config</td></tr></table></div></body></html>
|
||||
Reference in New Issue
Block a user