.\"     Title: ne_session_create
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
.\"      Date: 14 July 2007
.\"    Manual: neon API reference
.\"    Source: neon 0.26.4
.\"
.TH "NE_SESSION_CREATE" "3" "14 July 2007" "neon 0.26.4" "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"
.sp
.ft B
.nf
#include <ne_session.h>
.fi
.ft
.HP 30
.BI "ne_session *ne_session_create(const\ char\ *" "scheme" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
.HP 22
.BI "void ne_session_proxy(ne_session\ *" "session" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
.HP 25
.BI "void ne_close_connection(ne_session\ *" "session" ");"
.HP 24
.BI "void ne_session_destroy(ne_session\ *" "session" ");"
.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
.RS 4
.nf
ne_session *sess;
sess = ne_session_create("http", "host.example.com", 80);
/* ... use sess ... */
ne_session_destroy(sess);
.fi
.RE
.SH "SEE ALSO"
.PP
ne_ssl_set_verify,
ne_ssl_trust_cert,
ne_sock_init
.SH "AUTHOR"
.PP
\fBJoe Orton\fR <\&neon@webdav.org\&>
.sp -1n
.IP "" 4
Author.
.SH "COPYRIGHT"