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 <ne_session.h></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