| 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 |
| 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> |