.\" ** You probably do not want to edit this file directly **
.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
.\" Instead of manually editing it, you probably should edit the DocBook XML
.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
.TH "NE_SESSION_CREATE" "3" "23 May 2006" "neon 0.26.1" "neon API reference"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy \- set up HTTP sessions
.SH "SYNOPSIS"
.PP
\fB#include <ne_session.h>\fR
.HP 30
\fBne_session\ *\fBne_session_create\fR\fR\fB(\fR\fBconst\ char\ *\fR\fB\fIscheme\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIhostname\fR\fR\fB, \fR\fBunsigned\ int\ \fR\fB\fIport\fR\fR\fB);\fR
.HP 22
\fBvoid\ \fBne_session_proxy\fR\fR\fB(\fR\fBne_session\ *\fR\fB\fIsession\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIhostname\fR\fR\fB, \fR\fBunsigned\ int\ \fR\fB\fIport\fR\fR\fB);\fR
.HP 25
\fBvoid\ \fBne_close_connection\fR\fR\fB(\fR\fBne_session\ *\fR\fB\fIsession\fR\fR\fB);\fR
.HP 24
\fBvoid\ \fBne_session_destroy\fR\fR\fB(\fR\fBne_session\ *\fR\fB\fIsession\fR\fR\fB);\fR
.SH "DESCRIPTION"
.PP
An
\fBne_session\fR
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.
.PP
A new HTTP session is created using
\fBne_session_create\fR, giving the
\fIhostname\fR
and
\fIport\fR
of the server to use, along with the
\fIscheme\fR
used to contact the server (usually
"http"). Before the first use of
\fBne_session_create\fR
in a process,
ne_sock_init
must have been called to perform any global initialization needed by any libraries used by neon.
.PP
To enable SSL/TLS for the session, pass the string
"https"
as the
\fIscheme\fR
parameter, and either register a certificate verification function (see
ne_ssl_set_verify) or trust the appropriate certificate (see
ne_ssl_trust_cert,
ne_ssl_trust_default_ca).
.PP
If an HTTP proxy server should be used for the session,
\fBne_session_proxy\fR
must be called giving the hostname and port on which to contact the proxy.
.PP
If it is known that the session will not be used for a significant period of time,
\fBne_close_connection\fR
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.
.PP
Once a session has been completed,
\fBne_session_destroy\fR
must be called to destroy the resources associated with the session. Any subsequent use of the session pointer produces undefined behaviour.
.SH "NOTES"
.PP
The hostname passed to
\fBne_session_create\fR
is resolved when the first request using the session is dispatched; a DNS resolution failure can only be detected at that time (using the
NE_LOOKUP
error code); see
ne_request_dispatch
for details.
.SH "RETURN VALUES"
.PP
\fBne_session_create\fR
will return a pointer to a new session object (and never
NULL).
.SH "EXAMPLES"
.PP
Create and destroy a session:
.sp
.nf
ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
/* ... use sess ... */
ne_session_destroy(sess);
.fi
.SH "SEE ALSO"
.PP
ne_ssl_set_verify,
ne_ssl_trust_cert,
ne_sock_init