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
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
<refentry id="refsess">
<refmeta>
<refentrytitle>ne_session_create</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_session_create">ne_session_create</refname>
<refname id="ne_close_connection">ne_close_connection</refname>
<refname id="ne_session_destroy">ne_session_destroy</refname>
<refpurpose>set up HTTP sessions</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_session.h></funcsynopsisinfo>
<funcprototype>
<funcdef>ne_session *<function>ne_session_create</function></funcdef>
<paramdef>const char *<parameter>scheme</parameter></paramdef>
<paramdef>const char *<parameter>hostname</parameter></paramdef>
<paramdef>unsigned int <parameter>port</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_close_connection</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_session_destroy</function></funcdef>
<paramdef>ne_session *<parameter>session</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>An <type>ne_session</type> 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.</para>
<para>A new HTTP session is created using the
<function>ne_session_create</function> function; the
<parameter>hostname</parameter> and <parameter>port</parameter>
parameters specify the origin server to use, along with
the <parameter>scheme</parameter> (usually <literal>"http"</literal>).
Before the first use of <function>ne_session_create</function> in a
process, <xref linkend="ne_sock_init"/> must have been called to
perform any global initialization needed by any libraries used by
&neon;.</para>
<para>To enable SSL/TLS for the session, pass the string
<literal>"https"</literal> as the <parameter>scheme</parameter>
parameter, and either register a certificate verification function
(see <xref linkend="ne_ssl_set_verify"/>) or trust the appropriate
certificate (see <xref linkend="ne_ssl_trust_cert"/>, <xref
linkend="ne_ssl_trust_default_ca"/>).</para>
<para>To use a proxy server for the session, it must be
configured (see <xref linkend="ne_session_proxy"/>) before any
requests are created from session object.</para>
<para>Further per-session options may be changed using the
<xref linkend="ne_set_session_flag"/> interface.</para>
<para>If it is known that the session will not be used for a
significant period of time, <function>ne_close_connection</function>
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.</para>
<para>Once a session has been completed,
<function>ne_session_destroy</function> must be called to
destroy the resources associated with the session. Any
subsequent use of the session pointer produces undefined
behaviour. The session object must not be destroyed until
after all associated request objects have been
destroyed.</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>The hostname passed to
<function>ne_session_create</function> is resolved when the first
request using the session is dispatched; a DNS resolution failure can
only be detected at that time (using the <literal>NE_LOOKUP</literal>
error code); see <xref linkend="ne_request_dispatch"/> for
details.</para>
</refsect1>
<refsect1>
<title>Return Values</title>
<para><function>ne_session_create</function> will return
a pointer to a new session object (and never &null;).</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>Create and destroy a session:</para>
<programlisting>ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
/* ... use sess ... */
ne_session_destroy(sess);
</programlisting>
</refsect1>
<refsect1>
<title>See Also</title>
<para><xref linkend="ne_ssl_set_verify"/>, <xref linkend="ne_ssl_trust_cert"/>, <xref linkend="ne_sock_init"/>, <xref linkend="ne_set_session_flag"/></para>
</refsect1>
</refentry>
|
