.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NE_SESSION_CREATE" 3 "20 January 2006" "neon 0.25.5" "neon API reference"
.SH NAME
ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy \- set up HTTP sessions
.SH "SYNOPSIS"
.ad l
.hy 0

#include <ne_session\&.h>
.sp
.HP 31
ne_session\ *\fBne_session_create\fR\ (const\ char\ *\fIscheme\fR, const\ char\ *\fIhostname\fR, unsigned\ int\ \fIport\fR);
.HP 23
void\ \fBne_session_proxy\fR\ (ne_session\ *\fIsession\fR, const\ char\ *\fIhostname\fR, unsigned\ int\ \fIport\fR);
.HP 26
void\ \fBne_close_connection\fR\ (ne_session\ *\fIsession\fR);
.HP 25
void\ \fBne_session_destroy\fR\ (ne_session\ *\fIsession\fR);
.ad
.hy

.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, \fBne_sock_init\fR(3) 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 \fBne_ssl_set_verify\fR(3)) or trust the appropriate certificate (see \fBne_ssl_trust_cert\fR(3), \fBne_ssl_trust_default_ca\fR(3))\&.

.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 \fBne_request_dispatch\fR(3) 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:

.nf
ne_session *sess;
sess = ne_session_create("http", "host\&.example\&.com", 80);
/* \&.\&.\&. use sess \&.\&.\&. */
ne_session_destroy(sess);

.fi

.SH "SEE ALSO"

.PP
\fBne_ssl_set_verify\fR(3), \fBne_ssl_trust_cert\fR(3), \fBne_sock_init\fR(3)

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.