base
This commit is contained in:
biosvos
@@ -0,0 +1,4 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 2. The neon C language interface</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="index.html" title="neon HTTP/WebDAV client library"><link rel="prev" href="security.html" title="HTTP Client Security"><link rel="next" href="xml.html" title="Parsing XML"></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">Chapter 2. The neon C language interface</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="security.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="xml.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 2. The neon C language interface"><div class="titlepage"><div><div><h2 class="title"><a name="api"></a>Chapter 2. The neon C language interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="xml.html">Parsing XML</a></span></dt><dd><dl><dt><span class="sect2"><a href="xml.html#xml-sax">Introduction to SAX</a></span></dt><dt><span class="sect2"><a href="xml.html#xml-stacked">Stacked SAX handlers</a></span></dt><dt><span class="sect2"><a href="xml.html#xml-state">Maintaining state</a></span></dt><dt><span class="sect2"><a href="xml.html#xml-ns">XML namespaces</a></span></dt></dl></dd></dl></div><p>The documentation for the neon interface is split between
|
||||
this chapter, which gives a broad introduction to the abstractions
|
||||
exposed by the library, and <a class="xref" href="ref.html" title="neon API reference">neon API reference</a>, which gives a
|
||||
function-by-function breakdown of the interface.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="xml.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">HTTP Client Security </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Parsing XML</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,4 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Bibliography</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="index.html" title="neon HTTP/WebDAV client library"><link rel="prev" href="refxml.html" title="ne_xml_create"></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">Bibliography</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refxml.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="biblio"></a>Bibliography</h2></div></div></div><div class="biblioentry" title="SSL and TLS: Designing and Building Secure Systems"><a name="bib.ssltls"></a><p>[<abbr class="abbrev">SSL-and-TLS</abbr>] <span class="title"><i><a class="ulink" href="http://www.rtfm.com/sslbook/" target="_top">SSL and
|
||||
TLS: Designing and Building Secure Systems</a></i>. </span><span class="author"><span class="firstname">Eric</span> <span class="surname">Rescorla</span>. </span><span class="isbn">0-201-62598-3. </span><span class="publisher"><span class="publishername">Addison-Wesley. </span></span><span class="pubdate">March 2001. </span></p></div><div class="biblioentry" title="Namespaces in XML"><a name="bib.xmlnames"></a><p>[<abbr class="abbrev">REC-XML-names</abbr>] <span class="corpauthor">World Wide Web Consortium. </span><span class="title"><i><a class="ulink" href="http://www.w3.org/TR/REC-xml-names" target="_top">Namespaces in XML</a></i>. </span><span class="pubdate">January 1999. </span></p></div><div class="biblioentry" title="Hypertext Transfer Protocol—HTTP/1.1"><a name="bib.rfc2616"></a><p>[<abbr class="abbrev">RFC2616</abbr>] <span class="title"><i><a class="ulink" href="http://www.ietf.org/rfc/rfc2616.txt" target="_top">Hypertext Transfer
|
||||
Protocol—HTTP/1.1</a></i>. </span><span class="authorgroup"><span class="firstname">Roy</span> <span class="surname">Fielding</span>, <span class="firstname">Jim</span> <span class="surname">Gettys</span>, <span class="firstname">Jeff</span> <span class="surname">Mogul</span>, <span class="firstname">Henrik</span> <span class="surname">Frystyk</span>, <span class="firstname">Larry</span> <span class="surname">Masinter</span>, <span class="firstname">Paul</span> <span class="surname">Leach</span>, and <span class="firstname">Tim</span> <span class="surname">Berners-Lee</span>. </span><span class="publishername">IETF. </span><span class="pubdate">June 1999. </span></p></div><div class="biblioentry" title="HTTP Extensions for Distributed Authoring—WEBDAV"><a name="bib.rfc2518"></a><p>[<abbr class="abbrev">RFC2518</abbr>] <span class="title"><i><a class="ulink" href="http://www.ietf.org/rfc/rfc2518.txt" target="_top">HTTP Extensions for Distributed Authoring—WEBDAV</a></i>. </span><span class="authorgroup"><span class="firstname">Yaron</span> <span class="surname">Goland</span>, <span class="firstname">Jim</span> <span class="surname">Whitehead</span>, <span class="firstname">Asad</span> <span class="surname">Faizi</span>, <span class="firstname">Steve</span> <span class="surname">Carter</span>, and <span class="firstname">Del</span> <span class="surname">Jensen</span>. </span><span class="publishername">IETF. </span><span class="pubdate">February 1999. </span></p></div><div class="biblioentry" title="Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile"><a name="bib.rfc3280"></a><p>[<abbr class="abbrev">RFC3280</abbr>] <span class="title"><i><a class="ulink" href="http://www.ietf.org/rfc/rfc3280.txt" target="_top">Internet X.509 Public Key Infrastructure
|
||||
Certificate and Certificate Revocation List (CRL) Profile</a></i>. </span><span class="authorgroup"><span class="firstname">Russel</span> <span class="surname">Housley</span>, <span class="firstname">Warwick</span> <span class="surname">Ford</span>, <span class="firstname">Tim</span> <span class="surname">Polk</span>, and <span class="firstname">David</span> <span class="surname">Solo</span>. </span><span class="publishername">IETF. </span><span class="pubdate">April 2002. </span></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refxml.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">ne_xml_create </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,34 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Standards compliance</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="intro.html" title="Chapter 1. Introduction"><link rel="prev" href="using.html" title="How to use neon from your application"><link rel="next" href="security.html" title="HTTP Client Security"></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">Standards compliance</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="security.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Standards compliance"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="compliance"></a>Standards compliance</h2></div></div></div><p>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.</p><div class="sect2" title="RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV"><div class="titlepage"><div><div><h3 class="title"><a name="id328676"></a>RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV</h3></div></div></div><p>neon is deliberately not compliant with section
|
||||
23.4.2, and treats property names as a (namespace-URI, name)
|
||||
pair. This is <a class="ulink" href="http://lists.w3.org/Archives/Public/w3c-dist-auth/1999OctDec/0343.html" target="_top">generally
|
||||
considered</a> to be correct behaviour by the WebDAV
|
||||
working group, and is likely to formally adopted in a future
|
||||
revision of the specification.</p></div><div class="sect2" title="RFC 2616, Hypertext Transfer Protocol—HTTP/1.1"><div class="titlepage"><div><div><h3 class="title"><a name="id328692"></a>RFC 2616, Hypertext Transfer Protocol—HTTP/1.1</h3></div></div></div><p>There is some confusion in this specification about the
|
||||
use of the <span class="quote">“<span class="quote">identity</span>”</span>
|
||||
<em class="firstterm">transfer-coding</em>. neon ignores the
|
||||
<code class="literal">Transfer-Encoding</code> response header if it
|
||||
contains only the (now deprecated) <span class="quote">“<span class="quote">identity</span>”</span>
|
||||
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 <code class="literal">Transfer-Encoding</code>
|
||||
header with a value other than <span class="quote">“<span class="quote">identity</span>”</span> or
|
||||
<span class="quote">“<span class="quote">chunked</span>”</span>.</p></div><div class="sect2" title="RFC 2617, HTTP Authentication: Basic and Digest Access Authentication"><div class="titlepage"><div><div><h3 class="title"><a name="id328732"></a>RFC 2617, HTTP Authentication: Basic and Digest Access Authentication</h3></div></div></div><p>neon is not strictly compliant with the quoting rules
|
||||
given in the grammar for the <code class="literal">Authorization</code>
|
||||
header. The grammar requires that the <code class="literal">qop</code>
|
||||
and <code class="literal">algorithm</code> 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.</p></div><div class="sect2" title="Namespaces in XML"><div class="titlepage"><div><div><h3 class="title"><a name="id328761"></a>Namespaces in XML</h3></div></div></div><p>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 <a class="xref" href="biblio.html#bib.xmlnames" title="Namespaces in XML">[<abbr class="abbrev">REC-XML-names</abbr>]</a>. Specifically: the restrictions on
|
||||
the first character of the <code class="literal">NCName</code> rule are
|
||||
not all implemented; neon will allow any
|
||||
<code class="literal">CombiningChar</code>, <code class="literal">Extender</code>
|
||||
and some characters from the <code class="literal">Digit</code> class in
|
||||
this position.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="security.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">How to use neon from your application </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> HTTP Client Security</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,36 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Feature list</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="intro.html" title="Chapter 1. Introduction"><link rel="prev" href="intro.html" title="Chapter 1. Introduction"><link rel="next" href="using.html" title="How to use neon from your application"></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">Feature list</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="using.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Feature list"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="features"></a>Feature list</h2></div></div></div><p>The major features of the neon library are as follows:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>A high-level interface to common HTTP and WebDAV
|
||||
methods. This allows you to easily dispatch a GET or a MKCOL request
|
||||
against a resource with a single function call.</p></li><li class="listitem"><p>A low-level interface for HTTP request
|
||||
handling; allowing you to implement requests using arbitrary methods
|
||||
and request headers, capture arbitrary response headers, and so
|
||||
on.</p></li><li class="listitem"><p>Persistent connection support; neon groups a
|
||||
set of requests to a server into a "session"; requests within that
|
||||
session can use a persistent (also known as "keep-alive")
|
||||
connection.</p></li><li class="listitem"><p>Modern HTTP authentication support: a complete
|
||||
implementation of the new authentication standard, RFC2617, supporting
|
||||
the Digest, Basic, and Negotiate protocols. Credentials are supplied
|
||||
by an application-defined callback as appropriate.</p></li><li class="listitem"><p>Proxy server support; a session can be set to
|
||||
use a proxy server. Authentication is supported for the Proxy as well
|
||||
as the origin server. The system's proxy configuration can be
|
||||
optionally used, on some platforms.</p></li><li class="listitem"><p>Complete SSL support; a simple interface for
|
||||
enabling SSL, hiding the complexity of using an SSL library directly.
|
||||
Client certificate support, callback-based server certificate
|
||||
verification, along with functions to load trusted CA certificates.
|
||||
Smartcard-based client certs are also supported via a wrapper
|
||||
interface for PKCS#11 modules.</p></li><li class="listitem"><p>Compressed response support: responses
|
||||
compressed using the "deflate" algorithm can be transparently
|
||||
decompressed.</p></li><li class="listitem"><p>Generic XML parsing interface for handling XML
|
||||
response bodies using SAX-like callbacks. Both the expat and libxml
|
||||
XML parser libraries are supported.</p></li><li class="listitem"><p>WebDAV metadata support; set and remove
|
||||
properties, query properties (PROPFIND); simple interface for
|
||||
retrieving "flat" byte-string properties, more advanced support for
|
||||
parsing "complex" structured XML properties.</p></li><li class="listitem"><p>Build environment support: the neon source
|
||||
tree is designed so that it can be embedded in your application's
|
||||
build tree; autoconf macros are supplied for integration. To get
|
||||
started quickly a <a class="xref" href="refconfig.html" title="neon-config"><span class="refentrytitle">neon-config</span></a> script is included,
|
||||
to easily determine how to compile and link against an installed copy
|
||||
of neon</p></li><li class="listitem"><p>Complete test suite: the neon test suite
|
||||
comprises half as many lines of source code as the library itself,
|
||||
including many tests for protocol compliance in network behaviour, and
|
||||
that the library implementation meets the guarantees made by the
|
||||
API.</p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="intro.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> How to use neon from your application</td></tr></table></div></body></html>
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,7 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 1. Introduction</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="index.html" title="neon HTTP/WebDAV client library"><link rel="prev" href="index.html" title="neon HTTP/WebDAV client library"><link rel="next" href="features.html" title="Feature list"></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">Chapter 1. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="features.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a name="intro"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="features.html">Feature list</a></span></dt><dt><span class="sect1"><a href="using.html">How to use neon from your application</a></span></dt><dt><span class="sect1"><a href="compliance.html">Standards compliance</a></span></dt><dd><dl><dt><span class="sect2"><a href="compliance.html#id328676">RFC 2518, HTTP Extensions for Distributed Authoring—WebDAV</a></span></dt><dt><span class="sect2"><a href="compliance.html#id328692">RFC 2616, Hypertext Transfer Protocol—HTTP/1.1</a></span></dt><dt><span class="sect2"><a href="compliance.html#id328732">RFC 2617, HTTP Authentication: Basic and Digest Access Authentication</a></span></dt><dt><span class="sect2"><a href="compliance.html#id328761">Namespaces in XML</a></span></dt></dl></dd><dt><span class="sect1"><a href="security.html">HTTP Client Security</a></span></dt><dd><dl><dt><span class="sect2"><a href="security.html#id328572">CPU or memory consumption attacks</a></span></dt><dt><span class="sect2"><a href="security.html#id329132">SSL/TLS connection security</a></span></dt><dt><span class="sect2"><a href="security.html#id329198">Control character insertion in error messages</a></span></dt><dt><span class="sect2"><a href="security.html#id329215">Attacks against authentication credentials</a></span></dt></dl></dd></dl></div><p>This chapter provides an introduction to neon, giving an
|
||||
overview of the range of features offered, and some general guidelines
|
||||
for using the neon API.</p><p>neon aims to provide a modern, flexible, and simple API
|
||||
in the C programming language for implementing HTTP and WebDAV
|
||||
support. The WebDAV functionality is entirely separate from the basic
|
||||
HTTP functionality; neon can be used simply as an HTTP client library,
|
||||
ignoring the WebDAV support if desired.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="features.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon HTTP/WebDAV client library </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Feature list</td></tr></table></div></body></html>
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,12 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_malloc</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refiaddr.html" title="ne_iaddr_make"><link rel="next" href="refsess.html" title="ne_session_create"></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">ne_malloc</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refiaddr.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsess.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_malloc"><a name="refalloc"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_malloc, ne_calloc, ne_realloc, ne_strdup, ne_strndup, ne_oom_callback — memory allocation wrappers</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_alloc.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void *<b class="fsfunc">ne_malloc</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void *<b class="fsfunc">ne_calloc</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void *<b class="fsfunc">ne_realloc</b>(</code></td><td>void *<var class="pdparam">size</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">len</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_strdup</b>(</code></td><td>const char *<var class="pdparam">s</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_strndup</b>(</code></td><td>const char *<var class="pdparam">s</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_oom_callback</b>(</code></td><td>void (*<var class="pdparam">callback</var>)(void)<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id337454"></a><h2>Description</h2><p>The functions <code class="function">ne_malloc</code>,
|
||||
<code class="function">ne_calloc</code>, <code class="function">ne_realloc</code>,
|
||||
<code class="function">ne_strdup</code> and <code class="function">ne_strdnup</code>
|
||||
provide wrappers for the equivalent functions in the standard C
|
||||
library. The wrappers provide the extra guarantee that if the C
|
||||
library equivalent returns <code class="literal">NULL</code> when no memory is available, an
|
||||
optional callback will be called, and the library will then call
|
||||
<code class="function">abort</code>().</p><p><code class="function">ne_oom_callback</code> registers a callback
|
||||
which will be invoked if an out of memory error is detected.</p></div><div class="refsect1" title="Notes"><a name="id337510"></a><h2>Notes</h2><p>If the operating system uses optimistic memory
|
||||
allocation, the C library memory allocation routines will not return
|
||||
<code class="literal">NULL</code>, so it is not possible to gracefully handle memory allocation
|
||||
failures.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refiaddr.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="refsess.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_iaddr_make </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_session_create</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,38 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_set_server_auth</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refreqbody.html" title="ne_set_request_body_buffer"><link rel="next" href="refshave.html" title="ne_shave"></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">ne_set_server_auth</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refreqbody.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refshave.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_set_server_auth"><a name="refauth"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_set_server_auth, ne_set_proxy_auth, ne_forget_auth — register authentication callbacks</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_auth.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">typedef int (*<b class="fsfunc">ne_auth_creds</b>)(</code></td><td>void *<var class="pdparam">userdata</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">realm</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">attempt</var>, </td></tr><tr><td> </td><td>char *<var class="pdparam">username</var>, </td></tr><tr><td> </td><td>char *<var class="pdparam">password</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_server_auth</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>ne_auth_creds <var class="pdparam">callback</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">userdata</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_proxy_auth</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>ne_auth_creds <var class="pdparam">callback</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">userdata</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_forget_auth</b>(</code></td><td>ne_session *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id342838"></a><h2>Description</h2><p>The <em class="type">ne_auth_creds</em> function type defines a
|
||||
callback which is invoked when a server or proxy server requires user
|
||||
authentication for a particular request. The
|
||||
<code class="parameter">realm</code> string is supplied by the server. The <code class="parameter">attempt</code> is a counter giving the
|
||||
number of times the request has been retried with different
|
||||
authentication credentials. The first time the callback is invoked
|
||||
for a particular request, <code class="parameter">attempt</code> will be zero.</p><p>To retry the request using new authentication
|
||||
credentials, the callback should return zero, and the
|
||||
<code class="parameter">username</code> and <code class="parameter">password</code>
|
||||
buffers must contain <code class="literal">NUL</code>-terminated strings. The
|
||||
<code class="literal">NE_ABUFSIZ</code> constant gives the size of these
|
||||
buffers.</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>If you only wish to allow the user one attempt to enter
|
||||
credentials, use the value of the <code class="parameter">attempt</code>
|
||||
parameter as the return value of the callback.</p></div><p>To abort the request, the callback should return a
|
||||
non-zero value; in which case the contents of the
|
||||
<code class="parameter">username</code> and <code class="parameter">password</code>
|
||||
buffers are ignored.</p><p>The <code class="function">ne_forget_auth</code> function can be
|
||||
used to discard the cached authentication credentials.</p></div><div class="refsect1" title="Examples"><a name="id342932"></a><h2>Examples</h2><pre class="programlisting">
|
||||
/* Function which prompts for a line of user input: */
|
||||
extern char *prompt_for(const char *prompt);
|
||||
|
||||
static int
|
||||
my_auth(void *userdata, const char *realm, int attempts,
|
||||
char *username, char *password)
|
||||
{
|
||||
strncpy(username, prompt_for("Username: "), NE_ABUFSIZ);
|
||||
strncpy(password, prompt_for("Password: "), NE_ABUFSIZ);
|
||||
return attempts;
|
||||
}
|
||||
|
||||
int main(...)
|
||||
{
|
||||
ne_session *sess = ne_session_create(...);
|
||||
|
||||
ne_set_server_auth(sess, my_auth, NULL);
|
||||
|
||||
/* ... */
|
||||
}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refreqbody.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="refshave.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_set_request_body_buffer </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_shave</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,20 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_buffer</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refresolve.html" title="ne_addr_resolve"><link rel="next" href="refbufapp.html" title="ne_buffer_append"></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">ne_buffer</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refresolve.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refbufapp.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_buffer"><a name="refbuf"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_buffer — string buffer handling</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h>
|
||||
|
||||
typedef struct {
|
||||
char *data;
|
||||
size_t used;
|
||||
size_t length;
|
||||
} <em class="type">ne_buffer</em>;</pre></div></div><div class="refsect1" title="Description"><a name="id333225"></a><h2>Description</h2><p>The <em class="type">ne_buffer</em> type represents an expandable
|
||||
memory buffer for holding <code class="literal">NUL</code>-terminated strings. The
|
||||
<em class="structfield"><code>data</code></em> field points to the beginnning of the
|
||||
string, the length of which is given by the
|
||||
<em class="structfield"><code>used</code></em> field. The current size of memory
|
||||
allocated is given by the <em class="structfield"><code>length</code></em> field. It
|
||||
is not recommended that the fields of a buffer are manipulated
|
||||
directly. The <em class="structfield"><code>data</code></em> pointer may change when
|
||||
the buffer is modified.</p><p>A buffer is created using <a class="xref" href="refbufcr.html#ne_buffer_create">ne_buffer_create</a> or <a class="xref" href="refbufcr.html#ne_buffer_create_sized">ne_buffer_ncreate</a>, and destroyed using <a class="xref" href="refbufdest.html#ne_buffer_destroy">ne_buffer_destroy</a> or <a class="xref" href="refbufdest.html#ne_buffer_finish">ne_buffer_finish</a>.
|
||||
The functions <a class="xref" href="refbufapp.html#ne_buffer_append">ne_buffer_append</a>, <a class="xref" href="refbufapp.html#ne_buffer_zappend">ne_buffer_zappend</a> and <a class="xref" href="refbufapp.html#ne_buffer_concat">ne_buffer_concat</a> are
|
||||
used to append data to a buffer.</p><p>If the string referenced by the
|
||||
<em class="structfield"><code>data</code></em> pointer is modified directly (rather
|
||||
than using one of the functions listed above),
|
||||
<code class="function">ne_buffer_altered</code> must be called.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refresolve.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="refbufapp.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_addr_resolve </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_buffer_append</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,22 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_buffer_append</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refbuf.html" title="ne_buffer"><link rel="next" href="refbufutil.html" title="ne_buffer_clear"></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">ne_buffer_append</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refbuf.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refbufutil.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_buffer_append"><a name="refbufapp"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_buffer_append, ne_buffer_zappend, ne_buffer_concat — append data to a string buffer</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_append</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">string</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">len</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_zappend</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">string</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_concat</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">str</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id333599"></a><h2>Description</h2><p>The <code class="function">ne_buffer_append</code> and
|
||||
<code class="function">ne_buffer_zappend</code> functions append a string to
|
||||
the end of a buffer; extending the buffer as necessary. The
|
||||
<code class="parameter">len</code> passed to
|
||||
<code class="function">ne_buffer_append</code> specifies the length of the
|
||||
string to append; there must be no <code class="literal">NUL</code> terminator in the first
|
||||
<code class="parameter">len</code> bytes of the string.
|
||||
<code class="function">ne_buffer_zappend</code> must be passed a
|
||||
<code class="literal">NUL</code>-terminated string.</p><p>The <code class="function">ne_buffer_concat</code> function takes
|
||||
a variable-length argument list following <code class="parameter">str</code>;
|
||||
each argument must be a <em class="type">char *</em> pointer to a
|
||||
<code class="literal">NUL</code>-terminated string. A <code class="literal">NULL</code> pointer must be given as the last
|
||||
argument to mark the end of the list. The strings (including
|
||||
<code class="parameter">str</code>) are appended to the buffer in the order
|
||||
given. None of the strings passed to
|
||||
<code class="function">ne_buffer_concat</code> are modified.</p></div><div class="refsect1" title="Examples"><a name="id333692"></a><h2>Examples</h2><p>The following code will output "<code class="literal">Hello, world.
|
||||
And goodbye.</code>".</p><pre class="programlisting">ne_buffer *buf = ne_buffer_create();
|
||||
ne_buffer_zappend(buf, "Hello");
|
||||
ne_buffer_concat(buf, ", world. ", "And ", "goodbye.", NULL);
|
||||
puts(buf->data);
|
||||
ne_buffer_destroy(buf);</pre></div><div class="refsect1" title="See also"><a name="id333714"></a><h2>See also</h2><p><a class="xref" href="refbuf.html#ne_buffer">ne_buffer</a>, <a class="xref" href="refbufcr.html#ne_buffer_create">ne_buffer_create</a>,
|
||||
<a class="xref" href="refbufdest.html#ne_buffer_destroy">ne_buffer_destroy</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refbuf.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="refbufutil.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_buffer </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_buffer_clear</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,7 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_buffer_create</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refbufutil.html" title="ne_buffer_clear"><link rel="next" href="refbufdest.html" title="ne_buffer_destroy"></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">ne_buffer_create</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refbufutil.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refbufdest.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_buffer_create"><a name="refbufcr"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_buffer_create, ne_buffer_ncreate — create a string buffer</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_alloc.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_buffer *<b class="fsfunc">ne_buffer_create</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_buffer *<b class="fsfunc">ne_buffer_ncreate</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id334514"></a><h2>Description</h2><p><code class="function">ne_buffer_create</code> creates a new
|
||||
buffer object, with an implementation-defined initial size.
|
||||
<code class="function">ne_buffer_ncreate</code> creates an
|
||||
<em class="type">ne_buffer</em> where the minimum initial size is given in the
|
||||
<code class="parameter">size</code> parameter. The buffer created will
|
||||
contain the empty string (<code class="literal">""</code>).</p></div><div class="refsect1" title="Return value"><a name="id334547"></a><h2>Return value</h2><p>Both functions return a pointer to a new buffer object,
|
||||
and never <code class="literal">NULL</code>.</p></div><div class="refsect1" title="See also"><a name="id334562"></a><h2>See also</h2><p><a class="xref" href="refbuf.html#ne_buffer">ne_buffer</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refbufutil.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="refbufdest.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_buffer_clear </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_buffer_destroy</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,17 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_buffer_destroy</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refbufcr.html" title="ne_buffer_create"><link rel="next" href="referr.html" title="ne_get_error"></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">ne_buffer_destroy</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refbufcr.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="referr.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_buffer_destroy"><a name="refbufdest"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_buffer_destroy, ne_buffer_finish — destroy a buffer object</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_destroy</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_buffer_finish</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id334814"></a><h2>Description</h2><p><code class="function">ne_buffer_destroy</code> frees all memory
|
||||
associated with the buffer. <code class="function">ne_buffer_finish</code>
|
||||
frees the buffer structure, but not the actual string stored in the
|
||||
buffer, which is returned and must be <code class="function">free</code>()d by
|
||||
the caller.</p><p>Any use of the buffer object after calling either of these
|
||||
functions gives undefined behaviour.</p></div><div class="refsect1" title="Return value"><a name="id334844"></a><h2>Return value</h2><p><code class="function">ne_buffer_finish</code> returns the
|
||||
<code class="function">malloc</code>-allocated string stored in the buffer.</p></div><div class="refsect1" title="Examples"><a name="id334862"></a><h2>Examples</h2><p>An example use of <code class="function">ne_buffer_finish</code>;
|
||||
the <code class="function">duplicate</code> function returns a string made up of
|
||||
<code class="parameter">n</code> copies of <code class="parameter">str</code>:</p><pre class="programlisting">static char *duplicate(int n, const char *str)
|
||||
{
|
||||
ne_buffer *buf = ne_buffer_create();
|
||||
while (n--) {
|
||||
ne_buffer_zappend(buf, str);
|
||||
}
|
||||
return ne_buffer_finish(buf);
|
||||
}</pre></div><div class="refsect1" title="See also"><a name="id334900"></a><h2>See also</h2><p><a class="xref" href="refbuf.html#ne_buffer">ne_buffer</a>, <a class="xref" href="refbufcr.html#ne_buffer_create">ne_buffer_create</a>,
|
||||
<a class="xref" href="refbufapp.html#ne_buffer_zappend">ne_buffer_zappend</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refbufcr.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="referr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_buffer_create </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_get_error</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,11 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_buffer_clear</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refbufapp.html" title="ne_buffer_append"><link rel="next" href="refbufcr.html" title="ne_buffer_create"></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">ne_buffer_clear</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refbufapp.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refbufcr.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_buffer_clear"><a name="refbufutil"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_buffer_clear, ne_buffer_grow, ne_buffer_altered — clear, grow, or mark as altered a string buffer</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_clear</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_altered</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_buffer_grow</b>(</code></td><td>ne_buffer *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id334158"></a><h2>Description</h2><p>The <code class="function">ne_buffer_clear</code> function sets
|
||||
the string stored in <code class="parameter">buf</code> to be the empty string
|
||||
(<code class="literal">""</code>).</p><p>The <code class="function">ne_buffer_altered</code> function must
|
||||
be used after the string stored in the buffer
|
||||
<code class="parameter">buf</code> is modified by directly rather than using
|
||||
<a class="xref" href="refbufapp.html#ne_buffer_append">ne_buffer_append</a>, <a class="xref" href="refbufapp.html#ne_buffer_zappend">ne_buffer_zappend</a>
|
||||
or <a class="xref" href="refbufapp.html#ne_buffer_concat">ne_buffer_concat</a>.</p><p>The <code class="function">ne_buffer_grow</code> function
|
||||
ensures that at least <code class="parameter">size</code> bytes are allocated
|
||||
for the string; this can be used if a large amount of data is going to
|
||||
be appended to the buffer and may result in more efficient memory
|
||||
allocation.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refbufapp.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="refbufcr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_buffer_append </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_buffer_create</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,33 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_cert_identity</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsockinit.html" title="ne_sock_init"><link rel="next" href="refsslcert2.html" title="ne_ssl_cert_cmp"></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">ne_ssl_cert_identity</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsockinit.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsslcert2.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_cert_identity"><a name="refcert"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_cert_identity, ne_ssl_cert_signedby, ne_ssl_cert_issuer, ne_ssl_cert_subject — functions to access certificate properties</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_ssl.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_ssl_cert_identity</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_ssl_certificate *<b class="fsfunc">ne_ssl_cert_signedby</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_ssl_dname *<b class="fsfunc">ne_ssl_cert_subject</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_ssl_dname *<b class="fsfunc">ne_ssl_cert_issuer</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id344226"></a><h2>Description</h2><p>The function <code class="function">ne_ssl_cert_identity</code>
|
||||
retrieves the <span class="quote">“<span class="quote">identity</span>”</span> of a certificate; for an
|
||||
SSL server certificate, this will be the hostname for which the
|
||||
certificate was issued. In PKI parlance, the identity is the
|
||||
<span class="emphasis"><em>common name</em></span> attribute of the distinguished name of
|
||||
the certificate subject.</p><p>The functions <code class="function">ne_ssl_cert_subject</code> and
|
||||
<code class="function">ne_ssl_cert_issuer</code> can be used to access the
|
||||
objects representing the distinguished name of the subject and of
|
||||
the issuer of a certificate, respectively.</p><p>If a certificate object is part of a certificate chain, then
|
||||
<code class="function">ne_ssl_cert_signedby</code> can be used to find the
|
||||
certificate which signed a particular certificate. For a
|
||||
self-signed certificate or a certificate for which the full chain
|
||||
is not available, this function will return <code class="literal">NULL</code>.</p></div><div class="refsect1" title="Return value"><a name="id344279"></a><h2>Return value</h2><p><code class="function">ne_ssl_cert_issuer</code> and
|
||||
<code class="function">ne_ssl_cert_subject</code> are guaranteed to never
|
||||
return <code class="literal">NULL</code>. <code class="function">ne_ssl_cert_identity</code> may
|
||||
return <code class="literal">NULL</code> if the certificate has no specific
|
||||
<span class="quote">“<span class="quote">identity</span>”</span>. <code class="function">ne_ssl_cert_signedby</code>
|
||||
may return <code class="literal">NULL</code> as covered above.</p></div><div class="refsect1" title="Examples"><a name="id344328"></a><h2>Examples</h2><p>The following function could be used to display information
|
||||
about a given certificate:</p><pre class="programlisting">void dump_cert(const ne_ssl_certificate *cert) {
|
||||
const char *id = ne_ssl_cert_identity(cert);
|
||||
char *dn;
|
||||
|
||||
if (id)
|
||||
printf("Certificate was issued for '%s'.\n", id);
|
||||
|
||||
dn = ne_ssl_readable_dname(ne_ssl_cert_subject(cert));
|
||||
printf("Subject: %s\n", dn);
|
||||
free(dn);
|
||||
|
||||
dn = ne_ssl_readable_dname(ne_ssl_cert_issuer(cert));
|
||||
printf("Issuer: %s\n", dn);
|
||||
free(dn);
|
||||
}</pre></div><div class="refsect1" title="See also"><a name="id344346"></a><h2>See also</h2><p><a class="xref" href="refsslcert2.html#ne_ssl_cert_cmp">ne_ssl_cert_cmp</a>, <a class="xref" href="refssldname.html#ne_ssl_readable_dname">ne_ssl_readable_dname</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsockinit.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="refsslcert2.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_sock_init </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_cert_cmp</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,55 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_client_cert</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsslvfy.html" title="ne_ssl_set_verify"><link rel="next" href="refstatus.html" title="ne_status"></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">ne_ssl_client_cert</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsslvfy.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refstatus.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_client_cert"><a name="refclicert"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_clicert_read, ne_ssl_clicert_name, ne_ssl_clicert_encrypted, ne_ssl_clicert_decrypt, ne_ssl_clicert_owner, ne_ssl_clicert_free — SSL client certificate handling</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_ssl.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_ssl_client_cert *<b class="fsfunc">ne_ssl_clicert_read</b>(</code></td><td>const char *<var class="pdparam">filename</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_ssl_clicert_name</b>(</code></td><td>const ne_ssl_client_cert *<var class="pdparam">ccert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_ssl_clicert_encrypted</b>(</code></td><td>const ne_ssl_client_cert *<var class="pdparam">ccert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_ssl_clicert_decrypt</b>(</code></td><td>ne_ssl_client_cert *<var class="pdparam">ccert</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">password</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_ssl_certificate *<b class="fsfunc">ne_ssl_clicert_owner</b>(</code></td><td>const ne_ssl_client_cert *<var class="pdparam">ccert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_ssl_clicert_free</b>(</code></td><td>ne_ssl_client_cert *<var class="pdparam">ccert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id347064"></a><h2>Description</h2><p>The <code class="function">ne_ssl_clicert_read</code> function reads
|
||||
a <em class="firstterm">client certificate</em> from a
|
||||
PKCS#12-formatted file, and returns an
|
||||
<em class="type">ne_ssl_client_cert</em> object. If the client
|
||||
certificate is encrypted, it must be decrypted before it is used.
|
||||
An <em class="type">ne_ssl_client_cert</em> object holds a client
|
||||
certificate and the associated private key, not just a
|
||||
certificate; the term "<em class="glossterm">client certificate</em>"
|
||||
will used to refer to this pair.</p><p>A client certificate can be in one of two states:
|
||||
<span class="emphasis"><em>encrypted</em></span> or <span class="emphasis"><em>decrypted</em></span>.
|
||||
The <code class="function">ne_ssl_clicert_encrypted</code> function will
|
||||
return non-zero if the client certificate is in the
|
||||
<span class="emphasis"><em>encrypted</em></span> state. A client certificate object
|
||||
returned by <code class="function">ne_ssl_clicert_read</code> may be
|
||||
initially in either state, depending on whether the file was
|
||||
encrypted or not.</p><p><code class="function">ne_ssl_clicert_decrypt</code> can be used to
|
||||
decrypt a client certificate using the appropriate password. This
|
||||
function must only be called if the object is in the
|
||||
<span class="emphasis"><em>encrypted</em></span> state; if decryption fails, the
|
||||
certificate state does not change, so decryption can be attempted
|
||||
more than once using different passwords.</p><p>A client certificate can be given a "friendly name" when it
|
||||
is created; <code class="function">ne_ssl_clicert_name</code> will return
|
||||
this name (or <code class="literal">NULL</code> if no friendly name was specified).
|
||||
<code class="function">ne_ssl_clicert_name</code> can be used when the
|
||||
client certificate is in either the encrypted or decrypted state,
|
||||
and will return the same string for the lifetime of the
|
||||
object.</p><p>The function <code class="function">ne_ssl_clicert_owner</code>
|
||||
returns the certificate part of the client certificate; it must
|
||||
only be called if the client certificate is in the
|
||||
<span class="emphasis"><em>decrypted</em></span> state.</p><p>When the client certificate is no longer needed, the
|
||||
<code class="function">ne_ssl_clicert_free</code> function should be used
|
||||
to destroy the object.</p></div><div class="refsect1" title="Return value"><a name="id347174"></a><h2>Return value</h2><p><code class="function">ne_ssl_clicert_read</code> returns a client
|
||||
certificate object, or <code class="literal">NULL</code> if the file could not be read.
|
||||
<code class="function">ne_ssl_clicert_encrypted</code> returns zero if the
|
||||
object is in the decrypted state, or non-zero if it is in the
|
||||
encrypted state. <code class="function">ne_ssl_clicert_name</code> returns
|
||||
a <code class="literal">NUL</code>-terminated friendly name string, or <code class="literal">NULL</code>.
|
||||
<code class="function">ne_ssl_clicert_owner</code> returns a certificate
|
||||
object.</p></div><div class="refsect1" title="Examples"><a name="id347220"></a><h2>Examples</h2><p>The following code reads a client certificate and decrypts
|
||||
it if necessary, then loads it into an HTTP session.</p><pre class="programlisting">ne_ssl_client_cert *ccert;
|
||||
|
||||
ccert = ne_ssl_clicert_read("/path/to/client.p12");
|
||||
|
||||
if (ccert == NULL) {
|
||||
/* handle error... */
|
||||
} else if (ne_ssl_clicert_encrypted(ccert)) {
|
||||
char *password = prompt_for_password();
|
||||
|
||||
if (ne_ssl_clicert_decrypt(ccert, password)) {
|
||||
/* could not decrypt! handle error... */
|
||||
}
|
||||
}
|
||||
|
||||
ne_ssl_set_clicert(sess, ccert);
|
||||
</pre></div><div class="refsect1" title="See also"><a name="id347239"></a><h2>See also</h2><p><a class="xref" href="refsslcertio.html#ne_ssl_cert_read">ne_ssl_cert_read</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsslvfy.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="refstatus.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_set_verify </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_status</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,32 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon-config</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refneon.html" title="neon"><link rel="next" href="refresolve.html" title="ne_addr_resolve"></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-config</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refneon.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refresolve.html">Next</a></td></tr></table><hr></div><div class="refentry" title="neon-config"><a name="refconfig"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>neon-config — script providing information about installed copy
|
||||
of neon library</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">neon-config</code> [<code class="option">--prefix</code>] [[<code class="option">--cflags</code>] | [<code class="option">--libs</code>] | [<code class="option">--la-file</code>] | [<code class="option">--support</code> <em class="replaceable"><code>feature</code></em>] | [<code class="option">--help</code>] | [<code class="option">--version</code>]]</p></div></div><div class="refsect1" title="Description"><a name="id331813"></a><h2>Description</h2><p>The <span class="command"><strong>neon-config</strong></span> script provides
|
||||
information about an installed copy of the neon library. The
|
||||
<code class="option">--cflags</code> and <code class="option">--libs</code> options instruct
|
||||
how to compile and link an application against the library; the
|
||||
<code class="option">--version</code> and <code class="option">--support</code> options can
|
||||
help determine whether the library meets the applications
|
||||
requirements.</p></div><div class="refsect1" title="Options"><a name="id331843"></a><h2>Options</h2><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="option">--cflags</code></span></p></td><td>Print the flags which should be passed to
|
||||
the C compiler when compiling object files, when the object files use
|
||||
neon header files.</td></tr><tr><td><p><span class="term"><code class="option">--libs</code></span></p></td><td>Print the flags which should be passed to
|
||||
the linker when linking an application which uses the neon
|
||||
library</td></tr><tr><td><p><span class="term"><code class="option">--la-file</code></span></p></td><td>Print the location of the libtool library
|
||||
script, <code class="filename">libneon.la</code>, which can be used to link against
|
||||
neon by applications using libtool.</td></tr><tr><td><p><span class="term"><code class="option">--version</code></span></p></td><td>Print the version of the library</td></tr><tr><td><p><span class="term"><code class="option">--prefix</code> <em class="replaceable"><code>dir</code></em></span></p></td><td>If <em class="replaceable"><code>dir</code></em> is given; relocate output of
|
||||
<code class="option">--cflags</code> and <code class="option">--libs</code> as if neon was
|
||||
installed in given prefix directory. Otherwise, print the
|
||||
installation prefix of the library.</td></tr><tr><td><p><span class="term"><code class="option">--support</code> <em class="replaceable"><code>feature</code></em></span></p></td><td>The script exits with success if
|
||||
<em class="replaceable"><code>feature</code></em> is supported by the
|
||||
library.</td></tr><tr><td><p><span class="term"><code class="option">--help</code></span></p></td><td>Print help message; includes list of known
|
||||
features and whether they are supported or not.</td></tr></tbody></table></div></div><div class="refsect1" title="Example"><a name="example"></a><h2>Example</h2><p>Below is a Makefile fragment which could be used to
|
||||
build an application against an installed neon library, when the
|
||||
<span class="command"><strong>neon-config</strong></span> script can be found in
|
||||
<code class="envar">$PATH</code>.</p><pre class="programlisting">CFLAGS = `neon-config --cflags`
|
||||
LIBS = `neon-config --libs`
|
||||
OBJECTS = myapp.o
|
||||
TARGET = myapp
|
||||
|
||||
$(TARGET): $(OBJECTS)
|
||||
$(CC) $(LDFLAGS) -o $(TARGET) $(OBJECTS) $(LIBS)
|
||||
|
||||
myapp.o: myapp.c
|
||||
$(CC) $(CFLAGS) -c myapp.c -o myapp.o</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refneon.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="refresolve.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_addr_resolve</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,18 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_get_error</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refbufdest.html" title="ne_buffer_destroy"><link rel="next" href="refgetst.html" title="ne_get_status"></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">ne_get_error</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refbufdest.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refgetst.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_get_error"><a name="referr"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_get_error, ne_set_error — error handling for HTTP sessions</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_session.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_get_error</b>(</code></td><td>ne_sesssion *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_error</b>(</code></td><td>ne_sesssion *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id335230"></a><h2>Description</h2><p>The session error string is used to store any
|
||||
human-readable error information associated with any errors which
|
||||
occur whilst using the HTTP session.</p><p>The <code class="function">ne_get_error</code> function returns
|
||||
the current session error string. This string persists only
|
||||
until it is changed by a subsequent operation on the session.
|
||||
If localisation was enabled at build time, and if necessary
|
||||
enabled at run-time if necessary using <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a>, the returned string may have been
|
||||
translated into the user's current locale.</p><p>The <code class="function">ne_set_error</code> function can be
|
||||
used to set a new session error string, using a
|
||||
<code class="function">printf</code>-style format string
|
||||
interface.</p></div><div class="refsect1" title="Return value"><a name="id335270"></a><h2>Return value</h2><p><code class="function">ne_set_error</code> returns a constant
|
||||
<code class="literal">NUL</code>-terminated string. In the default English locale, the
|
||||
returned string will <span class="emphasis"><em>not</em></span> have a
|
||||
terminating <span class="quote">“<span class="quote">.</span>”</span> period character.</p></div><div class="refsect1" title="Examples"><a name="id335297"></a><h2>Examples</h2><p>Retrieve the current error string:</p><pre class="programlisting">ne_session *sess = ne_session_create(...);
|
||||
...
|
||||
printf("Error was: %s\n", ne_get_error(sess));</pre><p>Set a new error string:</p><pre class="programlisting">ne_session *sess = ne_session_create(...);
|
||||
...
|
||||
ne_set_error(sess, "Response missing header %s", "somestring");</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refbufdest.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="refgetst.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_buffer_destroy </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_get_status</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,10 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_has_support</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refgetst.html" title="ne_get_status"><link rel="next" href="refi18n.html" title="ne_i18n_init"></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">ne_has_support</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refgetst.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refi18n.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_has_support"><a name="reffeat"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_has_support — determine feature support status</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_utils.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_has_support</b>(</code></td><td>int <var class="pdparam">feature</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id335870"></a><h2>Description</h2><p>The <code class="function">ne_has_support</code> function can be used
|
||||
to determine whether a particular optional feature, given by the
|
||||
feature code <code class="parameter">feature</code>, is supported. The
|
||||
following feature codes are available:
|
||||
|
||||
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="constant">NE_FEATURE_SSL</code></span></p></td><td>Indicates support for SSL/TLS</td></tr><tr><td><p><span class="term"><code class="constant">NE_FEATURE_ZLIB</code></span></p></td><td>Indicates support for compressed responses</td></tr><tr><td><p><span class="term"><code class="constant">NE_FEATURE_IPV6</code></span></p></td><td>Indicates support for IPv6</td></tr><tr><td><p><span class="term"><code class="constant">NE_FEATURE_LFS</code></span></p></td><td>Indicates support for large files</td></tr><tr><td><p><span class="term"><code class="constant">NE_FEATURE_SOCKS</code></span></p></td><td>Indicates support for SOCKSv5</td></tr><tr><td><p><span class="term"><code class="constant">NE_FEATURE_TS_SSL</code></span></p></td><td>Indicates support for thread-safe SSL
|
||||
initialization — see <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a></td></tr></tbody></table></div><p>
|
||||
|
||||
</p></div><div class="refsect1" title="Return value"><a name="id335981"></a><h2>Return value</h2><p><code class="function">ne_has_support</code> returns non-zero if
|
||||
the given feature is supported, or zero otherwise.</p></div><div class="refsect1" title="See also"><a name="id335995"></a><h2>See also</h2><p><a class="xref" href="refvers.html" title="ne_version_match"><span class="refentrytitle">ne_version_match</span></a>, <a class="xref" href="refsockinit.html" title="ne_sock_init"><span class="refentrytitle">ne_sock_init</span></a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refgetst.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="refi18n.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_get_status </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_i18n_init</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,13 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_get_status</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="referr.html" title="ne_get_error"><link rel="next" href="reffeat.html" title="ne_has_support"></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">ne_get_status</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="referr.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="reffeat.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_get_status"><a name="refgetst"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_get_status — retrieve HTTP response status for request</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_status *<b class="fsfunc">ne_get_status</b>(</code></td><td>const ne_request *<var class="pdparam">request</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id335595"></a><h2>Description</h2><p>The <code class="function">ne_get_status</code> function returns
|
||||
a pointer to the HTTP status object giving the result of a request.
|
||||
The object returned only becomes valid once the request has been
|
||||
<span class="emphasis"><em>successfully</em></span> dispatched (the return value of
|
||||
<code class="function">ne_request_dispatch</code> or
|
||||
<code class="function">ne_begin_request</code> was zero). The object remains
|
||||
valid until the associated request object is destroyed.</p></div><div class="refsect1" title="See also"><a name="id335625"></a><h2>See also</h2><p><a class="xref" href="refstatus.html#ne_status">ne_status</a>, <a class="xref" href="refreq.html#ne_request_create">ne_request_create</a></p></div><div class="refsect1" title="Example"><a name="id335641"></a><h2>Example</h2><p>Display the response status code of applying the
|
||||
<code class="literal">HEAD</code> method to some resource.</p><pre class="programlisting">ne_request *req = ne_request_create(sess, "HEAD", "/foo/bar");
|
||||
if (ne_request_dispatch(req))
|
||||
/* handle errors... */
|
||||
else
|
||||
printf("Response status code was %d\n", ne_get_status(req)->code);
|
||||
ne_request_destroy(req);</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="referr.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="reffeat.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_get_error </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_has_support</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,18 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_i18n_init</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="reffeat.html" title="ne_has_support"><link rel="next" href="refiaddr.html" title="ne_iaddr_make"></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">ne_i18n_init</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="reffeat.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refiaddr.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_i18n_init"><a name="refi18n"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_i18n_init — functions to initialize internationalization support</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_i18n.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_i18n_init</b>(</code></td><td>const char *<var class="pdparam">encoding</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id336304"></a><h2>Description</h2><p>The <code class="function">ne_i18n_init</code> function can be used
|
||||
to enable support for translated messages in the neon library.
|
||||
The <code class="parameter">encoding</code> parameter, if non-<code class="literal">NULL</code>,
|
||||
specifies the character encoding required for generated translated
|
||||
string. If it is <code class="literal">NULL</code>, the appropriate character encoding for
|
||||
the process locale will be used.</p><p>This call is only strictly necessary if either:
|
||||
|
||||
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem">neon has been installed into a different
|
||||
prefix than the <code class="literal">gettext</code> implementation on
|
||||
which it depends for i18n purposes, or</li><li class="listitem">the caller requires that translated messages
|
||||
are in a particular character encoding.</li></ol></div><p>If <code class="function">ne_i18n_init</code> is never called, the
|
||||
message catalogs will not be found if case (a) applies (and so
|
||||
English error messages will be used), and will use the default
|
||||
character encoding specified by the process locale. The library
|
||||
will otherwise operate correctly.</p><p>Note that the encoding used is a process-global setting and
|
||||
so results may be unexpected if other users of neon within the
|
||||
process call <code class="function">ne_i18n_init</code> with a different
|
||||
encoding parameter.</p></div><div class="refsect1" title="See also"><a name="id336383"></a><h2>See also</h2><p><a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reffeat.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="refiaddr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_has_support </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_iaddr_make</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,37 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_iaddr_make</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refi18n.html" title="ne_i18n_init"><link rel="next" href="refalloc.html" title="ne_malloc"></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">ne_iaddr_make</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refi18n.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refalloc.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_iaddr_make"><a name="refiaddr"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_iaddr_make, ne_iaddr_cmp, ne_iaddr_print, ne_iaddr_typeof, ne_iaddr_free — functions to manipulate and compare network addresses</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_socket.h>
|
||||
|
||||
typedef enum {
|
||||
ne_iaddr_ipv4 = 0,
|
||||
ne_iaddr_ipv6
|
||||
} <em class="type">ne_iaddr_type</em>;</pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_inet_addr *<b class="fsfunc">ne_iaddr_make</b>(</code></td><td>ne_iaddr_type <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const unsigned char *<var class="pdparam">raw</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_iaddr_cmp</b>(</code></td><td>const ne_inet_addr *<var class="pdparam">ia1</var>, </td></tr><tr><td> </td><td>const ne_inet_addr *<var class="pdparam">ia2</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_iaddr_print</b>(</code></td><td>const ne_inet_addr *<var class="pdparam">ia</var>, </td></tr><tr><td> </td><td>char *<var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">bufsiz</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_iaddr_type <b class="fsfunc">ne_iaddr_typeof</b>(</code></td><td>const ne_inet_addr *<var class="pdparam">ia</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_iaddr_free</b>(</code></td><td>const ne_inet_addr *<var class="pdparam">ia</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id336750"></a><h2>Description</h2><p><code class="function">ne_iaddr_make</code> creates an
|
||||
<em class="type">ne_inet_addr</em> object from a raw binary network
|
||||
address; for instance the four bytes <code class="literal">0x7f 0x00 0x00
|
||||
0x01</code> represent the IPv4 address
|
||||
<code class="literal">127.0.0.1</code>. The object returned is suitable for
|
||||
passing to <code class="function">ne_sock_connect</code>. A binary IPv4
|
||||
address contains four bytes; a binary IPv6 address contains
|
||||
sixteen bytes; addresses passed must be in network byte
|
||||
order.</p><p><code class="function">ne_iaddr_cmp</code> can be used to compare two
|
||||
network addresses; returning zero only if they are identical. The
|
||||
addresses need not be of the same address type; if the addresses
|
||||
are not of the same type, the return value is guaranteed to be
|
||||
non-zero.</p><p><code class="function">ne_iaddr_print</code> can be used to print the
|
||||
human-readable string representation of a network address into a
|
||||
buffer, for instance the string
|
||||
<code class="literal">"127.0.0.1"</code>.</p><p><code class="function">ne_iaddr_typeof</code> returns the type of the
|
||||
given network address.</p><p><code class="function">ne_iaddr_free</code> releases the memory
|
||||
associated with a network address object.</p></div><div class="refsect1" title="Return value"><a name="id336823"></a><h2>Return value</h2><p><code class="function">ne_iaddr_make</code> returns <code class="literal">NULL</code> if the
|
||||
address type passed is not supported (for instance on a platform
|
||||
which does not support IPv6).</p><p><code class="function">ne_iaddr_print</code> returns the
|
||||
<code class="parameter">buffer</code> pointer, and never <code class="literal">NULL</code>.</p></div><div class="refsect1" title="Examples"><a name="id336861"></a><h2>Examples</h2><p>The following example connects a socket to port 80 at the
|
||||
address <code class="literal">127.0.0.1</code>.</p><pre class="programlisting">unsigned char addr[] = "\0x7f\0x00\0x00\0x01";
|
||||
ne_inet_addr *ia;
|
||||
|
||||
ia = ne_iaddr_make(ne_iaddr_ipv4, addr);
|
||||
if (ia != NULL) {
|
||||
ne_socket *sock = ne_sock_connect(ia, 80);
|
||||
ne_iaddr_free(ia);
|
||||
/* ... */
|
||||
} else {
|
||||
/* ... */
|
||||
}</pre></div><div class="refsect1" title="See also"><a name="id336883"></a><h2>See also</h2><p><a class="xref" href="refresolve.html#ne_addr_resolve">ne_addr_resolve</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refi18n.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="refalloc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_i18n_init </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_malloc</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,113 @@
|
||||
<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.75.2"><link rel="home" 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" title="neon"><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" title="Description"><a name="id330539"></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 class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP
|
||||
<span class="emphasis"><em>request</em></span>, created by <a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>. HTTP authentication is handled
|
||||
transparently for server and proxy servers, see <a class="xref" href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also
|
||||
included, see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1" title="Conventions"><a name="id330489"></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" title="Thread-safeness and global initialization"><a name="id330499"></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 SSL in the OpenSSL and GnuTLS
|
||||
libraries neon must be configured using the
|
||||
<code class="literal">--enable-threadsafe-ssl</code>; if this is done,
|
||||
locking callbacks will be registered by <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>; note that care must be exercised if
|
||||
neon is used in conjunction with another library which uses
|
||||
OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global
|
||||
initialization before use; notably:
|
||||
|
||||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">The <code class="literal">SIGPIPE</code> signal
|
||||
disposition must be set to <span class="emphasis"><em>ignored</em></span> or
|
||||
otherwise handled to avoid process termination when writing to a
|
||||
socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global
|
||||
initialization to load shared lookup
|
||||
tables.</li><li class="listitem">The Win32 socket library requires
|
||||
initialization before use.</li></ul></div><p>
|
||||
|
||||
The <a class="xref" 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. Applications
|
||||
wishing to perform all the necessary process-global initialization
|
||||
steps themselves may omit to call <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>
|
||||
(and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether
|
||||
these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary
|
||||
to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support
|
||||
for internationalization in neon.</p></div><div class="refsect2" title="Asynchronous signal safety"><a name="id330739"></a><h3>Asynchronous signal safety</h3><p>No function in neon is defined to be <span class="quote">“<span class="quote">async-signal safe</span>”</span> -
|
||||
that is, no function is safe to call from a signal handler. Any
|
||||
call into the neon library from a signal handler will have
|
||||
undefined behaviour - in other words, it may crash the
|
||||
process.</p></div><div class="refsect2" title="Functions using global state"><a name="id330755"></a><h3>Functions using global state</h3><p>Any function in neon may modify the
|
||||
<code class="literal">errno</code> global variable as a side-effect. Except
|
||||
where explicitly documented, the value of <code class="literal">errno</code>
|
||||
is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only
|
||||
functions which use or modify process-global state in neon are
|
||||
as follows:
|
||||
|
||||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>, <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a>, and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>, as
|
||||
described above</li><li class="listitem"><code class="function">ne_debug_init</code> and
|
||||
<code class="function">ne_debug</code>, if enabled at compile time; for
|
||||
debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for
|
||||
installing a process-global callback to be invoked on
|
||||
<code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2" title="Namespaces"><a name="id330830"></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><p><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></p></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><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and
|
||||
dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces
|
||||
used by the expat library.</td></tr><tr><td><p><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></p></td><td>Namespaces used by the libxml2 library; a
|
||||
relatively small number of symbols are used without these
|
||||
prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompres, adler32,
|
||||
zlib</span></p></td><td>Namespaces used by the zlib library; a
|
||||
relatively small number of symbols are used without these
|
||||
prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
|
||||
mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI
|
||||
library and dependencies thereof; a number of symbols lie
|
||||
outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois
|
||||
library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy
|
||||
library.</td></tr></tbody></table></div></div><div class="refsect2" title="Argument validation"><a name="id330960"></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" title="URI paths, WebDAV metadata"><a name="id330972"></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" title="User interaction"><a name="id330996"></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" title="Memory handling"><a name="id331017"></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 class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2" title="Callbacks and userdata"><a name="id331045"></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 class="refsect2" title="Large File Support"><a name="id331066"></a><h3>Large File Support</h3><p>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
|
||||
<code class="literal">off_t</code> type, where LFS support is
|
||||
available.</p><p>Some interfaces use the <code class="literal">ne_off_t</code> type,
|
||||
which is defined to be either <code class="literal">off_t</code> or
|
||||
<code class="literal">off64_t</code> according to whether LFS support is
|
||||
detected at build time. neon does not use or require the
|
||||
<code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1" title="See also"><a name="id331111"></a><h2>See also</h2><p><a class="xref" href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a class="xref" 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>
|
||||
@@ -0,0 +1,28 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_set_useragent</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refresphdr.html" title="ne_get_response_header"><link rel="next" href="refreqflags.html" title="ne_set_request_flag"></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">ne_set_useragent</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refresphdr.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refreqflags.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_set_useragent"><a name="refopts"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_set_useragent, ne_set_read_timeout, ne_set_connect_timeout, ne_get_scheme, ne_get_server_hostport — common properties for HTTP sessions</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_session.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_useragent</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">product</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_read_timeout</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">timeout</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_connect_timeout</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">timeout</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_get_scheme</b>(</code></td><td>ne_sesssion *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_get_server_hostport</b>(</code></td><td>ne_sesssion *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id341269"></a><h2>Description</h2><p>The <code class="literal">User-Agent</code> request header is used
|
||||
to identify the software which generated the request for statistical
|
||||
or debugging purposes. neon does not send a
|
||||
<code class="literal">User-Agent</code> header unless a call is made to the
|
||||
<code class="function">ne_set_useragent</code>.
|
||||
<code class="function">ne_set_useragent</code> must be passed a product string
|
||||
conforming to RFC2616's product token grammar; of the form
|
||||
<code class="literal">"Product/Version"</code>.</p><p>When neon reads from a socket, by default the read
|
||||
operation will time out after 60 seconds, and the request will fail
|
||||
giving an <span class="errorcode">NE_TIMEOUT</span> error. To configure this
|
||||
timeout interval, call <code class="function">ne_set_read_timeout</code> giving
|
||||
the desired number of seconds as the <code class="parameter">timeout</code>
|
||||
parameter.</p><p>When a connection is being established to a server,
|
||||
normally only the system's TCP timeout handling will apply.
|
||||
To configure a specific (and probably shorter) timeout, the
|
||||
<code class="function">ne_set_connect_timeout</code> can be used,
|
||||
giving the desired number of seconds as the
|
||||
<code class="parameter">timeout</code> parameter. If
|
||||
<code class="literal">0</code> is passed, then the default behaviour of
|
||||
using the system TCP timeout will be used.</p><p>The scheme used to initially create the session will be
|
||||
returned by <code class="function">ne_get_scheme</code>.</p><p>The hostport pair with which the session is associated
|
||||
will be returned by the
|
||||
<code class="function">ne_get_server_hostport</code>; for example
|
||||
<code class="literal">www.example.com:8080</code>. Note that the
|
||||
<code class="literal">:port</code> will be omitted if the default port
|
||||
for the scheme is used.</p></div><div class="refsect1" title="Examples"><a name="id341378"></a><h2>Examples</h2><p>Set a user-agent string:</p><pre class="programlisting">ne_session *sess = ne_session_create(...);
|
||||
ne_set_useragent(sess, "MyApplication/2.1");</pre><p>Set a 30 second read timeout:</p><pre class="programlisting">ne_session *sess = ne_session_create(...);
|
||||
ne_set_read_timeout(sess, 30);</pre></div><div class="refsect1" title="See also"><a name="id341403"></a><h2>See also</h2><p><a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>, <a class="xref" href="refsessflags.html#ne_set_session_flag">ne_set_session_flag</a>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refresphdr.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="refreqflags.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_get_response_header </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_set_request_flag</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,46 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_request_create</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsessflags.html" title="ne_set_session_flag"><link rel="next" href="refreqhdr.html" title="ne_add_request_header"></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">ne_request_create</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsessflags.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refreqhdr.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_request_create"><a name="refreq"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_request_create, ne_request_dispatch, ne_request_destroy — low-level HTTP request handling</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_request *<b class="fsfunc">ne_request_create</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">method</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">path</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_request_dispatch</b>(</code></td><td>ne_request *<var class="pdparam">req</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_request_destroy</b>(</code></td><td>ne_request *<var class="pdparam">req</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id339290"></a><h2>Description</h2><p>An HTTP request, represented by the
|
||||
<em class="type">ne_request</em> type, specifies that some operation is to be
|
||||
performed on some resource. The
|
||||
<code class="function">ne_request_create</code> function creates a request
|
||||
object, specifying the operation in the <code class="parameter">method</code>
|
||||
parameter. The location of the resource is determined by the server in
|
||||
use for the session given by the <code class="parameter">sess</code>
|
||||
parameter, combined with the <code class="parameter">path</code> parameter.</p><p>The <code class="parameter">path</code> string used must conform to the
|
||||
<code class="literal">abs_path</code> definition given in RFC2396, with an
|
||||
optional "?query" part, and must be URI-escaped by the caller (for
|
||||
instance, using <code class="function">ne_path_escape</code>). If the string
|
||||
comes from an untrusted source, failure to perform URI-escaping
|
||||
results in a security vulnerability.</p><p>To dispatch a request, and process the response, the
|
||||
<code class="function">ne_request_dispatch</code> function can be used. An
|
||||
alternative is to use the (more complex, but more flexible)
|
||||
combination of the <code class="function">ne_begin_request</code>,
|
||||
<code class="function">ne_end_request</code>, and
|
||||
<code class="function">ne_read_response_block</code> functions; see
|
||||
<code class="function">ne_begin_request</code>.</p><p>To add extra headers in the request, the functions <a class="xref" href="refreqhdr.html#ne_add_request_header">ne_add_request_header</a> and <a class="xref" href="refreqhdr.html#ne_print_request_header">ne_print_request_header</a> can be used. To include a message
|
||||
body with the request, one of the functions
|
||||
<code class="function">ne_set_request_body_buffer</code>, <a class="xref" href="refreqbody.html#ne_set_request_body_fd">ne_set_request_body_fd</a>, or
|
||||
<code class="function">ne_set_request_body_provider</code> can be used.</p><p>The return value of
|
||||
<code class="function">ne_request_dispatch</code> indicates merely whether the
|
||||
request was sent and the response read successfully. To discover the
|
||||
result of the operation, <a class="xref" href="refgetst.html#ne_get_status">ne_get_status</a>, along with
|
||||
any processing of the response headers and message body.</p><p>A request can only be dispatched once: calling
|
||||
<code class="function">ne_request_dispatch</code> more than once on a
|
||||
single <em class="type">ne_request</em> object produces undefined
|
||||
behaviour. Once all processing associated with the request
|
||||
object is complete, use the
|
||||
<code class="function">ne_request_destroy</code> function to destroy
|
||||
the resources associated with it. Any subsequent use of the
|
||||
request object produces undefined behaviour.</p><p>If a request is being using a non-idempotent method such
|
||||
as <code class="literal">POST</code>, the
|
||||
<code class="literal">NE_REQFLAG_IDEMPOTENT</code> flag should be
|
||||
disabled; see <a class="xref" href="refreqflags.html#ne_set_request_flag">ne_set_request_flag</a>.</p></div><div class="refsect1" title="Return value"><a name="id339456"></a><h2>Return value</h2><p>The <code class="function">ne_request_create</code> function
|
||||
returns a pointer to a request object (and never <code class="literal">NULL</code>).</p><p>The <code class="function">ne_request_dispatch</code> function
|
||||
returns zero if the request was dispatched successfully, and a
|
||||
non-zero error code otherwise.</p></div><div class="refsect1" title="Errors"><a name="id339488"></a><h2>Errors</h2><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><span class="errorcode">NE_ERROR</span></span></p></td><td>Request failed (see session error string)</td></tr><tr><td><p><span class="term"><span class="errorcode">NE_LOOKUP</span></span></p></td><td>The DNS lookup for the server (or proxy server) failed.</td></tr><tr><td><p><span class="term"><span class="errorcode">NE_AUTH</span></span></p></td><td>Authentication failed on the server.</td></tr><tr><td><p><span class="term"><span class="errorcode">NE_PROXYAUTH</span></span></p></td><td>Authentication failed on the proxy server.</td></tr><tr><td><p><span class="term"><span class="errorcode">NE_CONNECT</span></span></p></td><td>A connection to the server could not be established.</td></tr><tr><td><p><span class="term"><span class="errorcode">NE_TIMEOUT</span></span></p></td><td>A timeout occurred while waiting for the server to respond.</td></tr></tbody></table></div></div><div class="refsect1" title="Example"><a name="id339587"></a><h2>Example</h2><p>An example of applying a <code class="literal">MKCOL</code>
|
||||
operation to the resource at the location
|
||||
<code class="literal">http://www.example.com/foo/bar/</code>:</p><pre class="programlisting">ne_session *sess = ne_session_create("http", "www.example.com", 80);
|
||||
ne_request *req = ne_request_create(sess, "MKCOL", "/foo/bar/");
|
||||
if (ne_request_dispatch(req)) {
|
||||
printf("Request failed: %s\n", ne_get_error(sess));
|
||||
}
|
||||
ne_request_destroy(req);</pre></div><div class="refsect1" title="See also"><a name="id339614"></a><h2>See also</h2><p><a class="xref" href="referr.html#ne_get_error">ne_get_error</a>, <a class="xref" href="referr.html#ne_set_error">ne_set_error</a>, <a class="xref" href="refgetst.html#ne_get_status">ne_get_status</a>, <a class="xref" href="refreqhdr.html#ne_add_request_header">ne_add_request_header</a>, <a class="xref" href="refreqbody.html#ne_set_request_body_buffer">ne_set_request_body_buffer</a>, <a class="xref" href="refreqflags.html#ne_set_request_flag">ne_set_request_flag</a>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsessflags.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="refreqhdr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_set_session_flag </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_add_request_header</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,17 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_set_request_body_buffer</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refreqflags.html" title="ne_set_request_flag"><link rel="next" href="refauth.html" title="ne_set_server_auth"></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">ne_set_request_body_buffer</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refreqflags.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refauth.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_set_request_body_buffer"><a name="refreqbody"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_set_request_body_buffer, ne_set_request_body_fd, ne_set_request_body_fd64 — include a message body with a request</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_request_body_buffer</b>(</code></td><td>ne_request *<var class="pdparam">req</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">buf</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">count</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_set_request_body_fd</b>(</code></td><td>ne_request *<var class="pdparam">req</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">fd</var>, </td></tr><tr><td> </td><td>off_t <var class="pdparam">begin</var>, </td></tr><tr><td> </td><td>off_t <var class="pdparam">length</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id342329"></a><h2>Description</h2><p>The <code class="function">ne_set_request_body_buffer</code>
|
||||
function specifies that a message body should be included with the
|
||||
body, which is stored in the <code class="parameter">count</code> bytes buffer
|
||||
<code class="parameter">buf</code>.</p><p>The <code class="function">ne_set_request_body_fd</code> function
|
||||
can be used to include a message body with a request which is read
|
||||
from a file descriptor. The body is read from the file descriptor
|
||||
<code class="parameter">fd</code>, which must be a associated with a seekable
|
||||
file (not a pipe, socket, or FIFO). <code class="parameter">count</code>
|
||||
bytes are read, beginning at offset <code class="parameter">begin</code>
|
||||
(hence, passing <code class="parameter">begin</code> as zero means the body is read
|
||||
from the beginning of the file).</p><p>For all the above functions, the source of the request
|
||||
body must survive until the request has been dispatched;
|
||||
neither the memory buffer passed to
|
||||
<code class="function">ne_set_request_body_buffer</code> nor the file
|
||||
descriptor passed to
|
||||
<code class="function">ne_set_request_body_fd</code> are copied
|
||||
internally.</p></div><div class="refsect1" title="See also"><a name="id342402"></a><h2>See also</h2><p><a class="xref" href="refreq.html#ne_request_create">ne_request_create</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refreqflags.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="refauth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_set_request_flag </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_set_server_auth</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,14 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_set_request_flag</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refopts.html" title="ne_set_useragent"><link rel="next" href="refreqbody.html" title="ne_set_request_body_buffer"></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">ne_set_request_flag</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refopts.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refreqbody.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_set_request_flag"><a name="refreqflags"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_set_request_flag, ne_get_request_flag — set and retrieve per-request flags</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_request_flag</b>(</code></td><td>ne_request *<var class="pdparam">req</var>, </td></tr><tr><td> </td><td>ne_request_flag <var class="pdparam">flag</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">value</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_get_request_flag</b>(</code></td><td>ne_request *<var class="pdparam">req</var>, </td></tr><tr><td> </td><td>ne_request_flag <var class="pdparam">flag</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id341884"></a><h2>Description</h2><p>The <code class="function">ne_set_request_flag</code> function
|
||||
enables or disables a per-request flag. Passing a non-zero
|
||||
<code class="parameter">value</code> argument enables the flag, and zero
|
||||
disables it.</p><p>The following flags are defined:</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="constant">NE_REQFLAG_EXPECT100</code></span></p></td><td>enable this flag to use the "Expect:
|
||||
100-continue" feature of HTTP/1.1, which allows the
|
||||
server to process request headers without reading the
|
||||
entire request body. This saves time and bandwidth if
|
||||
the server gives an authentication challenge (requiring
|
||||
the request to be resent), but has interoperability
|
||||
problems with some older servers.</td></tr><tr><td><p><span class="term"><code class="constant">NE_REQFLAG_IDEMPOTENT</code></span></p></td><td>disable this flag if the request uses a
|
||||
non-idempotent method such as
|
||||
<code class="literal">POST</code></td></tr></tbody></table></div></div><div class="refsect1" title="Return value"><a name="id341947"></a><h2>Return value</h2><p>The <code class="function">ne_get_request_flag</code> function returns
|
||||
zero if a flag is disabled, less than zero if the flag is not
|
||||
supported, or greater than zero if the flag is enabled.</p></div><div class="refsect1" title="See also"><a name="id341963"></a><h2>See also</h2><p><a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refopts.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="refreqbody.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_set_useragent </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_set_request_body_buffer</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,8 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_add_request_header</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refreq.html" title="ne_request_create"><link rel="next" href="refresphdr.html" title="ne_get_response_header"></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">ne_add_request_header</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refreq.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refresphdr.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_add_request_header"><a name="refreqhdr"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_add_request_header, ne_print_request_header — add headers to a request</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_add_request_header</b>(</code></td><td>ne_request *<var class="pdparam">request</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">value</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_print_request_header</b>(</code></td><td>ne_request *<var class="pdparam">request</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id340277"></a><h2>Description</h2><p>The functions <code class="function">ne_add_request_header</code>
|
||||
and <code class="function">ne_print_request_header</code> can be used to add
|
||||
headers to a request, before it is sent.</p><p><code class="function">ne_add_request_header</code> simply adds a
|
||||
header of given <code class="parameter">name</code>, with given
|
||||
<code class="parameter">value</code>.</p><p><code class="function">ne_print_request_header</code> adds a
|
||||
header of given <code class="parameter">name</code>, taking the value from the
|
||||
<code class="function">printf</code>-like <code class="parameter">format</code> string
|
||||
parameter and subsequent variable-length argument list.</p></div><div class="refsect1" title="See also"><a name="id340339"></a><h2>See also</h2><p><a class="xref" href="refreq.html#ne_request_create">ne_request_create</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refreq.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="refresphdr.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_request_create </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_get_response_header</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,48 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_addr_resolve</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refconfig.html" title="neon-config"><link rel="next" href="refbuf.html" title="ne_buffer"></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">ne_addr_resolve</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refconfig.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refbuf.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_addr_resolve"><a name="refresolve"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_addr_resolve, ne_addr_result, ne_addr_first, ne_addr_next, ne_addr_error, ne_addr_destroy — functions to resolve hostnames to addresses</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_socket.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_sock_addr *<b class="fsfunc">ne_addr_resolve</b>(</code></td><td>const char *<var class="pdparam">hostname</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_addr_result</b>(</code></td><td>const ne_sock_addr *<var class="pdparam">addr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_inet_addr *<b class="fsfunc">ne_addr_first</b>(</code></td><td>ne_sock_addr *<var class="pdparam">addr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const ne_inet_addr *<b class="fsfunc">ne_addr_next</b>(</code></td><td>ne_sock_addr *<var class="pdparam">addr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_addr_error</b>(</code></td><td>const ne_sock_addr *<var class="pdparam">addr</var>, </td></tr><tr><td> </td><td>char *<var class="pdparam">buffer</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">bufsiz</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_addr_destroy</b>(</code></td><td>ne_sock_addr *<var class="pdparam">addr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id332521"></a><h2>Description</h2><p>The <code class="function">ne_addr_resolve</code> function resolves
|
||||
the given <code class="parameter">hostname</code>, returning an
|
||||
<em class="type">ne_sock_addr</em> object representing the address (or
|
||||
addresses) associated with the hostname. The
|
||||
<code class="parameter">flags</code> parameter is currently unused, and
|
||||
must be passed as 0.</p><p>The <code class="parameter">hostname</code> passed to
|
||||
<code class="function">ne_addr_resolve</code> can be a DNS hostname
|
||||
(e.g. <code class="literal">"www.example.com"</code>) or an IPv4 dotted quad
|
||||
(e.g. <code class="literal">"192.0.34.72"</code>); or, on systems which
|
||||
support IPv6, an IPv6 hex address, which may be enclosed in
|
||||
brackets, e.g. <code class="literal">"[::1]"</code>.</p><p>To determine whether the hostname was successfully resolved,
|
||||
the <code class="function">ne_addr_result</code> function is used, which
|
||||
returns non-zero if an error occurred. If an error did occur, the
|
||||
<code class="function">ne_addr_error</code> function can be used, which
|
||||
will copy the error string into a given
|
||||
<code class="parameter">buffer</code> (of size
|
||||
<code class="parameter">bufsiz</code>).</p><p>The functions <code class="function">ne_addr_first</code> and
|
||||
<code class="function">ne_addr_next</code> are used to retrieve the
|
||||
Internet addresses associated with an address object which has
|
||||
been successfully resolved. <code class="function">ne_addr_first</code>
|
||||
returns the first address; <code class="function">ne_addr_next</code>
|
||||
returns the next address after the most recent call to
|
||||
<code class="function">ne_addr_next</code> or
|
||||
<code class="function">ne_addr_first</code>, or <code class="literal">NULL</code> if there are no more
|
||||
addresses. The <em class="type">ne_inet_addr</em> pointer returned by
|
||||
these functions can be passed to
|
||||
<code class="function">ne_sock_connect</code> to connect a socket.</p><p>After the address object has been used, it should be
|
||||
destroyed using <code class="function">ne_addr_destroy</code>.</p></div><div class="refsect1" title="Return value"><a name="id332667"></a><h2>Return value</h2><p><code class="function">ne_addr_resolve</code> returns a pointer to an
|
||||
address object, and never <code class="literal">NULL</code>.
|
||||
<code class="function">ne_addr_error</code> returns the
|
||||
<code class="parameter">buffer</code> parameter .</p></div><div class="refsect1" title="Examples"><a name="id332696"></a><h2>Examples</h2><p>The code below prints out the set of addresses associated
|
||||
with the hostname <code class="literal">www.google.com</code>.</p><pre class="programlisting">ne_sock_addr *addr;
|
||||
char buf[256];
|
||||
|
||||
addr = ne_addr_resolve("www.google.com", 0);
|
||||
if (ne_addr_result(addr)) {
|
||||
printf("Could not resolve www.google.com: %s\n",
|
||||
ne_addr_error(addr, buf, sizeof buf));
|
||||
} else {
|
||||
const ne_inet_addr *ia;
|
||||
printf("www.google.com:");
|
||||
for (ia = ne_addr_first(addr); ia != NULL; ia = ne_addr_next(addr)) {
|
||||
printf(" %s", ne_iaddr_print(ia, buf, sizeof buf));
|
||||
}
|
||||
putchar('\n');
|
||||
}
|
||||
ne_addr_destroy(addr);
|
||||
</pre></div><div class="refsect1" title="See also"><a name="id332721"></a><h2>See also</h2><p><a class="xref" href="refiaddr.html#ne_iaddr_print">ne_iaddr_print</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refconfig.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="refbuf.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon-config </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_buffer</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,26 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_get_response_header</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refreqhdr.html" title="ne_add_request_header"><link rel="next" href="refopts.html" title="ne_set_useragent"></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">ne_get_response_header</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refreqhdr.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refopts.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_get_response_header"><a name="refresphdr"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_get_response_header, ne_response_header_iterate — functions to access response headers</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_get_response_header</b>(</code></td><td>ne_request *<var class="pdparam">request</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void *<b class="fsfunc">ne_response_header_iterate</b>(</code></td><td>ne_request *<var class="pdparam">request</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">cursor</var>, </td></tr><tr><td> </td><td>const char **<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char **<var class="pdparam">value</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id340683"></a><h2>Description</h2><p>To retrieve the value of a response header field, the
|
||||
<code class="function">ne_get_response_header</code> function can be used,
|
||||
and is given the name of the header to return.</p><p>To iterate over all the response headers returned, the
|
||||
<code class="function">ne_response_header_iterate</code> function can be
|
||||
used. This function takes a <code class="parameter">cursor</code>
|
||||
parameter which should be <code class="literal">NULL</code> to retrieve the first header. The
|
||||
function stores the name and value of the next header header in
|
||||
the <code class="parameter">name</code> and <code class="parameter">value</code>
|
||||
parameters, and returns a new cursor pointer which can be passed
|
||||
to <code class="function">ne_response_header_iterate</code> to retrieve the
|
||||
next header.</p></div><div class="refsect1" title="Return value"><a name="id340734"></a><h2>Return value</h2><p><code class="function">ne_get_response_header</code> returns a
|
||||
string, or <code class="literal">NULL</code> if no header with that name was given. If used
|
||||
during request processing, the return value pointer is valid only
|
||||
until the next call to <code class="function">ne_begin_request</code>, or
|
||||
else, until the request object is destroyed.</p><p>Likewise, the cursor, names, and values returned by
|
||||
<code class="function">ne_response_header_iterate</code> are only valid
|
||||
until the next call to <code class="function">ne_begin_request</code> or
|
||||
until the request object is destroyed.</p></div><div class="refsect1" title="Examples"><a name="id340774"></a><h2>Examples</h2><p>The following code will output the value of the
|
||||
<code class="literal">Last-Modified</code> header for a resource:</p><pre class="programlisting">ne_request *req = ne_request_create(sess, "GET", "/foo.txt");
|
||||
if (ne_request_dispatch(req) == NE_OK) {
|
||||
const char *mtime = ne_get_response_header(req, "Last-Modified");
|
||||
if (mtime) {
|
||||
printf("/foo.txt has last-modified value %s\n", mtime);
|
||||
}
|
||||
}
|
||||
ne_request_destroy(req);</pre></div><div class="refsect1" title="See also"><a name="id340797"></a><h2>See also</h2><p><a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>, <a class="xref" href="refreq.html#ne_request_destroy">ne_request_destroy</a>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refreqhdr.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="refopts.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_add_request_header </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_set_useragent</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,36 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_session_create</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refalloc.html" title="ne_malloc"><link rel="next" href="refsessflags.html" title="ne_set_session_flag"></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">ne_session_create</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refalloc.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsessflags.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_session_create"><a name="refsess"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy — set up HTTP sessions</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_session.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_session *<b class="fsfunc">ne_session_create</b>(</code></td><td>const char *<var class="pdparam">scheme</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">hostname</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">port</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_session_proxy</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">hostname</var>, </td></tr><tr><td> </td><td>unsigned int <var class="pdparam">port</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_close_connection</b>(</code></td><td>ne_session *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_session_destroy</b>(</code></td><td>ne_session *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id337986"></a><h2>Description</h2><p>An <em class="type">ne_session</em> object represents an HTTP
|
||||
session - a logical grouping of a sequence of HTTP requests made to a
|
||||
certain server. Any requests made using the session can use a
|
||||
persistent connection, share cached authentication credentials and any
|
||||
other common attributes.</p><p>A new HTTP session is created using
|
||||
<code class="function">ne_session_create</code>, giving the
|
||||
<code class="parameter">hostname</code> and <code class="parameter">port</code> of the
|
||||
server to use, along with the <code class="parameter">scheme</code> used to
|
||||
contact the server (usually <code class="literal">"http"</code>). Before the
|
||||
first use of <code class="function">ne_session_create</code> in a process,
|
||||
<a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> must have been called to perform any
|
||||
global initialization needed by any libraries used by neon.</p><p>To enable SSL/TLS for the session, pass the string
|
||||
<code class="literal">"https"</code> as the <code class="parameter">scheme</code>
|
||||
parameter, and either register a certificate verification function
|
||||
(see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>) or trust the appropriate
|
||||
certificate (see <a class="xref" href="refsslca.html#ne_ssl_trust_cert">ne_ssl_trust_cert</a>, <a class="xref" href="refsslca.html#ne_ssl_trust_default_ca">ne_ssl_trust_default_ca</a>).</p><p>If an HTTP proxy server should be used for the session,
|
||||
<code class="function">ne_session_proxy</code> must be called giving
|
||||
the hostname and port on which to contact the proxy.</p><p>Further per-session options may be changed using the
|
||||
<a class="xref" href="refreqflags.html#ne_set_request_flag">ne_set_request_flag</a> interface.</p><p>If it is known that the session will not be used for a
|
||||
significant period of time, <code class="function">ne_close_connection</code>
|
||||
can be called to close the connection, if one remains open. Use of
|
||||
this function is entirely optional, but it must not be called if there
|
||||
is a request active using the session.</p><p>Once a session has been completed,
|
||||
<code class="function">ne_session_destroy</code> must be called to destroy the
|
||||
resources associated with the session. Any subsequent use of the
|
||||
session pointer produces undefined behaviour.</p></div><div class="refsect1" title="Notes"><a name="id338106"></a><h2>Notes</h2><p>The hostname passed to
|
||||
<code class="function">ne_session_create</code> is resolved when the first
|
||||
request using the session is dispatched; a DNS resolution failure can
|
||||
only be detected at that time (using the <code class="literal">NE_LOOKUP</code>
|
||||
error code); see <a class="xref" href="refreq.html#ne_request_dispatch">ne_request_dispatch</a> for
|
||||
details.</p></div><div class="refsect1" title="Return Values"><a name="id338131"></a><h2>Return Values</h2><p><code class="function">ne_session_create</code> will return
|
||||
a pointer to a new session object (and never <code class="literal">NULL</code>).</p></div><div class="refsect1" title="Examples"><a name="id338151"></a><h2>Examples</h2><p>Create and destroy a session:</p><pre class="programlisting">ne_session *sess;
|
||||
sess = ne_session_create("http", "host.example.com", 80);
|
||||
/* ... use sess ... */
|
||||
ne_session_destroy(sess);
|
||||
</pre></div><div class="refsect1" title="See Also"><a name="id338167"></a><h2>See Also</h2><p><a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>, <a class="xref" href="refsslca.html#ne_ssl_trust_cert">ne_ssl_trust_cert</a>, <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>, <a class="xref" href="refsessflags.html#ne_set_session_flag">ne_set_session_flag</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refalloc.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="refsessflags.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_malloc </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_set_session_flag</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,17 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_set_session_flag</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsess.html" title="ne_session_create"><link rel="next" href="refreq.html" title="ne_request_create"></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">ne_set_session_flag</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsess.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refreq.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_set_session_flag"><a name="refsessflags"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_set_session_flag, ne_get_session_flag — set and retrieve session flags</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_request.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_set_session_flag</b>(</code></td><td>ne_session *<var class="pdparam">sess</var>, </td></tr><tr><td> </td><td>ne_session_flag <var class="pdparam">flag</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">value</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_get_session_flag</b>(</code></td><td>ne_session *<var class="pdparam">sess</var>, </td></tr><tr><td> </td><td>ne_session_flag <var class="pdparam">flag</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id338695"></a><h2>Description</h2><p>The <code class="function">ne_set_session_flag</code> function
|
||||
enables or disables a session flag. Passing a non-zero
|
||||
<code class="parameter">value</code> argument enables the flag, and zero
|
||||
disables it.</p><p>The following flags are defined:</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_PERSIST</code></span></p></td><td>disable this flag to prevent use of persistent
|
||||
connections</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_ICYPROTO</code></span></p></td><td>enable this flag to enable support for non-HTTP
|
||||
ShoutCast-style "ICY" responses</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_SSLv2</code></span></p></td><td>disable this flag to disable support for the SSLv2
|
||||
protocol</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_RFC4918</code></span></p></td><td>enable this flag to enable support for
|
||||
RFC4918-only WebDAV features; losing
|
||||
backwards-compatibility with RFC2518 servers</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_CONNAUTH</code></span></p></td><td>enable this flag if an RFC-violating
|
||||
connection-based HTTP authentication scheme is in
|
||||
use</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_TLS_SNI</code></span></p></td><td>disable this flag if a server is used
|
||||
which does not correctly support the TLS SNI
|
||||
extension</td></tr><tr><td><p><span class="term"><code class="constant">NE_SESSFLAG_EXPECT100</code></span></p></td><td>enable this flag to enable the request flag
|
||||
<code class="constant">NE_REQFLAG_EXPECT100</code> for new
|
||||
requests</td></tr></tbody></table></div></div><div class="refsect1" title="Return value"><a name="id338828"></a><h2>Return value</h2><p>The <code class="function">ne_get_session_flag</code> function
|
||||
returns zero if a flag is disabled, less than zero if the flag is
|
||||
not supported, or greater than zero if the flag is enabled.</p></div><div class="refsect1" title="See also"><a name="id338844"></a><h2>See also</h2><p><a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>, <a class="xref" href="refreqflags.html#ne_set_request_flag">ne_set_request_flag</a>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsess.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="refreq.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_session_create </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_request_create</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,7 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_shave</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refauth.html" title="ne_set_server_auth"><link rel="next" href="refsockinit.html" title="ne_sock_init"></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">ne_shave</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refauth.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsockinit.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_shave"><a name="refshave"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_shave — trim whitespace from a string</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_shave</b>(</code></td><td>char *<var class="pdparam">str</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">whitespace</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id343342"></a><h2>Description</h2><p><code class="function">ne_shave</code> returns a portion of
|
||||
<code class="parameter">str</code> with any leading or trailing characters in
|
||||
the <code class="parameter">whitespace</code> array removed.
|
||||
<code class="parameter">str</code> may be modified. Note that the return
|
||||
value may not be equal to <code class="parameter">str</code>.</p></div><div class="refsect1" title="Examples"><a name="id343376"></a><h2>Examples</h2><p>The following code segment will output
|
||||
<code class="literal">"fish"</code>:</p><pre class="programlisting">char s[] = ".!.fish!.!";
|
||||
puts(ne_shave(s, ".!"));</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refauth.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="refsockinit.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_set_server_auth </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_sock_init</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,51 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_sock_init</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refshave.html" title="ne_shave"><link rel="next" href="refcert.html" title="ne_ssl_cert_identity"></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">ne_sock_init</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refshave.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refcert.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_sock_init"><a name="refsockinit"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_sock_init, ne_sock_exit — perform library initialization</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_socket.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_sock_init</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_sock_exit</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id343611"></a><h2>Description</h2><p>In some platforms and configurations, neon may be using
|
||||
some socket or SSL libraries which require global initialization
|
||||
before use. To perform this initialization, the
|
||||
<code class="function">ne_sock_init</code> function must be called before
|
||||
any other library functions are used.</p><p>Once all use of neon is complete,
|
||||
<code class="function">ne_sock_exit</code> can be called to perform
|
||||
de-initialization of socket or SSL libraries, if necessary. Uses
|
||||
of <code class="function">ne_sock_init</code> and
|
||||
<code class="function">ne_sock_exit</code> are "reference counted"; if N
|
||||
calls to <code class="function">ne_sock_init</code> are made, only the Nth
|
||||
call to <code class="function">ne_sock_exit</code> will have effect.</p><p><code class="function">ne_sock_init</code> will set the disposition
|
||||
of the <code class="literal">SIGPIPE</code> signal to
|
||||
<span class="emphasis"><em>ignored</em></span>. No change is made to the
|
||||
<code class="literal">SIGPIPE</code> disposition by
|
||||
<code class="function">ne_sock_exit</code>.</p><p>Both the SSL libraries supported by neon — OpenSSL
|
||||
and GnuTLS — require callbacks to be registered to allow
|
||||
thread-safe use of SSL. These callbacks are stored as global
|
||||
variables and so their state persists for as long as the library
|
||||
in question is loaded into the process. If multiple users of the
|
||||
SSL library exist within the process, this can be problematic,
|
||||
particularly if one is dynamically loaded (and may subsequently be
|
||||
unloaded).</p><p>If neon is configured using the
|
||||
<code class="literal">--enable-threadsafe-ssl</code> flag, thread-safe SSL
|
||||
support will be enabled automatically, as covered in the following
|
||||
section. Otherwise, it is not safe to use neon with SSL in a
|
||||
multi-threaded process. The <a class="xref" href="reffeat.html#ne_has_support">ne_has_support</a>
|
||||
function can be used to determine whether neon is built to
|
||||
enable thread-safety support in the SSL library.</p><div class="refsect2" title="Thread-safe SSL with OpenSSL"><a name="id343706"></a><h3>Thread-safe SSL with OpenSSL</h3><p>neon follows two simple rules when dealing with the
|
||||
OpenSSL locking callbacks:
|
||||
|
||||
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><code class="function">ne_sock_init</code> will set
|
||||
thread-safety locking callbacks if and only if no locking
|
||||
callbacks are already registered.</li><li class="listitem"><code class="function">ne_sock_exit</code> will
|
||||
unset the thread-safety locking callbacks if and only if the
|
||||
locking callbacks registered are those registered by
|
||||
<code class="function">ne_sock_init</code>.</li></ul></div><p>
|
||||
|
||||
Applications and libraries should be able to co-operate to
|
||||
ensure that SSL use is always thread-safe if similar rules are
|
||||
always followed.</p></div><div class="refsect2" title="Thread-safe SSL with GnuTLS"><a name="id343745"></a><h3>Thread-safe SSL with GnuTLS</h3><p>The cryptography library used by GnuTLS, libgcrypt, only
|
||||
supports an initialization operation to register thread-safety
|
||||
callbacks. <code class="function">ne_sock_init</code> will register the
|
||||
thread-safe locking callbacks on first use;
|
||||
<code class="function">ne_sock_exit</code> cannot unregister them. If
|
||||
multiple users of GnuTLS are present within the process, it is
|
||||
unsafe to dynamically unload neon from the process if neon
|
||||
is configured with thread-safe SSL support enabled (since the
|
||||
callbacks would be left pointing at unmapped memory once neon
|
||||
is unloaded).</p></div></div><div class="refsect1" title="Return value"><a name="id343771"></a><h2>Return value</h2><p><code class="function">ne_sock_init</code> returns zero on success,
|
||||
or non-zero on error. If an error occurs, no further use of the
|
||||
neon library should be attempted.</p></div><div class="refsect1" title="See also"><a name="id343787"></a><h2>See also</h2><p><a class="xref" href="refneon.html" title="neon"><span class="refentrytitle">neon</span></a>, <a class="xref" href="reffeat.html" title="ne_has_support"><span class="refentrytitle">ne_has_support</span></a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refshave.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="refcert.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_shave </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_cert_identity</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,15 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_trust_cert</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refssldname.html" title="ne_ssl_dname"><link rel="next" href="refsslvfy.html" title="ne_ssl_set_verify"></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">ne_ssl_trust_cert</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refssldname.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsslvfy.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_trust_cert"><a name="refsslca"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_trust_cert, ne_ssl_trust_default_ca — functions to indicate that certificates are trusted</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_session.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_ssl_trust_cert</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_ssl_trust_default_ca</b>(</code></td><td>ne_session *<var class="pdparam">session</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id345987"></a><h2>Description</h2><p>To indicate that a given certificate is trusted by the
|
||||
user, the certificate object can be passed to
|
||||
<code class="function">ne_ssl_trust_cert</code>. The certificate object is
|
||||
duplicated internally and can subsequently be destroyed.</p><p>The SSL library in use by neon may include a default
|
||||
set of CA certificates; calling the
|
||||
<code class="function">ne_ssl_trust_default_ca</code> function will indicate
|
||||
that these CAs are trusted by the user.</p></div><div class="refsect1" title="Examples"><a name="id346012"></a><h2>Examples</h2><p>Load the CA certificate stored in <code class="filename">/path/to/cacert.pem</code>:</p><pre class="programlisting">ne_session *sess = ne_session_create(...);
|
||||
ne_ssl_certificate *cert = ne_ssl_cert_read("/path/to/cacert.pem");
|
||||
|
||||
if (cert) {
|
||||
ne_ssl_trust_cert(sess, cert);
|
||||
ne_ssl_cert_free(cert);
|
||||
} else {
|
||||
printf("Could not load CA cert: %s\n", ne_get_error(sess));
|
||||
}</pre></div><div class="refsect1" title="See also"><a name="id346034"></a><h2>See also</h2><p><a class="xref" href="refsslcertio.html#ne_ssl_cert_read">ne_ssl_cert_read</a>, <a class="xref" href="refsslcertio.html#ne_ssl_cert_import">ne_ssl_cert_import</a>, <a class="xref" href="refsslcert2.html#ne_ssl_cert_free">ne_ssl_cert_free</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refssldname.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="refsslvfy.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_dname </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_set_verify</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,5 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_cert_cmp</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refcert.html" title="ne_ssl_cert_identity"><link rel="next" href="refsslcertio.html" title="ne_ssl_cert_read"></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">ne_ssl_cert_cmp</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refcert.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsslcertio.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_cert_cmp"><a name="refsslcert2"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_cert_cmp, ne_ssl_cert_free — functions to operate on certificate objects</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_header.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_ssl_cert_cmp</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">c1</var>, </td></tr><tr><td> </td><td>const ne_ssl_certificate *<var class="pdparam">c2</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_ssl_cert_free</b>(</code></td><td>ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id344753"></a><h2>Description</h2><p>The <code class="function">ne_ssl_cert_cmp</code> function can be
|
||||
used to compare two certificate objects; it returns zero if they
|
||||
refer to the same certificate, and non-zero otherwise.</p><p>The <code class="function">ne_ssl_cert_free</code> function can be
|
||||
used to destroy a certificate object when it is no longer
|
||||
needed.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refcert.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="refsslcertio.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_cert_identity </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_cert_read</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,24 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_cert_read</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsslcert2.html" title="ne_ssl_cert_cmp"><link rel="next" href="refssldname.html" title="ne_ssl_dname"></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">ne_ssl_cert_read</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsslcert2.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refssldname.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_cert_read"><a name="refsslcertio"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_cert_read, ne_ssl_cert_write, ne_ssl_cert_import, ne_ssl_cert_export — functions to read or write certificates to and from files or strings</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_ssl.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_ssl_certificate *<b class="fsfunc">ne_ssl_cert_read</b>(</code></td><td>const char *<var class="pdparam">filename</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_ssl_cert_write</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">filename</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_ssl_certificate *<b class="fsfunc">ne_ssl_cert_import</b>(</code></td><td>const char *<var class="pdparam">data</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_ssl_cert_export</b>(</code></td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id345053"></a><h2>Description</h2><p>The <code class="function">ne_ssl_cert_write</code> function writes a
|
||||
certificate to a file using the PEM encoding. The
|
||||
<code class="function">ne_ssl_cert_export</code> function returns a
|
||||
base64-encoded <code class="literal">NUL</code>-terminated string representing the
|
||||
certificate. This string is malloc-allocated and should be
|
||||
destroyed using <code class="function">free</code> by the caller.</p><p>The <code class="function">ne_ssl_cert_read</code> function reads a
|
||||
certificate from a PEM-encoded file, and returns a certificate
|
||||
object. The <code class="function">ne_ssl_cert_import</code> function
|
||||
returns a certificate object from a base64-encoded string,
|
||||
<code class="parameter">data</code>, as returned by
|
||||
<code class="function">ne_ssl_cert_export</code>. The certificate object
|
||||
returned by these functions should be destroyed using <a class="xref" href="refsslcert2.html#ne_ssl_cert_free">ne_ssl_cert_free</a> after use.</p></div><div class="refsect1" title="Return value"><a name="id345114"></a><h2>Return value</h2><p><code class="function">ne_ssl_cert_read</code> returns <code class="literal">NULL</code> if a
|
||||
certificate could not be read from the file.
|
||||
<code class="function">ne_ssl_cert_write</code> returns non-zero if the
|
||||
certificate could not be written to the file.
|
||||
<code class="function">ne_ssl_cert_export</code> always returns a
|
||||
<code class="literal">NUL</code>-terminated string, and never <code class="literal">NULL</code>.
|
||||
<code class="function">ne_ssl_cert_import</code> returns <code class="literal">NULL</code> if the
|
||||
string was not a valid base64-encoded certificate.</p></div><div class="refsect1" title="Encoding Formats"><a name="id345166"></a><h2>Encoding Formats</h2><p>The string produced by
|
||||
<code class="function">ne_ssl_cert_export</code> is the base64 encoding of
|
||||
the DER representation of the certificate. The file written by
|
||||
<code class="function">ne_ssl_cert_write</code> uses the PEM format: this
|
||||
is the base64 encoding of the DER representation with newlines
|
||||
every 64 characters, and start and end marker lines.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsslcert2.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="refssldname.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_cert_cmp </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_dname</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,9 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_dname</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsslcertio.html" title="ne_ssl_cert_read"><link rel="next" href="refsslca.html" title="ne_ssl_trust_cert"></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">ne_ssl_dname</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsslcertio.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refsslca.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_dname"><a name="refssldname"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_readable_dname, ne_ssl_dname_cmp — SSL distinguished name handling</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_ssl.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_ssl_readable_dname</b>(</code></td><td>const ne_ssl_dname *<var class="pdparam">dname</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_ssl_dname_cmp</b>(</code></td><td>const ne_ssl_dname *<var class="pdparam">dn1</var>, </td></tr><tr><td> </td><td>const ne_ssl_dname *<var class="pdparam">dn2</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id345588"></a><h2>Description</h2><p>The <code class="function">ne_ssl_readable_dname</code> function
|
||||
creates a single-line, human-readable string out of an
|
||||
<em class="type">ne_ssl_dname</em> object. The returned string is
|
||||
<code class="function">malloc</code>()-allocated, and must be
|
||||
<code class="function">free</code>()d by the caller.</p><p>The <code class="function">ne_ssl_dname_cmp</code> function
|
||||
compares two distinguished names, and returns zero if they are
|
||||
equal, or non-zero otherwise.</p></div><div class="refsect1" title="Return value"><a name="id345626"></a><h2>Return value</h2><p><code class="function">ne_ssl_readable_dname</code> returns a <code class="function">malloc</code>-allocated
|
||||
string, and never <code class="literal">NULL</code>.</p></div><div class="refsect1" title="Examples"><a name="id345650"></a><h2>Examples</h2><p>See <a class="xref" href="refcert.html#ne_ssl_cert_subject">ne_ssl_cert_subject</a> for an example
|
||||
use of <code class="function">ne_ssl_readable_dname</code>.</p></div><div class="refsect1" title="See also"><a name="id345669"></a><h2>See also</h2><p><a class="xref" href="refcert.html#ne_ssl_cert_subject">ne_ssl_cert_subject</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsslcertio.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="refsslca.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_cert_read </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_trust_cert</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,66 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_ssl_set_verify</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refsslca.html" title="ne_ssl_trust_cert"><link rel="next" href="refclicert.html" title="ne_ssl_client_cert"></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">ne_ssl_set_verify</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refsslca.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refclicert.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_ssl_set_verify"><a name="refsslvfy"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_ssl_set_verify — register an SSL certificate verification callback</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_session.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">typedef int <b class="fsfunc">ne_ssl_verify_fn</b>(</code></td><td>void *<var class="pdparam">userdata</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">failures</var>, </td></tr><tr><td> </td><td>const ne_ssl_certificate *<var class="pdparam">cert</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_ssl_set_verify</b>(</code></td><td>ne_session *<var class="pdparam">session</var>, </td></tr><tr><td> </td><td>ne_ssl_verify_fn <var class="pdparam">verify_fn</var>, </td></tr><tr><td> </td><td>void *<var class="pdparam">userdata</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id346347"></a><h2>Description</h2><p>To enable manual SSL certificate verification, a
|
||||
callback can be registered using
|
||||
<code class="function">ne_ssl_set_verify</code>. If such a callback is not
|
||||
registered, when a connection is established to an SSL server which
|
||||
does not present a certificate signed by a trusted CA (see <a class="xref" href="refsslca.html#ne_ssl_trust_cert">ne_ssl_trust_cert</a>), or if the certificate presented is invalid in
|
||||
some way, the connection will fail.</p><p>When the callback is invoked, the
|
||||
<code class="parameter">failures</code> parameter gives a bitmask indicating
|
||||
in what way the automatic certificate verification failed. The value
|
||||
is equal to the bit-wise OR of one or more of the following
|
||||
constants (and is guaranteed to be non-zero):</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="constant">NE_SSL_NOTYETVALID</code></span></p></td><td>The certificate is not yet valid.</td></tr><tr><td><p><span class="term"><code class="constant">NE_SSL_EXPIRED</code></span></p></td><td>The certificate has expired.</td></tr><tr><td><p><span class="term"><code class="constant">NE_SSL_IDMISMATCH</code></span></p></td><td>The hostname used for the session does not match
|
||||
the hostname to which the certificate was issued.</td></tr><tr><td><p><span class="term"><code class="constant">NE_SSL_UNTRUSTED</code></span></p></td><td>The Certificate Authority which signed the certificate
|
||||
is not trusted.</td></tr></tbody></table></div><p>Note that if either of the
|
||||
<code class="constant">NE_SSL_IDMISMATCH</code> or
|
||||
<code class="constant">NE_SSL_UNTRUSTED</code> failures is given, the
|
||||
connection may have been intercepted by a third party, and
|
||||
must not be presumed to be <span class="quote">“<span class="quote">secure</span>”</span>.</p><p>The <code class="parameter">cert</code> parameter passed to the
|
||||
callback represents the certificate which was presented by the server.
|
||||
If the server presented a chain of certificates, the chain can be
|
||||
accessed using <a class="xref" href="refcert.html#ne_ssl_cert_signedby">ne_ssl_cert_signedby</a>. The
|
||||
<code class="parameter">cert</code> object given is not valid after the
|
||||
callback returns.</p></div><div class="refsect1" title="Return value"><a name="id346468"></a><h2>Return value</h2><p>The verification callback must return zero to indicate
|
||||
that the certificate should be trusted; and non-zero otherwise (in
|
||||
which case, the connection will fail).</p></div><div class="refsect1" title="Examples"><a name="id346479"></a><h2>Examples</h2><p>The following code implements an example verification
|
||||
callback, using the <code class="function">dump_cert</code> function
|
||||
from <a class="xref" href="refcert.html#ne_ssl_cert_subject">ne_ssl_cert_subject</a> to display
|
||||
certification information. Notice that the hostname of the
|
||||
server used for the session is passed as the
|
||||
<code class="parameter">userdata</code> parameter to the
|
||||
callback.</p><pre class="programlisting">
|
||||
static int
|
||||
my_verify(void *userdata, int failures, const ne_ssl_certificate *cert)
|
||||
{
|
||||
const char *hostname = userdata;
|
||||
|
||||
dump_cert(cert);
|
||||
|
||||
puts("Certificate verification failed - the connection may have been "
|
||||
"intercepted by a third party!");
|
||||
|
||||
if (failures & NE_SSL_IDMISMATCH) {
|
||||
const char *id = ne_ssl_cert_identity(cert);
|
||||
if (id)
|
||||
printf("Server certificate was issued to '%s' not '%s'.\n",
|
||||
id, hostname);
|
||||
else
|
||||
printf("The certificate was not issued for '%s'\n", hostname);
|
||||
}
|
||||
|
||||
if (failures & NE_SSL_UNTRUSTED)
|
||||
puts("The certificate is not signed by a trusted Certificate Authority.");
|
||||
|
||||
/* ... check for validity failures ... */
|
||||
|
||||
if (prompt_user())
|
||||
return 1; /* fail verification */
|
||||
else
|
||||
return 0; /* trust the certificate anyway */
|
||||
}
|
||||
|
||||
int
|
||||
main(...)
|
||||
{
|
||||
ne_session *sess = ne_session_create("https", "some.host.name", 443);
|
||||
ne_ssl_set_verify(sess, my_verify, "some.host.name");
|
||||
...
|
||||
}</pre></div><div class="refsect1" title="See also"><a name="id346524"></a><h2>See also</h2><p><a class="xref" href="refsslca.html#ne_ssl_trust_cert">ne_ssl_trust_cert</a>, <a class="xref" href="refssldname.html#ne_ssl_readable_dname">ne_ssl_readable_dname</a>, <a class="xref" href="refcert.html#ne_ssl_cert_subject">ne_ssl_cert_subject</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refsslca.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="refclicert.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_trust_cert </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_ssl_client_cert</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,22 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_status</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refclicert.html" title="ne_ssl_client_cert"><link rel="next" href="reftok.html" title="ne_token"></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">ne_status</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refclicert.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="reftok.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_status"><a name="refstatus"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_status — HTTP status structure</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_utils.h>
|
||||
|
||||
typedef struct {
|
||||
int major_version, minor_version;
|
||||
int code, klass;
|
||||
const char *reason_phrase;
|
||||
} <em class="type">ne_status</em>;</pre></div></div><div class="refsect1" title="Description"><a name="id347704"></a><h2>Description</h2><p>An <em class="type">ne_status</em> type represents an HTTP
|
||||
response status; used in response messages giving a result of request.
|
||||
The <em class="structfield"><code>major_version</code></em> and
|
||||
<em class="structfield"><code>minor_version</code></em> fields give the HTTP version
|
||||
supported by the server issuing the response. The
|
||||
<em class="structfield"><code>code</code></em> field gives the status code of the
|
||||
result (lying between 100 and 999 inclusive), and the
|
||||
<em class="structfield"><code>klass</code></em> field gives the
|
||||
class<sup>[<a name="id347728" href="#ftn.id347728" class="footnote">2</a>]</sup>, which is equal to the most significant digit
|
||||
of the status.</p><p>There are five classes of HTTP status code defined by
|
||||
RFC2616:</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">1xx</code></span></p></td><td>Informational response.</td></tr><tr><td><p><span class="term"><code class="literal">2xx</code></span></p></td><td>Success: the operation was successful</td></tr><tr><td><p><span class="term"><code class="literal">3xx</code></span></p></td><td>Redirection</td></tr><tr><td><p><span class="term"><code class="literal">4xx</code></span></p></td><td>Client
|
||||
error: the request made was incorrect in some
|
||||
manner.</td></tr><tr><td><p><span class="term"><code class="literal">5xx</code></span></p></td><td>Server error</td></tr></tbody></table></div></div><div class="refsect1" title="See also"><a name="id347822"></a><h2>See also</h2><p><a class="xref" href="refgetst.html#ne_get_status">ne_get_status</a>.</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id347728" href="#id347728" class="para">2</a>] </sup>the field is named <span class="quote">“<span class="quote">klass</span>”</span> not
|
||||
<span class="quote">“<span class="quote">class</span>”</span> so that the header can be used from a C++
|
||||
program, in which <span class="quote">“<span class="quote">class</span>”</span> is a reserved
|
||||
word)</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refclicert.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="reftok.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_ssl_client_cert </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_token</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,20 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_token</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refstatus.html" title="ne_status"><link rel="next" href="refvers.html" title="ne_version_match"></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">ne_token</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refstatus.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refvers.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_token"><a name="reftok"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_token, ne_qtoken — string tokenizers</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_string.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_token</b>(</code></td><td>char **<var class="pdparam">str</var>, </td></tr><tr><td> </td><td>char <var class="pdparam">sep</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">char *<b class="fsfunc">ne_qtoken</b>(</code></td><td>char **<var class="pdparam">str</var>, </td></tr><tr><td> </td><td>char <var class="pdparam">sep</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">quotes</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id348139"></a><h2>Description</h2><p><code class="function">ne_token</code> and
|
||||
<code class="function">ne_qtoken</code> tokenize the string at the location
|
||||
stored in the pointer <code class="parameter">str</code>. Each time the
|
||||
function is called, it returns the next token, and modifies the
|
||||
<code class="parameter">str</code> pointer to point to the remainer of the
|
||||
string, or <code class="literal">NULL</code> if there are no more tokens in the string. A token
|
||||
is delimited by the separator character <code class="parameter">sep</code>; if
|
||||
<code class="function">ne_qtoken</code> is used any quoted segments of the
|
||||
string are skipped when searching for a separator. A quoted segment
|
||||
is enclosed in a pair of one of the characters given in the
|
||||
<code class="parameter">quotes</code> string.</p><p>The string being tokenized is modified each time
|
||||
the tokenizing function is called; replacing the next separator
|
||||
character with a <code class="literal">NUL</code> terminator.</p></div><div class="refsect1" title="Examples"><a name="id348203"></a><h2>Examples</h2><p>The following function prints out each token in a
|
||||
comma-separated string <code class="parameter">list</code>, which is
|
||||
modified in-place:</p><pre class="programlisting">static void splitter(char *list)
|
||||
{
|
||||
do {
|
||||
printf("Token: %s\n", ne_token(&list, ','));
|
||||
while (list);
|
||||
}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refstatus.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="refvers.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_status </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_version_match</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,11 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_version_match</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="reftok.html" title="ne_token"><link rel="next" href="refxml.html" title="ne_xml_create"></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">ne_version_match</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="reftok.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refxml.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_version_match"><a name="refvers"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_version_match, ne_version_string — library versioning</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_utils.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">int <b class="fsfunc">ne_version_match</b>(</code></td><td>int <var class="pdparam">major</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">minor</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">const char *<b class="fsfunc">ne_version_string</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id348521"></a><h2>Description</h2><p>The <code class="function">ne_version_match</code> function returns
|
||||
non-zero if the library version is not of major version
|
||||
<code class="parameter">major</code>, or the minor version is less than
|
||||
<code class="parameter">minor</code>. For neon versions 0.x, every
|
||||
minor version is assumed to be incompatible with every other minor
|
||||
version.</p><p>The <code class="function">ne_version_string</code> function returns
|
||||
a string giving the library version.</p></div><div class="refsect1" title="Examples"><a name="id348559"></a><h2>Examples</h2><p>To require neon 1.x, version 1.2 or later:</p><pre class="programlisting">if (ne_version_match(1, 2)) {
|
||||
printf("Library version out of date: 1.2 required, found %s.",
|
||||
ne_version_string());
|
||||
exit(1);
|
||||
}</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reftok.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="refxml.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_token </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> ne_xml_create</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,4 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ne_xml_create</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="refvers.html" title="ne_version_match"><link rel="next" href="biblio.html" title="Bibliography"></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">ne_xml_create</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="refvers.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="biblio.html">Next</a></td></tr></table><hr></div><div class="refentry" title="ne_xml_create"><a name="refxml"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>ne_xml_create, ne_xml_destroy — create and destroy an XML parser</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <ne_xml.h></pre><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">ne_xml_parser *<b class="fsfunc">ne_xml_create</b>(</code></td><td><code>void)</code>;</td><td> </td></tr></table><div class="funcprototype-spacer"> </div><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void <b class="fsfunc">ne_xml_destroy</b>(</code></td><td>ne_xml_parser *<var class="pdparam">parser</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1" title="Description"><a name="id348806"></a><h2>Description</h2><p>The <code class="function">ne_xml_create</code> function creates an
|
||||
XML parser object, which can be used for parsing XML documents
|
||||
using stacked SAX handlers.</p></div><div class="refsect1" title="Return value"><a name="id348822"></a><h2>Return value</h2><p><code class="function">ne_xml_create</code> returns a pointer to an
|
||||
XML parser object, and never <code class="literal">NULL</code></p></div><div class="refsect1" title="See also"><a name="id348840"></a><h2>See also</h2><p>XXX</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="refvers.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="biblio.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">ne_version_match </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Bibliography</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,54 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>HTTP Client Security</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="intro.html" title="Chapter 1. Introduction"><link rel="prev" href="compliance.html" title="Standards compliance"><link rel="next" href="api.html" title="Chapter 2. The neon C language interface"></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">HTTP Client Security</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="compliance.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr></div><div class="sect1" title="HTTP Client Security"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security"></a>HTTP Client Security</h2></div></div></div><p>neon is intended to be secure against a specific threat
|
||||
model: use of a malicious HTTP server. Under this threat model, a
|
||||
range of attacks are possible against a client when the user (or
|
||||
application) can be tricked into accessing an HTTP server which is
|
||||
controlled by an attacker. This section documents various types of
|
||||
possible attack and describes what mitigation is used in
|
||||
neon.</p><div class="sect2" title="CPU or memory consumption attacks"><div class="titlepage"><div><div><h3 class="title"><a name="id328572"></a>CPU or memory consumption attacks</h3></div></div></div><p>neon uses fixed resource limits to prevent the following
|
||||
attacks:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>memory/CPU consumption attack using an unbounded number
|
||||
of response header fields</p></li><li class="listitem"><p>memory consumption attack using an unbounded length of
|
||||
individual response header lines (or continuation
|
||||
headers)</p></li><li class="listitem"><p>memory consumption attack against the PROPFIND code
|
||||
using an unbounded number of properties (propstat elements)
|
||||
per resource</p></li><li class="listitem"><p>memory consumption attack against the PROPFIND code
|
||||
using an unbounded CDATA element in a "flat property"
|
||||
value</p></li></ul></div><p>Memory consumption attacks against applications based on
|
||||
neon by use of unbounded response length are also possible, but
|
||||
must be mitigated at application level. Memory consumption in
|
||||
neon itself is fixed and is not proportional to the response
|
||||
size.</p><p>Test cases for all the above attacks are present in the
|
||||
neon test suite.</p></div><div class="sect2" title="SSL/TLS connection security"><div class="titlepage"><div><div><h3 class="title"><a name="id329132"></a>SSL/TLS connection security</h3></div></div></div><p>When using a connection secured by SSL/TLS, it is necessary
|
||||
for clients to verify that the X.509 certificate presented by the
|
||||
server matches the server's expected identity. The algorithm
|
||||
required for this purpose is described in RFC 2818 and RFC 3280,
|
||||
and is implemented by neon in the following manner:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the hostname argument passed to <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a> is the expected identity of the
|
||||
server</p></li><li class="listitem"><p>the subjectAltName extension of the certificate is used
|
||||
for comparision against the expected identity, in preference
|
||||
to the Subject name's commonName attribute.</p></li><li class="listitem"><p>the dNSName, iPAddress, and uniformResourceIdentifier
|
||||
classes of GeneralName are supported in subjectAltName
|
||||
comparison.</p></li><li class="listitem"><p>if no subjectAltName is present in the certificate, the
|
||||
most specific commonName attribute in the Subject name is used
|
||||
for comparison instead.</p></li></ul></div><p>In the case where a server certificate is presented that
|
||||
does not match the expected identity (or is otherwise not
|
||||
trusted), neon will fail the request by default. This behaviour
|
||||
can be overridden by the use of a callback installed using <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>, which allows the application to
|
||||
present the certificate details to a user for manual/off-line
|
||||
verification, if possible.</p><p>Test cases for the correctness of the implementation of the
|
||||
identity verification algorithm are present in the neon test
|
||||
suite.</p></div><div class="sect2" title="Control character insertion in error messages"><div class="titlepage"><div><div><h3 class="title"><a name="id329198"></a>Control character insertion in error messages</h3></div></div></div><p>Where error messages (as returned by
|
||||
(<a class="xref" href="referr.html#ne_get_error">ne_get_error</a>) contain data supplied by the
|
||||
server, the untrusted data is sanitised to remove both control
|
||||
characters and non-ASCII characters. This prevents any attacks
|
||||
where such error messages are exposed to the user and can
|
||||
potentially distort the presentation of the interface (for
|
||||
example, through the use of a carriage return character in a text
|
||||
user interface).</p></div><div class="sect2" title="Attacks against authentication credentials"><div class="titlepage"><div><div><h3 class="title"><a name="id329215"></a>Attacks against authentication credentials</h3></div></div></div><p>Authentication credentials can be compromised by a
|
||||
"downgrade attack" by an active attacker; for example, where a
|
||||
MITM presents a Basic authentication challenge in place of the
|
||||
server's Digest challenge. neon mitigates these attacks by
|
||||
allowing the application (and hence, user) to specify that only a
|
||||
specific set of authentication protocols is permitted.</p><p>neon supports the Digest and Negotiate authentication
|
||||
schemes, which both allow authentication of users without passing
|
||||
credentials in cleartext over the wire. The "domain" parameter is
|
||||
supported in Digest, allowing the server to restrict an
|
||||
authentication session to a particular set of URIs.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="compliance.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Standards compliance </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. The neon C language interface</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,40 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to use neon from your application</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="intro.html" title="Chapter 1. Introduction"><link rel="prev" href="features.html" title="Feature list"><link rel="next" href="compliance.html" title="Standards compliance"></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">How to use neon from your application</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="features.html">Prev</a> </td><th width="60%" align="center">Chapter 1. Introduction</th><td width="20%" align="right"> <a accesskey="n" href="compliance.html">Next</a></td></tr></table><hr></div><div class="sect1" title="How to use neon from your application"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="using"></a>How to use neon from your application</h2></div></div></div><p>This section describes how to add neon support to an
|
||||
application. If you just want to quickly try out neon, use
|
||||
the <a class="xref" href="refconfig.html" title="neon-config"><span class="refentrytitle">neon-config</span></a> script.</p><p>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 <a class="ulink" href="http://www.gnu.org/software/autoconf/" target="_top">GNU autoconf</a>
|
||||
macros are supplied, which can be used in a number of ways, as
|
||||
follows:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>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).</p></li><li class="listitem"><p>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':</p><pre class="programlisting">NEON_BUNDLED(libneon, ...)</pre><p>If your application supports builds where srcdir != builddir,
|
||||
you should use the NEON_VPATH_BUNDLED macro like this:</p><pre class="programlisting">NEON_VPATH_BUNDLED(${srcdir}/libneon, libneon, ...)</pre><p>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.</p></li><li class="listitem"><p>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.</p></li></ul></div><p>A full fragment might be:</p><pre class="programlisting">NEON_BUNDLED(libneon, [
|
||||
NEON_NORMAL_BUILD
|
||||
NEON_XML_PARSER
|
||||
SUBDIRS="libneon $SUBDIRS"
|
||||
])</pre><p>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.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="features.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="intro.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="compliance.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Feature list </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Standards compliance</td></tr></table></div></body></html>
|
||||
@@ -0,0 +1,90 @@
|
||||
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Parsing XML</title><link rel="stylesheet" href="../manual.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="api.html" title="Chapter 2. The neon C language interface"><link rel="prev" href="api.html" title="Chapter 2. The neon C language interface"><link rel="next" href="ref.html" title="neon API reference"></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">Parsing XML</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center">Chapter 2. The neon C language interface</th><td width="20%" align="right"> <a accesskey="n" href="ref.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Parsing XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="xml"></a>Parsing XML</h2></div></div></div><p>The neon XML interface is exposed by the
|
||||
<code class="filename">ne_xml.h</code> header file. This interface gives a
|
||||
wrapper around the standard <a class="ulink" href="http://www.saxproject.org/" target="_top">SAX</a> API used by XML
|
||||
parsers, with an additional abstraction, <em class="firstterm">stacked SAX
|
||||
handlers</em>, and also giving consistent <a class="ulink" href="http://www.w3.org/TR/REC-xml-names" target="_top">XML Namespace</a> support.</p><div class="sect2" title="Introduction to SAX"><div class="titlepage"><div><div><h3 class="title"><a name="xml-sax"></a>Introduction to SAX</h3></div></div></div><p>A SAX-based parser works by emitting a sequence of
|
||||
<em class="firstterm">events</em> to reflect the tokens being parsed
|
||||
from the XML document. For example, parsing the following document
|
||||
fragment:
|
||||
|
||||
</p><pre class="programlisting">
|
||||
<hello>world</hello>
|
||||
</pre><p>
|
||||
|
||||
results in the following events:
|
||||
|
||||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="emphasis"><em>start-element</em></span> "hello"</li><li class="listitem"><span class="emphasis"><em>character-data</em></span> "world"</li><li class="listitem"><span class="emphasis"><em>end-element</em></span> "hello"</li></ol></div><p>
|
||||
|
||||
This example demonstrates the three event types used used in the
|
||||
subset of SAX exposed by the neon XML interface: <span class="emphasis"><em>start-element</em></span>,
|
||||
<span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span>. In a C API, an <span class="quote">“<span class="quote">event</span>”</span> is
|
||||
implemented as a function callback; three callback types are used in
|
||||
neon, one for each type of event.</p></div><div class="sect2" title="Stacked SAX handlers"><div class="titlepage"><div><div><h3 class="title"><a name="xml-stacked"></a>Stacked SAX handlers</h3></div></div></div><p>WebDAV property values are represented as fragments of XML,
|
||||
transmitted as parts of larger XML documents over HTTP (notably in
|
||||
the body of the response to a <code class="literal">PROPFIND</code> request).
|
||||
When neon parses such documents, the SAX events generated for
|
||||
these property value fragments may need to be handled by the
|
||||
application, since neon has no knowledge of the structure of
|
||||
properties used by the application.</p><p>To solve this problem<sup>[<a name="foot.xml.sax" href="#ftn.foot.xml.sax" class="footnote">1</a>]</sup> the neon XML interface introduces
|
||||
the concept of a <em class="firstterm">SAX handler</em>. A SAX handler
|
||||
comprises a <span class="emphasis"><em>start-element</em></span>, <span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span> callback; the
|
||||
<span class="emphasis"><em>start-element</em></span> callback being defined such that each handler may
|
||||
<span class="emphasis"><em>accept</em></span> or <span class="emphasis"><em>decline</em></span> the
|
||||
<span class="emphasis"><em>start-element</em></span> event. Handlers are composed into a <em class="firstterm">handler
|
||||
stack</em> before parsing a document. When a new <span class="emphasis"><em>start-element</em></span>
|
||||
event is generated by the XML parser, neon invokes each <span class="emphasis"><em>start-element</em></span>
|
||||
callback in the handler stack in turn until one accepts the event.
|
||||
The handler which accepts the event will then be subsequently be
|
||||
passed <span class="emphasis"><em>character-data</em></span> events if the element contains character data,
|
||||
followed by an <span class="emphasis"><em>end-element</em></span> event when the element is closed. If no
|
||||
handler in the stack accepts a <span class="emphasis"><em>start-element</em></span> event, the branch of the
|
||||
tree is ignored.</p><p>To illustrate, given a handler A, which accepts the
|
||||
<code class="literal">cat</code> and <code class="literal">age</code> elements, and a
|
||||
handler B, which accepts the <code class="literal">name</code> element, the
|
||||
following document:
|
||||
|
||||
</p><div class="example"><a name="xml-example"></a><p class="title"><b>Example 2.1. An example XML document</b></p><div class="example-contents"><pre class="programlisting">
|
||||
<cat>
|
||||
<age>3</age>
|
||||
<name>Bob</name>
|
||||
</cat>
|
||||
</pre></div></div><p><br class="example-break">
|
||||
|
||||
would be parsed as follows:
|
||||
|
||||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "cat" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "age" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">A <span class="emphasis"><em>character-data</em></span> "3"</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> "age"</li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "name" → <span class="emphasis"><em>decline</em></span></li><li class="listitem">B <span class="emphasis"><em>start-element</em></span> "name" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">B <span class="emphasis"><em>character-data</em></span> "Bob"</li><li class="listitem">B <span class="emphasis"><em>end-element</em></span> "name"</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> "cat"</li></ol></div><p>The search for a handler which will accept a <span class="emphasis"><em>start-element</em></span> event
|
||||
begins at the handler of the parent element and continues toward the
|
||||
top of the stack. For the root element, it begins at the base of
|
||||
the stack. In the above example, handler A is at the base, and
|
||||
handler B at the top; if the <code class="literal">name</code> element had any
|
||||
children, only B's <span class="emphasis"><em>start-element</em></span> would be invoked to accept
|
||||
them.</p></div><div class="sect2" title="Maintaining state"><div class="titlepage"><div><div><h3 class="title"><a name="xml-state"></a>Maintaining state</h3></div></div></div><p>To facilitate communication between independent handlers, a
|
||||
<em class="firstterm">state integer</em> is associated with each element
|
||||
being parsed. This integer is returned by <span class="emphasis"><em>start-element</em></span> callback and
|
||||
is passed to the subsequent <span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span> callbacks
|
||||
associated with the element. The state integer of the parent
|
||||
element is also passed to each <span class="emphasis"><em>start-element</em></span> callback, the value zero
|
||||
used for the root element (which by definition has no
|
||||
parent).</p><p>To further extend <a class="xref" href="xml.html#xml-example" title="Example 2.1. An example XML document">Example 2.1, “An example XML document”</a>: if handler A
|
||||
defines that the state of the root element <code class="sgmltag-element">cat</code>
|
||||
will be <code class="literal">42</code>, the event trace would be as
|
||||
follows:
|
||||
|
||||
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 0, "cat") →
|
||||
<span class="emphasis"><em>accept</em></span>, state = 42
|
||||
</li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 42, "age") →
|
||||
<span class="emphasis"><em>accept</em></span>, state = 50
|
||||
</li><li class="listitem">A <span class="emphasis"><em>character-data</em></span> (state = 50, "3")</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> (state = 50, "age")</li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 42, "name") →
|
||||
<span class="emphasis"><em>decline</em></span></li><li class="listitem">B <span class="emphasis"><em>start-element</em></span> (parent = 42, "name") →
|
||||
<span class="emphasis"><em>accept</em></span>, state = 99</li><li class="listitem">B <span class="emphasis"><em>character-data</em></span> (state = 99, "Bob")</li><li class="listitem">B <span class="emphasis"><em>end-element</em></span> (state = 99, "name")</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> (state = 42, "cat")</li></ol></div><p>To avoid collisions between state integers used by different
|
||||
handlers, the interface definition of any handler includes the range
|
||||
of integers it will use.</p></div><div class="sect2" title="XML namespaces"><div class="titlepage"><div><div><h3 class="title"><a name="xml-ns"></a>XML namespaces</h3></div></div></div><p>To support XML namespaces, every element name is represented
|
||||
as a <span class="emphasis"><em>(namespace, name)</em></span> pair. The <span class="emphasis"><em>start-element</em></span>
|
||||
and <span class="emphasis"><em>end-element</em></span> callbacks are passed namespace and name strings
|
||||
accordingly. If an element in the XML document has no declared
|
||||
namespace, the namespace given will be the empty string,
|
||||
<code class="literal">""</code>.</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.foot.xml.sax" href="#foot.xml.sax" class="para">1</a>] </sup>This
|
||||
<span class="quote">“<span class="quote">problem</span>”</span> only needs solving because the SAX interface
|
||||
is so inflexible when implemented as C function callbacks; a better
|
||||
approach would be to use an XML parser interface which is not based
|
||||
on callbacks.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="api.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. The neon C language interface </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon API reference</td></tr></table></div></body></html>
|
||||
Reference in New Issue
Block a user