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
51session - a logical grouping of a sequence of HTTP requests made to a
52certain server. Any requests made using the session can use a
53persistent connection, share cached authentication credentials and any
54other 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
59server to use, along with the <parameter>scheme</parameter> used to
60contact the server (usually <literal>"http"</literal>).  Before the
61first use of <function>ne_session_create</function> in a process,
62<xref linkend="ne_sock_init"/> must have been called to perform any
63global 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>
67parameter, and either register a certificate verification function
68(see <xref linkend="ne_ssl_set_verify"/>) or trust the appropriate 
69certificate (see <xref linkend="ne_ssl_trust_cert"/>, <xref
70linkend="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
80significant period of time, <function>ne_close_connection</function>
81can be called to close the connection, if one remains open.  Use of
82this function is entirely optional, but it must not be called if there
83is 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
87resources associated with the session.  Any subsequent use of the
88session 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
97request using the session is dispatched; a DNS resolution failure can
98only be detected at that time (using the <literal>NE_LOOKUP</literal>
99error code); see <xref linkend="ne_request_dispatch"/> for
100details.</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;
114sess = ne_session_create("http", "host.example.com", 80);
115/* ... use sess ... */
116ne_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>
127