127 lines
4.7 KiB
XML
127 lines
4.7 KiB
XML
<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_proxy">ne_session_proxy</refname>
|
|
<refname id="ne_session_destroy">ne_session_destroy</refname>
|
|
<refpurpose>set up HTTP sessions</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<funcsynopsis>
|
|
<funcsynopsisinfo>#include <ne_session.h></funcsynopsisinfo>
|
|
<funcprototype>
|
|
<funcdef>ne_session *<function>ne_session_create</function></funcdef>
|
|
<paramdef>const char *<parameter>scheme</parameter></paramdef>
|
|
<paramdef>const char *<parameter>hostname</parameter></paramdef>
|
|
<paramdef>unsigned int <parameter>port</parameter></paramdef>
|
|
</funcprototype>
|
|
|
|
<funcprototype>
|
|
<funcdef>void <function>ne_session_proxy</function></funcdef>
|
|
<paramdef>ne_session *<parameter>session</parameter></paramdef>
|
|
<paramdef>const char *<parameter>hostname</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
|
|
<function>ne_session_create</function>, giving the
|
|
<parameter>hostname</parameter> and <parameter>port</parameter> of the
|
|
server to use, along with the <parameter>scheme</parameter> used to
|
|
contact the server (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>
|
|
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>If an HTTP proxy server should be used for the session,
|
|
<function>ne_session_proxy</function> must be called giving
|
|
the hostname and port on which to contact the proxy.</para>
|
|
|
|
<para>Further per-session options may be changed using the
|
|
<xref linkend="ne_set_request_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.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Notes</title>
|
|
|
|
<para>The hostname passed to
|
|
<function>ne_session_create</function> is 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"/></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|