1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
<refentry id="refgetst">
<refmeta>
<refentrytitle>ne_get_status</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_get_status">ne_get_status</refname>
<refname id="ne_get_response_location">ne_get_response_location</refname>
<refname id="ne_get_response_retry_after">ne_get_response_retry_after</refname>
<refpurpose>retrieve HTTP response properties</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_request.h></funcsynopsisinfo>
<funcprototype>
<funcdef>const ne_status *<function>ne_get_status</function></funcdef>
<paramdef>const ne_request *<parameter>request</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>ne_uri *<function>ne_get_response_location</function></funcdef>
<paramdef>ne_request *<parameter>request</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>time_t <function>ne_get_response_retry_after</function></funcdef>
<paramdef>ne_request *<parameter>request</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The <function>ne_get_status</function> 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
<emphasis>successfully</emphasis> dispatched (the return value of
<function>ne_request_dispatch</function> or
<function>ne_begin_request</function> was zero).</para>
<para>If the response includes a <literal>Location</literal> header,
the <function>ne_get_response_location</function> function parses and
resolves the URI-reference relative to the request target. If a
fragment ("#fragment") is applicable to the request target, it can be
passed as an argument to allow appropriate relative resolution.</para>
<para>The <function>ne_get_response_retry_after</function> function
parses any <literal>Retry-After</literal> header included in the
response. If the header value uses a relative time, it is interpreted
relative to the time the function was invoked, rather than the time
the response was received, so the function should be used directly
after dispatching the request.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para><function>ne_get_status</function> returns a pointer to
the HTTP status object giving the result of a request. This
pointer is valid until the associated request object is
destroyed.</para>
<para><function>ne_get_response_location</function> returns a
malloc-allocated ne_uri object, or NULL if either the URI in
the Location header could not be parsed or the Location header
was not present.</para>
<para><function>ne_get_response_retry_after</function> returns
a time_t value, or zero if either no Retry-After header was
included or the header value could not be parsed.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>Display the response status code of applying the
<literal>HEAD</literal> method to some resource.</para>
<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);</programlisting>
</refsect1>
<refsect1>
<title>History</title>
<para><function>ne_get_response_location</function> is
available in &neon; 0.34.0 and later.</para>
</refsect1>
<refsect1>
<title>See also</title>
<para><xref linkend="ne_status"/>, <xref
linkend="ne_request_create"/></para>
</refsect1>
</refentry>
|
