     <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 &lt;ne_session.h&gt;</funcsynopsisinfo>
	  <funcprototype>
	    <funcdef>ne_session *<function>ne_session_create</function></funcdef>
	    <paramdef>const char *<parameter>scheme</parameter></paramdef>
	    <paramdef>const char *<parameter>host</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>host</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>, 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>The <parameter>host</parameter> parameter must follow
        the definition of host <literal>host</literal> in <ulink
        url="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</ulink>,
        which can be an IP-literal or registered (DNS) hostname. Valid
        examples of each: <literal>"198.51.100.42"</literal> (IPv4
        literal address), <literal>"[2001:db8::42]"</literal> (IPv6
        literal, which <emphasis>MUST</emphasis> be enclosed in square
        brackets), or <literal>"www.example.com"</literal> (DNS
        hostname). The <ulink
        url="https://www.rfc-editor.org/rfc/rfc6874">RFC 6874</ulink>
        syntax for scoped IPv6 link-local literal addresses is also
        permitted, for example <literal>"[fe80::1%25eth0]"</literal>.
        </para>

        <para>The <parameter>scheme</parameter> parameter is used to
        determine the URI for resources identified during request
        handling. Other than special handling of the string
        <literal>"https"</literal>, no other interpretation or
        checking of the <parameter>scheme</parameter> is
        performed. For example, if an HTTP-to-FTP proxy is configured,
        a scheme of <literal>"ftp"</literal> could be used to access
        resources.</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>If a hostname is passed to
<function>ne_session_create</function>, it will be 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"/>, <xref linkend="ne_session_proxy"/></para>
      </refsect1>

    </refentry>
