* doc/ref/resphdr.xml: New file; document response header handling.

* doc/manual.xml: Reference it.  


git-svn-id: http://svn.webdav.org/repos/projects/neon/trunk@698 61a7d7f5-40b7-0310-9c16-bb0ea8cb1845

2 files changed, 102 insertions, 2 deletions

diff --git a/doc/manual.xml b/doc/manual.xml
index f78de1b..d3880b6 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -52,6 +52,7 @@
 <!ENTITY refssltrust SYSTEM "ref/ssltrust.xml">
 <!ENTITY refreq SYSTEM "ref/req.xml">
 <!ENTITY refreqhdr SYSTEM "ref/reqhdr.xml">
+<!ENTITY refresphdr SYSTEM "ref/resphdr.xml">
 <!ENTITY refreqopts SYSTEM "ref/reqopts.xml">
 <!ENTITY refstatus SYSTEM "ref/status.xml">
 <!ENTITY refgetst SYSTEM "ref/getst.xml">
@@ -144,7 +145,6 @@ ignoring the WebDAV support if desired.</para>
     &refneon; <!-- neon -->
     &refconfig; <!-- neon-config -->
 
-    &refreqhdr; <!-- ne_add_request_header -->
     &refresolve; <!-- ne_addr_resolve -->
     &refbuf; <!-- ne_buffer -->
     &refbufapp; <!-- ne_buffer_append -->
@@ -155,8 +155,10 @@ ignoring the WebDAV support if desired.</para>
     &refgetst; <!-- ne_get_status -->
     &refiaddr; <!-- ne_iaddr_make -->
     &refalloc; <!-- ne_malloc -->
-    &refreq; <!-- ne_request_create -->
     &refsess; <!-- ne_session_create -->
+    &refreq; <!-- ne_request_create -->
+    &refreqhdr; <!-- ne_add_request_header -->
+    &refresphdr; <!-- ne_add_request_header -->
     &refopts; <!-- ne_set_useragent -->
     &refreqopts; <!-- ne_set_useragent -->
     &refreqbody; <!-- ne_set_request_body_buffer -->
diff --git a/doc/ref/resphdr.xml b/doc/ref/resphdr.xml
new file mode 100644
index 0000000..af9546f
--- /dev/null
+++ b/doc/ref/resphdr.xml
@@ -0,0 +1,98 @@
+<refentry id="refresphdr">
+
+  <refmeta>
+    <refentrytitle>ne_get_response_header</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname id="ne_get_response_header">ne_get_response_header</refname>
+    <refname id="ne_response_header_iterate">ne_response_header_iterate</refname>
+    <refpurpose>functions to access response headers</refpurpose>
+  </refnamediv>
+  
+  <refsynopsisdiv>
+
+    <funcsynopsis>
+
+      <funcsynopsisinfo>#include &lt;ne_request.h&gt;</funcsynopsisinfo>
+
+      <funcprototype>
+        <funcdef>const char *<function>ne_get_response_header</function></funcdef>
+        <paramdef>ne_request *<parameter>request</parameter></paramdef>
+        <paramdef>const char *<parameter>name</parameter></paramdef>
+      </funcprototype>
+
+      <funcprototype>
+        <funcdef>void *<function>ne_response_header_iterate</function></funcdef>
+        <paramdef>ne_request *<parameter>request</parameter></paramdef>
+        <paramdef>void *<parameter>cursor</parameter></paramdef>
+        <paramdef>const char **<parameter>name</parameter></paramdef>
+        <paramdef>const char **<parameter>value</parameter></paramdef>
+      </funcprototype>
+
+    </funcsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+
+    <para>To retrieve the value of a response header field, the
+    <function>ne_get_response_header</function> function can be used,
+    and is given the name of the header to return.</para>
+
+    <para>To iterate over all the response headers returned, the
+    <function>ne_response_header_iterate</function> function can be
+    used.  This function takes a <parameter>cursor</parameter>
+    parameter which should be &null; to retrieve the first header. The
+    function stores the name and value of the next header header in
+    the <paramater>name</paramater> and <paramater>value</paramater>
+    parameters, and returns a new cursor pointer which can be passed
+    to <function>ne_response_header_iterate</function> to retrieve the
+    next header.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Return value</title>
+
+    <para><function>ne_get_response_header</function> returns a
+    string, or &null; 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 <function>ne_begin_request</function>, or
+    else, until the request object is destroyed.</para>
+
+    <para>Likewise, the cursor, names, and values returned by
+    <function>ne_response_header_iterate</function> are only valid
+    until the next call to <function>ne_begin_request</function> or
+    until the request object is destroyed.</para>
+
+  </refsect1>
+
+  <refsect1>
+    <title>Examples</title>
+
+    <para>The following code will output the value of the
+    <literal>Last-Modified</literal> header for a resource:</para>
+
+    <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);</programlisting>
+
+  </refsect1>
+
+  <refsect1>
+    <title>See also</title>
+
+    <para><xref linkend="ne_request_create"/>, <xref
+    linkend="ne_request_destroy"/>.</para>
+  </refsect1>
+
+</refentry>
+