Debian Codegraph @

deps/libneon/doc/ref/sess.xml

raw
1 <refentry id="refsess">
2
3 <refmeta>
4 <refentrytitle>ne_session_create</refentrytitle>
5 <manvolnum>3</manvolnum>
6 </refmeta>
7
8 <refnamediv>
9 <refname id="ne_session_create">ne_session_create</refname>
10 <refname id="ne_close_connection">ne_close_connection</refname>
11 <refname id="ne_session_proxy">ne_session_proxy</refname>
12 <refname id="ne_session_destroy">ne_session_destroy</refname>
13 <refpurpose>set up HTTP sessions</refpurpose>
14 </refnamediv>
15
16 <refsynopsisdiv>
17
18 <funcsynopsis>
19 <funcsynopsisinfo>#include &lt;ne_session.h&gt;</funcsynopsisinfo>
20 <funcprototype>
21 <funcdef>ne_session *<function>ne_session_create</function></funcdef>
22 <paramdef>const char *<parameter>scheme</parameter></paramdef>
23 <paramdef>const char *<parameter>hostname</parameter></paramdef>
24 <paramdef>unsigned int <parameter>port</parameter></paramdef>
25 </funcprototype>
26
27 <funcprototype>
28 <funcdef>void <function>ne_session_proxy</function></funcdef>
29 <paramdef>ne_session *<parameter>session</parameter></paramdef>
30 <paramdef>const char *<parameter>hostname</parameter></paramdef>
31 <paramdef>unsigned int <parameter>port</parameter></paramdef>
32 </funcprototype>
33
34 <funcprototype>
35 <funcdef>void <function>ne_close_connection</function></funcdef>
36 <paramdef>ne_session *<parameter>session</parameter></paramdef>
37 </funcprototype>
38
39 <funcprototype>
40 <funcdef>void <function>ne_session_destroy</function></funcdef>
41 <paramdef>ne_session *<parameter>session</parameter></paramdef>
42 </funcprototype>
43
44 </funcsynopsis>
45 </refsynopsisdiv>
46
47 <refsect1>
48 <title>Description</title>
49
50 <para>An <type>ne_session</type> object represents an HTTP
51 session - a logical grouping of a sequence of HTTP requests made to a
52 certain server. Any requests made using the session can use a
53 persistent connection, share cached authentication credentials and any
54 other common attributes.</para>
55
56 <para>A new HTTP session is created using
57 <function>ne_session_create</function>, giving the
58 <parameter>hostname</parameter> and <parameter>port</parameter> of the
59 server to use, along with the <parameter>scheme</parameter> used to
60 contact the server (usually <literal>"http"</literal>). Before the
61 first use of <function>ne_session_create</function> in a process,
62 <xref linkend="ne_sock_init"/> must have been called to perform any
63 global initialization needed by any libraries used by &neon;.</para>
64
65 <para>To enable SSL/TLS for the session, pass the string
66 <literal>"https"</literal> as the <parameter>scheme</parameter>
67 parameter, and either register a certificate verification function
68 (see <xref linkend="ne_ssl_set_verify"/>) or trust the appropriate
69 certificate (see <xref linkend="ne_ssl_trust_cert"/>, <xref
70 linkend="ne_ssl_trust_default_ca"/>).</para>
71
72 <para>If an HTTP proxy server should be used for the session,
73 <function>ne_session_proxy</function> must be called giving
74 the hostname and port on which to contact the proxy.</para>
75
76 <para>Further per-session options may be changed using the
77 <xref linkend="ne_set_request_flag"/> interface.</para>
78
79 <para>If it is known that the session will not be used for a
80 significant period of time, <function>ne_close_connection</function>
81 can be called to close the connection, if one remains open. Use of
82 this function is entirely optional, but it must not be called if there
83 is a request active using the session.</para>
84
85 <para>Once a session has been completed,
86 <function>ne_session_destroy</function> must be called to destroy the
87 resources associated with the session. Any subsequent use of the
88 session pointer produces undefined behaviour.</para>
89
90 </refsect1>
91
92 <refsect1>
93 <title>Notes</title>
94
95 <para>The hostname passed to
96 <function>ne_session_create</function> is resolved when the first
97 request using the session is dispatched; a DNS resolution failure can
98 only be detected at that time (using the <literal>NE_LOOKUP</literal>
99 error code); see <xref linkend="ne_request_dispatch"/> for
100 details.</para>
101
102 </refsect1>
103
104 <refsect1>
105 <title>Return Values</title>
106 <para><function>ne_session_create</function> will return
107 a pointer to a new session object (and never &null;).</para>
108 </refsect1>
109
110 <refsect1>
111 <title>Examples</title>
112 <para>Create and destroy a session:</para>
113 <programlisting>ne_session *sess;
114 sess = ne_session_create("http", "host.example.com", 80);
115 /* ... use sess ... */
116 ne_session_destroy(sess);
117 </programlisting>
118 </refsect1>
119
120 <refsect1>
121 <title>See Also</title>
122
123 <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>
124 </refsect1>
125
126 </refentry>